Entities

An entity is a business you onboard and operate on behalf of: its profile, compliance details, and per-operation limitations. It combines an organization and its owner into a single record that Melio screens against KYC and compliance requirements. A business must clear those requirements before it can send payments. Only business entities are supported today. Creating an entity also requires the business’s acceptance of the Melio terms of service, which you attest to in the request. See Terms acceptance.

Endpoints

Method	Path	Description
`GET`	`/entities`	List your entities, newest first. Filter by `externalId` or `metadata`.
`POST`	`/entities`	Create an entity.
`GET`	`/entities/{entityId}`	Retrieve one entity.
`PATCH`	`/entities/{entityId}`	Update an entity (partial).

{entityId} is an entity id (ent_<uuid>) or the sentinel me, which resolves to the partner’s sole entity. The same value is accepted in the Melio-Entity-Id header used by other resources.

Entity fields

Supplied when you create an entity. Every field below except externalId, metadata, website, and description is required on create.

Field	Type	Description
`type`	enum	Entity type discriminator. Only `business` is supported.
`name`	string	Company (doing-business-as) name shown on transactions. 3 to 100 characters.
`legalName`	string	Full legal business name as it appears on the tax return. 3 to 100 characters. Immutable after creation.
`phoneNumber`	string	Business phone number. At least 9 digits.
`businessType`	enum	One of `partnership`, `sole-proprietorship`, `llc`, `corporation`, `trust`, `non-profit`, `municipality`.
`taxInfo`	object	Business tax identifier. See below. Immutable after creation.
`industry`	object	`naicsCode` (NAICS classification, digits) and optional `name`.
`contact`	object	Organization-level contact person: `firstName`, `lastName` (each at least 2 characters).
`address`	object	Physical business (mailing) address. May not be a PO box.
`legalAddress`	object	Registered legal address. Immutable after creation.
`owner`	object	The account owner. See below.
`termsAcceptance`	object	Your attestation that the business accepted the terms of service. See Terms acceptance. Write-once: set at creation.
`website`	string	Optional.
`description`	string	Optional.
`externalId`	string	Optional. Your own id for the entity, unique per partner. See External IDs.
`metadata`	object	Optional. Your own key/value context. See Metadata.

Tax info

{ "type": "ein", "identifier": "12-3456789" }

type is one of ein, ssn. ein is accepted for every business type; ssn is accepted only for sole-proprietorship and trust.
identifier is a 9-digit tax id, optionally dash-separated. It is write-only: responses return only taxInfo.identifierLast4.

Address

line1, city, state (two-letter US code), and postalCode are required; line2, aptNumber, and countryCode (defaults to US) are optional. The physical address may not be a PO box.

Owner

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "dateOfBirth": "1985-04-12"
}

firstName, lastName, email, and dateOfBirth are required and are collected for sanctions screening; phoneNumber is optional. The owner must be between 18 and 120 years old, and stricter date-of-birth validation applies when taxInfo.type is ssn.

Terms acceptance

An entity cannot be created unless the business has accepted the Melio terms of service. You own the screen where the business accepts, so termsAcceptance is your attestation that the business was shown the terms and accepted them.

{
  "accepted": true,
  "acceptedAt": "2026-09-22T14:31:07Z"
}

Both fields are required.

Field	Type	Description
`accepted`	boolean	Must be `true`. A `false` value is rejected, not recorded.
`acceptedAt`	string	When the business accepted, as you observed it (ISO-8601). See the rules below.

acceptedAt must:

Carry a UTC offset, such as Z or +09:00, so it identifies one unambiguous instant. A timestamp without an offset is rejected. Any timezone is fine.
Be within the last 90 days.
Be no more than 14 hours ahead of Melio’s clock, which allows for a skewed clock on your side.

Melio stores the acceptance as an immutable record alongside the entity, in the same operation that creates it: an entity is never created without one. Entity responses include it as termsAcceptance:

{
  "termsAcceptance": {
    "acceptedAt": "2026-09-22T14:31:07Z"
  }
}

The response returns only acceptedAt.

Creating an entity

