Skip to main content
POST
Create an entity

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 400 INVALID_SONAR_TOKEN.

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.

industry
object
required
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.

address
object
required
legalAddress
object
required
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.

termsAcceptance
object
required

Your attestation that the business was shown Melio's terms of service in your UI and accepted them. Recorded with the entity and cannot be changed afterwards.

Required: an entity cannot be created without the business accepting the terms of service.

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 500 keys; each key 1 to 40 chars and may not contain square brackets ([ ], reserved for the metadata[key] filter); value ≤100 chars. The whole object must serialize to at most 128KB of JSON. Filterable via metadata[key].

website
string
description
string

Response

Entity created.

id
string
required

Opaque entity id (ent_)

type
enum<string>
required
Available options:
business
externalId
string
metadata
object

Free-form string key/value pairs stored and returned verbatim, never interpreted by Melio. Up to 500 keys; each key 1 to 40 chars and may not contain square brackets ([ ], reserved for the metadata[key] filter); value ≤100 chars. The whole object must serialize to at most 128KB of JSON. Filterable via metadata[key].

createdAt
string<date-time>
updatedAt
string<date-time>
name
string
legalName
string
businessType
string
taxInfo
object
phoneNumber
string
contact
object

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

website
string
description
string
address
object

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

legalAddress
object

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

industry
object
owner
object
termsAcceptance
object

The terms of service acceptance on file for this business. Absent when none has been recorded.