Create an entity

POST

entities

Create an entity

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'business',
    externalId: 'partner-biz-1234',
    name: 'Acme Supplies',
    legalName: 'Acme Supplies LLC',
    phoneNumber: '+12125551234',
    businessType: 'llc',
    taxInfo: {type: 'ein', identifier: '12-3456789'},
    industry: {naicsCode: '424410'},
    contact: {firstName: 'Jane', lastName: 'Doe'},
    website: 'https://acmesupplies.com',
    address: {line1: '350 5th Ave', city: 'New York', state: 'NY', postalCode: '10118'},
    legalAddress: {line1: '350 5th Ave', city: 'New York', state: 'NY', postalCode: '10118'},
    owner: {
      firstName: 'Jane',
      lastName: 'Doe',
      email: '[email protected]',
      dateOfBirth: '1985-04-12',
      phoneNumber: '+12125559876'
    }
  })
};

fetch('https://api.melio.com/v2/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.melio.com/v2/entities"

payload = {
    "type": "business",
    "externalId": "partner-biz-1234",
    "name": "Acme Supplies",
    "legalName": "Acme Supplies LLC",
    "phoneNumber": "+12125551234",
    "businessType": "llc",
    "taxInfo": {
        "type": "ein",
        "identifier": "12-3456789"
    },
    "industry": { "naicsCode": "424410" },
    "contact": {
        "firstName": "Jane",
        "lastName": "Doe"
    },
    "website": "https://acmesupplies.com",
    "address": {
        "line1": "350 5th Ave",
        "city": "New York",
        "state": "NY",
        "postalCode": "10118"
    },
    "legalAddress": {
        "line1": "350 5th Ave",
        "city": "New York",
        "state": "NY",
        "postalCode": "10118"
    },
    "owner": {
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "dateOfBirth": "1985-04-12",
        "phoneNumber": "+12125559876"
    }
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.melio.com/v2/entities \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "type": "business",
  "externalId": "partner-biz-1234",
  "name": "Acme Supplies",
  "legalName": "Acme Supplies LLC",
  "phoneNumber": "+12125551234",
  "businessType": "llc",
  "taxInfo": {
    "type": "ein",
    "identifier": "12-3456789"
  },
  "industry": {
    "naicsCode": "424410"
  },
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "website": "https://acmesupplies.com",
  "address": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118"
  },
  "legalAddress": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118"
  },
  "owner": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "dateOfBirth": "1985-04-12",
    "phoneNumber": "+12125559876"
  }
}
'

HttpResponse<String> response = Unirest.post("https://api.melio.com/v2/entities")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"business\",\n  \"externalId\": \"partner-biz-1234\",\n  \"name\": \"Acme Supplies\",\n  \"legalName\": \"Acme Supplies LLC\",\n  \"phoneNumber\": \"+12125551234\",\n  \"businessType\": \"llc\",\n  \"taxInfo\": {\n    \"type\": \"ein\",\n    \"identifier\": \"12-3456789\"\n  },\n  \"industry\": {\n    \"naicsCode\": \"424410\"\n  },\n  \"contact\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"website\": \"https://acmesupplies.com\",\n  \"address\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"legalAddress\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"owner\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\",\n    \"email\": \"[email protected]\",\n    \"dateOfBirth\": \"1985-04-12\",\n    \"phoneNumber\": \"+12125559876\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.melio.com/v2/entities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"business\",\n  \"externalId\": \"partner-biz-1234\",\n  \"name\": \"Acme Supplies\",\n  \"legalName\": \"Acme Supplies LLC\",\n  \"phoneNumber\": \"+12125551234\",\n  \"businessType\": \"llc\",\n  \"taxInfo\": {\n    \"type\": \"ein\",\n    \"identifier\": \"12-3456789\"\n  },\n  \"industry\": {\n    \"naicsCode\": \"424410\"\n  },\n  \"contact\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"website\": \"https://acmesupplies.com\",\n  \"address\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"legalAddress\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"owner\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\",\n    \"email\": \"[email protected]\",\n    \"dateOfBirth\": \"1985-04-12\",\n    \"phoneNumber\": \"+12125559876\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.melio.com/v2/entities"

	payload := strings.NewReader("{\n  \"type\": \"business\",\n  \"externalId\": \"partner-biz-1234\",\n  \"name\": \"Acme Supplies\",\n  \"legalName\": \"Acme Supplies LLC\",\n  \"phoneNumber\": \"+12125551234\",\n  \"businessType\": \"llc\",\n  \"taxInfo\": {\n    \"type\": \"ein\",\n    \"identifier\": \"12-3456789\"\n  },\n  \"industry\": {\n    \"naicsCode\": \"424410\"\n  },\n  \"contact\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"website\": \"https://acmesupplies.com\",\n  \"address\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"legalAddress\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"owner\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\",\n    \"email\": \"[email protected]\",\n    \"dateOfBirth\": \"1985-04-12\",\n    \"phoneNumber\": \"+12125559876\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "ent_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "business",
  "externalId": "partner-biz-1234",
  "createdAt": "2026-07-08T15:00:00Z",
  "updatedAt": "2026-07-08T15:00:00Z",
  "name": "Acme Supplies",
  "legalName": "Acme Supplies LLC",
  "businessType": "llc",
  "taxInfo": {
    "type": "ein",
    "identifierLast4": "6789"
  },
  "phoneNumber": "+12125551234",
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "website": "https://acmesupplies.com",
  "address": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118",
    "countryCode": "US"
  },
  "legalAddress": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118",
    "countryCode": "US"
  },
  "industry": {
    "naicsCode": "424410"
  },
  "owner": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