curl -X POST https://api.melio.com/v2/entities \
  -H "api-key: <api-key>" \
  -H "Idempotency-Key: 1f8e2c3a-9b47-4d21-8a6e-2c0f5b7d9e14" \
  -H "Content-Type: application/json" \
  -d '{
    "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" },
    "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"
    },
    "termsAcceptance": {
      "accepted": true,
      "acceptedAt": "2026-09-22T14:31:07Z"
    }
  }'

A successful create returns 201 with the entity, including its id (ent_<uuid>) and the recorded termsAcceptance. Send an Idempotency-Key so retries are safe. See Idempotency.

Direct vs. platform partners

A direct partner manages a single entity: its own business. A second POST /entities returns 409 conflict_error / DUPLICATE_ENTITY.
A platform partner can create as many entities as it needs, one per business it serves. Each business must accept the terms, so send a termsAcceptance for every entity you create.

Validation errors

A missing or invalid termsAcceptance returns 400 VALIDATION_ERROR and no entity is created.

Cause	Fix
`termsAcceptance` missing, or any of its fields missing	Send both `accepted` and `acceptedAt`.
`accepted` is not `true`	The business must have accepted.
`acceptedAt` has no UTC offset, is older than 90 days, or is more than 14 hours in the future	Send an offset timestamp (`Z` or `+HH:MM`) within the allowed window. If the acceptance is older than 90 days, have the business accept again.

Conflicts

Status	`code`	Meaning
`409 Conflict`	`DUPLICATE_ENTITY`	A direct partner already has an entity.
`409 Conflict`	`DUPLICATE_EXTERNAL_ID`	The `externalId` is already used by another entity.

On DUPLICATE_EXTERNAL_ID you can recover by fetching the existing entity with GET /entities?externalId=<yourId> and reusing it, which makes queued retries safe once the idempotency-key window has elapsed.

Updating an entity

PATCH /entities/{entityId} changes only the fields you send.

curl -X PATCH https://api.melio.com/v2/entities/ent_7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "api-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Supplies Co", "website": "https://acme-supplies.example.com" }'

legalName, legalAddress, and taxInfo are fixed once the entity is created. Including any of them in a PATCH returns 400 VALIDATION_ERROR.

termsAcceptance is recorded when the entity is created and isn’t part of PATCH.

Payment eligibility

Creating an entity does not clear it to transact. Melio screens the profile against KYC and compliance requirements, and the result is exposed as per-operation limitations. Check them with GET /limitations:

curl https://api.melio.com/v2/limitations \
  -H "api-key: <api-key>" \
  -H "Melio-Entity-Id: ent_7c9e6679-7425-40de-944b-e07fc1f90ae7"

Each capability reports whether an operation (for example payment.domestic:write) is allowed, and if not, the reasons why. A MissingInformation reason lists the entity fields that still need to be supplied in missingFields:

{
  "capabilities": [
    {
      "operation": "payment.domestic:write",
      "allowed": false,
      "reasons": [
        {
          "code": "MissingInformation",
          "message": "Additional information is required before this business can send payments.",
          "missingFields": ["taxInfo"]
        }
      ]
    }
  ]
}

Resolve each missingFields entry with a PATCH /entities/{entityId}, then re-check. Rather than polling, subscribe to the api.limitation.updated webhook event and re-fetch when it fires. See Limitations for the full model, and Errors for the BUSINESS_NOT_ELIGIBLE response returned when you attempt a blocked operation.

Limitations - per-operation eligibility and reasons.
External IDs - correlate entities with your own records.
Idempotency - safe entity creation.

Get started

Core resources

Building with the API

Risk, compliance & going live

Tools

Legal

Endpoints

Entity fields

Tax info

Address

Owner

Terms acceptance

Creating an entity

Direct vs. platform partners

Validation errors

Conflicts

Updating an entity

Payment eligibility

Endpoints

Entity fields

Tax info

Address

Owner

Terms acceptance

Creating an entity

Direct vs. platform partners

Validation errors

Conflicts

Updating an entity

Payment eligibility

Related