> ## Documentation Index > Fetch the complete documentation index at: https://developers.staging01.melio.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create an entity > Creates an entity (a business). A direct partner manages a single entity; a platform partner can create as many as it needs. ## OpenAPI ````yaml /openapi.json post /entities openapi: 3.0.3 info: title: Melio Payouts API version: '1.0' description: > Self-serve payouts API. Partners onboard an Entity, which is the business (organization plus owner, with the details required to be payment-eligible), then attach accounts (internal accounts and external accounts) and make payments. ## Resource ids Every resource has an opaque, prefixed id that is stable for the life of the resource: `ent_` (entity), `pay_` (payment), `acct_` (account, internal or external). Ids are Melio-issued; treat them as opaque strings and never parse or construct them. To attach your own identifier to a resource, use `externalId`. ## Pagination List endpoints are cursor-paginated and always return results newest-first (`createdAt` descending). The response envelope is: ```json { "data": [ /* resources */ ], "hasMore": true } ``` Page through results with `limit` (1 to 50, default 50) plus a cursor: - `startingAfter=`: return the page immediately **after** the given resource id (the next, older page). This is how you walk forward through a list. - `endingBefore=`: return the page immediately **before** the given resource id (the previous, newer page). `startingAfter` and `endingBefore` are mutually exclusive. The cursor is a resource id you already received (e.g. the `id` of the last item on the current page), not an index. Keep requesting the next page until `hasMore` is `false`. ## Filtering & sorting Ordering is fixed (newest-first); there is no `sortBy`. To narrow a list, filter it. Each list endpoint documents its own filter parameters (there is no generic query language). Date-range filters use bracket suffixes and accept RFC 3339 timestamps: `created[gte]`, `created[lte]`. Filter by your own identifier with `externalId`, and by metadata with `metadata[]=` (matches resources whose metadata contains every supplied key/value pair). Filters combine with AND and compose with pagination. ## External ids Every created resource accepts an optional `externalId`, your own unique identifier for the resource (≤255 chars, letters/digits/`-`/`_`). It is unique per partner per resource type: reusing one returns `409 DUPLICATE_EXTERNAL_ID`. Use it to correlate Melio resources with records in your system and to look resources up (`?externalId=`) without storing Melio ids. `externalId` identifies a *resource*; it is not a request-deduplication key (that is the `Idempotency-Key` header, below); the two are complementary. ## Idempotency Send an `Idempotency-Key` header on every create so retries are safe: the original response is replayed instead of creating a second resource. It is required on `POST /payments`. ## Metadata Most resources accept a `metadata` object: free-form string key/value pairs that Melio stores and returns verbatim but never interprets. Limits: up to 50 keys, key ≤40 chars, value ≤100 chars. Use it to stash your own structured context on a resource; it is also filterable (see above). ## Melio Sonar Session Token Write endpoints optionally accept a `Melio-Sonar-Token` header: a signed session token minted by the MelioSonar SDK on the end user's device, carrying device signals used for risk evaluation. Omit it when no SDK session is available. contact: name: Melio Platform External API email: platform@melio.com servers: - description: Production url: https://api.melio.com/v2 - description: Staging01 url: https://api.staging01.melio.com/v2 security: [] tags: - name: Entities description: >- A business you onboard and operate on behalf of: its profile, compliance details, and per-operation limitations. - name: Accounts description: Accounts the entity pays from (internal) and payees it pays to (external). - name: Payments description: >- Money moved from an internal account to an external account, and their lifecycle. - name: Tools description: >- Pre-flight calculators for fees, fast-payment eligibility, and delivery estimates. No resource is created. - name: Webhooks description: >- Your single endpoint for event notifications, and the events you can subscribe to. paths: /entities: post: tags: - Entities summary: Create an entity description: > Creates an entity (a business). A direct partner manages a single entity; a platform partner can create as many as it needs. parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/MelioSonarToken' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEntityRequest' example: 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: jane.doe@acmesupplies.com dateOfBirth: '1985-04-12' phoneNumber: '+12125559876' responses: '201': description: Entity created. content: application/json: schema: $ref: '#/components/schemas/Entity' example: 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: jane.doe@acmesupplies.com '400': description: Validation error (includes formation-type / tax-id-type mismatch) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: > A direct partner already has an entity (DUPLICATE_ENTITY), the `externalId` is already used by another entity (DUPLICATE_EXTERNAL_ID), or the `Idempotency-Key` was reused with a different body (IDEMPOTENCY_KEY_REUSED) / is still being processed by an earlier request (IDEMPOTENCY_KEY_IN_PROGRESS). On DUPLICATE_EXTERNAL_ID you can retrieve the existing entity with `GET /entities?externalId=` and reuse it; this makes retries (e.g. from a queue) safe once the idempotency-key window has elapsed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: duplicateEntity: summary: Direct partner already has an entity value: error: type: conflict_error code: DUPLICATE_ENTITY message: >- Entity already exists; only platform partners may create additional entities duplicateExternalId: summary: >- externalId already in use, recover with GET /entities?externalId= value: error: type: conflict_error code: DUPLICATE_EXTERNAL_ID message: An entity with externalId 'acme-123' already exists. security: - ApiKey: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: > Unique key (UUID recommended) that makes a create request safe to retry by replaying the original response; retained 24h per partner. schema: type: string maxLength: 255 MelioSonarToken: name: Melio-Sonar-Token in: header required: false description: > Signed MelioSonar session token from the initiating device, used for risk evaluation; invalid or expired tokens return 403. schema: type: string schemas: CreateEntityRequest: type: object description: > 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). required: - type - name - legalName - phoneNumber - businessType - taxInfo - industry - contact - address - legalAddress - owner properties: type: type: string enum: - business description: Entity type discriminator. Only `business` is supported today. externalId: type: string description: Partner's own id for the entity (unique per partner) metadata: $ref: '#/components/schemas/Metadata' name: type: string description: Company (doing-business-as) name. Between 3 and 100 characters. minLength: 3 maxLength: 100 legalName: type: string description: >- Full legal business name as it appears on the tax return. Between 3 and 100 characters. minLength: 3 maxLength: 100 phoneNumber: type: string description: Business phone number. Must contain at least 9 digits. businessType: type: string enum: - partnership - sole-proprietorship - llc - corporation - trust - non-profit - municipality taxInfo: $ref: '#/components/schemas/TaxInfo' industry: $ref: '#/components/schemas/Industry' contact: $ref: '#/components/schemas/Contact' website: type: string description: type: string address: $ref: '#/components/schemas/Address' legalAddress: $ref: '#/components/schemas/Address' owner: $ref: '#/components/schemas/Owner' Entity: oneOf: - $ref: '#/components/schemas/BusinessEntity' discriminator: propertyName: type mapping: business: $ref: '#/components/schemas/BusinessEntity' ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' Metadata: type: object description: > 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]`. additionalProperties: type: string maxLength: 100 maxProperties: 50 TaxInfo: type: object description: > 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. required: - type - identifier properties: type: type: string enum: - ein - ssn - itin identifier: type: string description: 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: type: object required: - naicsCode properties: naicsCode: type: string description: NAICS industry classification code (digits). pattern: ^[0-9]+$ name: type: string Contact: type: object description: > 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. required: - firstName - lastName properties: firstName: type: string minLength: 2 lastName: type: string minLength: 2 Address: type: object required: - line1 - city - state - postalCode properties: line1: type: string description: > Street address. Must not be a PO box for the business (physical) address. line2: type: string city: type: string state: type: string description: Two-letter US state code (e.g. NY, CA). pattern: ^[A-Za-z]{2}$ postalCode: type: string aptNumber: type: string countryCode: type: string enum: - US default: US Owner: type: object description: > 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. required: - firstName - lastName - email - dateOfBirth properties: firstName: type: string minLength: 2 lastName: type: string minLength: 2 email: type: string format: email dateOfBirth: type: string format: date phoneNumber: type: string description: Optional. When supplied, must contain at least 9 digits. BusinessEntity: type: object required: - id - type properties: id: type: string description: Opaque entity id (ent_) type: type: string enum: - business externalId: type: string metadata: $ref: '#/components/schemas/Metadata' createdAt: type: string format: date-time updatedAt: type: string format: date-time name: type: string legalName: type: string businessType: type: string taxInfo: type: object properties: type: type: string enum: - ein - ssn - itin identifierLast4: type: string phoneNumber: type: string contact: $ref: '#/components/schemas/ContactResponse' website: type: string description: type: string address: $ref: '#/components/schemas/AddressResponse' legalAddress: $ref: '#/components/schemas/AddressResponse' industry: $ref: '#/components/schemas/Industry' owner: type: object properties: firstName: type: string lastName: type: string email: type: string Error: type: object required: - type - code - message properties: type: type: string description: >- Coarse, machine-readable error category. Branch on this to handle a whole class of failures without enumerating every `code`. enum: - invalid_request_error - authentication_error - authorization_error - not_found_error - conflict_error - rate_limit_error - service_unavailable_error - internal_error code: type: string description: Machine-readable error code. enum: - VALIDATION_ERROR - INVALID_ACCOUNT_TYPE - INVALID_DELIVERY_PREFERENCE - MCC_REQUIRED - GOODS_RECEIVED_REQUIRED - IDEMPOTENCY_KEY_REQUIRED - FEE_CALCULATION_FAILED - UNAUTHORIZED - NOT_FOUND - NO_ACTIVE_API_KEY - DUPLICATE_ENTITY - DUPLICATE_ACCOUNT - DUPLICATE_PAYMENT - DUPLICATE_EXTERNAL_ID - ACCOUNT_IN_USE - BUSINESS_NOT_ELIGIBLE - PAYMENT_NOT_EDITABLE - PAYMENT_NOT_CANCELABLE - IDEMPOTENCY_KEY_REUSED - IDEMPOTENCY_KEY_IN_PROGRESS - IDEMPOTENCY_STORE_UNAVAILABLE - INTERNAL_ERROR message: type: string description: Human-readable error message. details: type: object description: Additional error context (e.g. field-level validation failures). ContactResponse: type: object description: >- Contact as returned in responses; fields may be absent when the stored record is incomplete. properties: firstName: type: string lastName: type: string AddressResponse: type: object description: >- Address as returned in responses; fields may be absent when the stored record is incomplete. properties: line1: type: string line2: type: string city: type: string state: type: string postalCode: type: string aptNumber: type: string countryCode: type: string securitySchemes: ApiKey: type: apiKey in: header name: api-key ````