Authorizations

api-key

string

header

required

Headers

Idempotency-Key

string

Unique key (UUID recommended) that makes a create request safe to retry by replaying the original response; retained 24h per partner.

Maximum string length: 255

Melio-Sonar-Token

string

Signed MelioSonar session token from the initiating device, used for risk evaluation; invalid or expired tokens return 403.

Body

application/json

The business's own attributes. Allowed tax id types depend on businessType (e.g. corporation/llc/partnership → ein only; sole-proprietorship/trust → ssn or ein).

type

enum<string>

required

Entity type discriminator. Only business is supported today.

Available options:

business

name

string

required

Company (doing-business-as) name. Between 3 and 100 characters.

Required string length: 3 - 100

legalName

string

required

Full legal business name as it appears on the tax return. Between 3 and 100 characters.

Required string length: 3 - 100

phoneNumber

string

required

Business phone number. Must contain at least 9 digits.

businessType

enum<string>

required

Available options:

partnership,

sole-proprietorship,

llc,

corporation,

trust,

non-profit,

municipality

taxInfo

object

required

Business tax identifier. Allowed type values depend on the business formation type: ein is accepted for every formation type, while ssn is accepted only for sole-proprietorship and trust. itin is retained for backward compatibility but is no longer accepted for any formation type.

Hide child attributes

taxInfo.type

enum<string>

required

Available options:

ein,

ssn,

itin

taxInfo.identifier

string

required

9-digit tax identifier, optionally dash-separated (e.g. 12-3456789).

Pattern: ^[0-9]{2}-?[0-9]{7}$|^[0-9]{3}-?[0-9]{2}-?[0-9]{4}$

industry

object

required

Hide child attributes

industry.naicsCode

string

required

NAICS industry classification code (digits).

Pattern: ^[0-9]+$

industry.name

string

contact

object

required

Organization-level point of contact (a person). First and last name must be at least 2 characters and contain only letters, spaces, hyphens, dots or commas.

Hide child attributes

contact.firstName

string

required

Minimum string length: 2

contact.lastName

string

required

Minimum string length: 2

address

object

required

Hide child attributes

address.line1

string

required

Street address. Must not be a PO box for the business (physical) address.

address.city

string

required

address.state

string

required

Two-letter US state code (e.g. NY, CA).

Pattern: ^[A-Za-z]{2}$

address.postalCode

string

required

address.line2

string

address.aptNumber

string

address.countryCode

enum<string>

default:US

Available options:

US

legalAddress

object

required

Hide child attributes

legalAddress.line1

string

required

Street address. Must not be a PO box for the business (physical) address.

legalAddress.city

string

required

legalAddress.state

string

required

Two-letter US state code (e.g. NY, CA).

Pattern: ^[A-Za-z]{2}$

legalAddress.postalCode

string

required

legalAddress.line2

string

legalAddress.aptNumber

