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.

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.
`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, or itin. ein is accepted for every business type; ssn is accepted only for sole-proprietorship and trust. itin is retained for backward compatibility but is no longer accepted for any business type.
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.

Creating an entity

curl -X POST https://api.example.com/v2/entities \
  -H "Authorization: Bearer <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"
    }
  }'

A successful create returns 201 with the entity, including its id (ent_<uuid>). 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.

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.example.com/v2/entities/ent_7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer <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.

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.example.com/v2/limitations \
  -H "Authorization: Bearer <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

Endpoints

Entity fields

Tax info

Address

Owner

Creating an entity

Direct vs. platform partners

Conflicts

Updating an entity

Payment eligibility

​Endpoints

​Entity fields

​Tax info

​Address

​Owner

​Creating an entity

​Direct vs. platform partners

​Conflicts

​Updating an entity

​Payment eligibility

​Related

Endpoints

Entity fields

Tax info

Address

Owner

Creating an entity

Direct vs. platform partners

Conflicts

Updating an entity

Payment eligibility

Related