string

legalAddress.countryCode

enum<string>

default:US

Available options:

US

owner

object

required

The person who owns the entity (the account owner). Name and date of birth are required and are collected for sanctions screening; the owner must be between 18 and 120 years old. Stricter date-of-birth validation applies when the entity's tax id type is SSN.

Hide child attributes

owner.firstName

string

required

Minimum string length: 2

owner.lastName

string

required

Minimum string length: 2

owner.email

string<email>

required

owner.dateOfBirth

string<date>

required

owner.phoneNumber

string

Optional. When supplied, must contain at least 9 digits.

externalId

string

Partner's own id for the entity (unique per partner)

metadata

object

Free-form string key/value pairs stored and returned verbatim, never interpreted by Melio. Up to 50 keys; each key 1 to 40 chars and may not contain square brackets ([ ], reserved for the metadata[key] filter); value ≤100 chars. Filterable via metadata[key].

Hide child attributes

metadata.{key}

string

Maximum string length: 100

website

string

description

string

Response

Entity created.

string

required

Opaque entity id (ent_)

type

enum<string>

required

Available options:

business

externalId

string

metadata

object

Hide child attributes

metadata.{key}

string

Maximum string length: 100

createdAt

string<date-time>

updatedAt

string<date-time>

name

string

legalName

string

businessType

string

taxInfo

object

Hide child attributes

taxInfo.type

enum<string>

Available options:

ein,

ssn,

itin

taxInfo.identifierLast4

string

phoneNumber

string

contact

object

Contact as returned in responses; fields may be absent when the stored record is incomplete.

Hide child attributes

contact.firstName

string

contact.lastName

string

website

string

description

string

address

object

Address as returned in responses; fields may be absent when the stored record is incomplete.

Hide child attributes

address.line1

string

address.line2

string

address.city

string

address.state

string

address.postalCode

string

address.aptNumber

string

address.countryCode

string

legalAddress

object

Address as returned in responses; fields may be absent when the stored record is incomplete.

Hide child attributes

legalAddress.line1

string

legalAddress.line2

string

legalAddress.city

string

legalAddress.state

string

legalAddress.postalCode

string

legalAddress.aptNumber

string

legalAddress.countryCode

string

industry

object

Hide child attributes

industry.naicsCode

string

required

NAICS industry classification code (digits).

Pattern: ^[0-9]+$

industry.name

string

owner

object

Hide child attributes

owner.firstName

string

owner.lastName

string

owner.email

string

⌘I

Create an entity

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'business',
    externalId: 'partner-biz-1234',
    name: 'Acme Supplies',
    legalName: 'Acme Supplies LLC',
    phoneNumber: '+12125551234',
    businessType: 'llc',
    taxInfo: {type: 'ein', identifier: '12-3456789'},
    industry: {naicsCode: '424410'},
    contact: {firstName: 'Jane', lastName: 'Doe'},
    website: 'https://acmesupplies.com',
    address: {line1: '350 5th Ave', city: 'New York', state: 'NY', postalCode: '10118'},
    legalAddress: {line1: '350 5th Ave', city: 'New York', state: 'NY', postalCode: '10118'},
    owner: {
      firstName: 'Jane',
      lastName: 'Doe',
      email: '[email protected]',
      dateOfBirth: '1985-04-12',
      phoneNumber: '+12125559876'
    }
  })
};

fetch('https://api.melio.com/v2/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.melio.com/v2/entities"

payload = {
    "type": "business",
    "externalId": "partner-biz-1234",
    "name": "Acme Supplies",
    "legalName": "Acme Supplies LLC",
    "phoneNumber": "+12125551234",
    "businessType": "llc",
    "taxInfo": {
        "type": "ein",
        "identifier": "12-3456789"
    },
    "industry": { "naicsCode": "424410" },
    "contact": {
        "firstName": "Jane",
        "lastName": "Doe"
    },
    "website": "https://acmesupplies.com",
    "address": {
        "line1": "350 5th Ave",
        "city": "New York",
        "state": "NY",
        "postalCode": "10118"
    },
    "legalAddress": {
        "line1": "350 5th Ave",
        "city": "New York",
        "state": "NY",
        "postalCode": "10118"
    },
    "owner": {
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "dateOfBirth": "1985-04-12",
        "phoneNumber": "+12125559876"
    }
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.melio.com/v2/entities \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "type": "business",
  "externalId": "partner-biz-1234",
  "name": "Acme Supplies",
  "legalName": "Acme Supplies LLC",
  "phoneNumber": "+12125551234",
  "businessType": "llc",
  "taxInfo": {
    "type": "ein",
    "identifier": "12-3456789"
  },
  "industry": {
    "naicsCode": "424410"
  },
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "website": "https://acmesupplies.com",
  "address": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118"
  },
  "legalAddress": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118"
  },
  "owner": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "dateOfBirth": "1985-04-12",
    "phoneNumber": "+12125559876"
  }
}
'

HttpResponse<String> response = Unirest.post("https://api.melio.com/v2/entities")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"business\",\n  \"externalId\": \"partner-biz-1234\",\n  \"name\": \"Acme Supplies\",\n  \"legalName\": \"Acme Supplies LLC\",\n  \"phoneNumber\": \"+12125551234\",\n  \"businessType\": \"llc\",\n  \"taxInfo\": {\n    \"type\": \"ein\",\n    \"identifier\": \"12-3456789\"\n  },\n  \"industry\": {\n    \"naicsCode\": \"424410\"\n  },\n  \"contact\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"website\": \"https://acmesupplies.com\",\n  \"address\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"legalAddress\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"owner\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\",\n    \"email\": \"[email protected]\",\n    \"dateOfBirth\": \"1985-04-12\",\n    \"phoneNumber\": \"+12125559876\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.melio.com/v2/entities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"business\",\n  \"externalId\": \"partner-biz-1234\",\n  \"name\": \"Acme Supplies\",\n  \"legalName\": \"Acme Supplies LLC\",\n  \"phoneNumber\": \"+12125551234\",\n  \"businessType\": \"llc\",\n  \"taxInfo\": {\n    \"type\": \"ein\",\n    \"identifier\": \"12-3456789\"\n  },\n  \"industry\": {\n    \"naicsCode\": \"424410\"\n  },\n  \"contact\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"website\": \"https://acmesupplies.com\",\n  \"address\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"legalAddress\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"owner\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\",\n    \"email\": \"[email protected]\",\n    \"dateOfBirth\": \"1985-04-12\",\n    \"phoneNumber\": \"+12125559876\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.melio.com/v2/entities"

	payload := strings.NewReader("{\n  \"type\": \"business\",\n  \"externalId\": \"partner-biz-1234\",\n  \"name\": \"Acme Supplies\",\n  \"legalName\": \"Acme Supplies LLC\",\n  \"phoneNumber\": \"+12125551234\",\n  \"businessType\": \"llc\",\n  \"taxInfo\": {\n    \"type\": \"ein\",\n    \"identifier\": \"12-3456789\"\n  },\n  \"industry\": {\n    \"naicsCode\": \"424410\"\n  },\n  \"contact\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"website\": \"https://acmesupplies.com\",\n  \"address\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"legalAddress\": {\n    \"line1\": \"350 5th Ave\",\n    \"city\": \"New York\",\n    \"state\": \"NY\",\n    \"postalCode\": \"10118\"\n  },\n  \"owner\": {\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\",\n    \"email\": \"[email protected]\",\n    \"dateOfBirth\": \"1985-04-12\",\n    \"phoneNumber\": \"+12125559876\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "ent_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "business",
  "externalId": "partner-biz-1234",
  "createdAt": "2026-07-08T15:00:00Z",
  "updatedAt": "2026-07-08T15:00:00Z",
  "name": "Acme Supplies",
  "legalName": "Acme Supplies LLC",
  "businessType": "llc",
  "taxInfo": {
    "type": "ein",
    "identifierLast4": "6789"
  },
  "phoneNumber": "+12125551234",
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "website": "https://acmesupplies.com",
  "address": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118",
    "countryCode": "US"
  },
  "legalAddress": {
    "line1": "350 5th Ave",
    "city": "New York",
    "state": "NY",
    "postalCode": "10118",
    "countryCode": "US"
  },
  "industry": {
    "naicsCode": "424410"
  },
  "owner": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

Entities

Accounts

Payments

Tools

Webhooks

Authorizations

Headers

Body

Response