> ## 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 account > Creates an account for the entity. An internal account is one the entity pays from (a bank account added through Plaid or, for selected partners, by its account and routing numbers). An external account is a payee the entity pays to, reachable by ACH, paper check, domestic wire, or virtual card. Authenticate with your api-key, or with a scoped session token from `POST /accounts/link` (which can only create internal accounts). ## OpenAPI ````yaml /openapi.json post /accounts 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: /accounts: parameters: - $ref: '#/components/parameters/MelioEntityId' post: tags: - Accounts summary: Create an account description: > Creates an account for the entity. An internal account is one the entity pays from (a bank account added through Plaid or, for selected partners, by its account and routing numbers). An external account is a payee the entity pays to, reachable by ACH, paper check, domestic wire, or virtual card. Authenticate with your api-key, or with a scoped session token from `POST /accounts/link` (which can only create internal accounts). parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/MelioSonarToken' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAccountRequest' examples: internalAch: summary: >- Internal ACH account (account and routing numbers, selected partners) value: ownershipType: internal type: ach nickname: Operating account bankAccount: accountType: checking accountNumber: '000123456789' routingNumber: '021000021' internalPlaid: summary: >- Internal Plaid account (submitted by the portal via scoped token) value: ownershipType: internal type: plaid nickname: Business checking details: plaidToken: public-sandbox-0000aaaa-1111-bbbb-2222-cccc3333dddd plaidAccountId: aBcDeFgHiJkLmNoP internalCard: summary: Internal card account (vaulted token, submitted by the portal) value: ownershipType: internal type: card nickname: Corporate card details: token: 3f8a1c2e-9b4d-4e6f-8a1b-2c3d4e5f6a7b tokenProvider: basistheory cardBin: '424242' expirationMonth: '11' expirationYear: '2029' lastFourDigits: '4242' cardOwner: firstName: Jane lastName: Doe address: line1: 123 Main St city: New York state: NY postalCode: '10001' externalAch: summary: External ACH account (counterParty) value: ownershipType: external type: ach counterPartyName: Globex Manufacturing counterPartyEmail: ap@globex.example.com bankAccount: accountType: checking accountNumber: '987654321' routingNumber: '111000025' externalCheck: summary: External paper-check account (counterParty) value: ownershipType: external type: check counterPartyName: Initech counterPartyEmail: ap@initech.example.com paperCheck: address: line1: 500 Market St city: San Francisco state: CA postalCode: '94105' externalDomesticWire: summary: External domestic-wire account (counterParty) value: ownershipType: external type: domestic-wire counterPartyName: Wayne Enterprises counterPartyEmail: ap@wayne.example.com bankAccount: accountNumber: '555987654' routingNumber: '021000021' address: line1: 1007 Mountain Drive city: Gotham state: NJ postalCode: '07001' externalVirtualCard: summary: External virtual-card account (counterParty) value: ownershipType: external type: virtual-card counterPartyName: Stark Industries counterPartyEmail: payments@stark.example.com responses: '201': description: Account created. content: application/json: schema: $ref: '#/components/schemas/Account' examples: internalAch: summary: Internal ACH account value: id: acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301 ownershipType: internal type: ach nickname: Operating account isVerified: true bankAccount: accountType: checking routingNumber: '021000021' accountNumberLast4: '6789' createdAt: '2026-07-08T15:04:05Z' updatedAt: '2026-07-08T15:04:05Z' internalPlaid: summary: Internal Plaid account (returned as type ach) value: id: acct_5e6f7a8b-1c2d-4e3f-9a0b-1c2d3e4f5a6b ownershipType: internal type: ach nickname: Business checking isVerified: true bankAccount: accountType: checking routingNumber: '011401533' accountNumberLast4: '0000' createdAt: '2026-07-08T15:04:30Z' updatedAt: '2026-07-08T15:04:30Z' internalCard: summary: Internal card account value: id: acct_15648478-270c-4d9b-855c-92e0466edaa1 ownershipType: internal type: card nickname: Corporate card isVerified: true card: lastFourDigits: '1111' network: Visa expiration: 07/27 createdAt: '2026-07-08T15:04:45Z' updatedAt: '2026-07-08T15:04:45Z' externalAch: summary: External ACH account value: id: acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d ownershipType: external type: ach counterPartyName: Globex Manufacturing counterPartyEmail: ap@globex.example.com bankAccount: accountType: checking routingNumber: '111000025' accountNumberLast4: '4321' createdAt: '2026-07-08T15:05:00Z' updatedAt: '2026-07-08T15:05:00Z' externalCheck: summary: External paper-check account value: id: acct_8be01c32-9378-4aad-9f0d-229e4454259c ownershipType: external type: check counterPartyName: Initech counterPartyEmail: ap@initech.example.com paperCheck: printName: Initech address: line1: 500 Market St city: San Francisco state: CA postalCode: '94105' createdAt: '2026-07-08T15:05:15Z' updatedAt: '2026-07-08T15:05:15Z' externalDomesticWire: summary: External domestic-wire account value: id: acct_ecbd32e8-7be4-4d91-a0fd-19bf2b6eca44 ownershipType: external type: domestic-wire counterPartyName: Wayne Enterprises counterPartyEmail: ap@wayne.example.com domesticWire: routingNumber: '021000021' accountNumberLast4: '7654' address: line1: 1007 Mountain Drive city: Gotham state: NJ postalCode: '07001' createdAt: '2026-07-08T15:05:30Z' updatedAt: '2026-07-08T15:05:30Z' externalVirtualCard: summary: External virtual-card account value: id: acct_62b00efd-e3fd-4be9-9376-949257669ba9 ownershipType: external type: virtual-card counterPartyName: Stark Industries counterPartyEmail: payments@stark.example.com createdAt: '2026-07-08T15:05:45Z' updatedAt: '2026-07-08T15:05:45Z' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: > The scoped token cannot create this account type, or the business is restricted by a risk/compliance limitation from adding an internal account (BUSINESS_NOT_ELIGIBLE). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Entity not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: > Conflict: an account already exists for this resource (DUPLICATE_ACCOUNT), the `externalId` is already used by another account (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). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: conflict_error code: DUPLICATE_EXTERNAL_ID message: An account with externalId 'partner-acct-42' already exists. security: - ApiKey: [] - SessionToken: [] components: parameters: MelioEntityId: name: Melio-Entity-Id in: header required: true description: >- Entity the request operates on — an entity id (`ent_`) or `me` (the partner's sole entity). schema: type: string 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: CreateAccountRequest: description: > Create an account. `ownershipType` selects internal (an internal account the entity pays from) or external (an external account the entity pays to); `type` selects the instrument. Supported combinations: internal ach, internal card, external ach, external check, external domestic-wire, external virtual-card. oneOf: - $ref: '#/components/schemas/CreateInternalAchAccountRequest' - $ref: '#/components/schemas/CreateInternalPlaidAccountRequest' - $ref: '#/components/schemas/CreateInternalCardAccountRequest' - $ref: '#/components/schemas/CreateExternalAchAccountRequest' - $ref: '#/components/schemas/CreateExternalCheckAccountRequest' - $ref: '#/components/schemas/CreateExternalDomesticWireAccountRequest' - $ref: '#/components/schemas/CreateExternalVirtualCardAccountRequest' Account: type: object properties: id: type: string description: Opaque account id (acct_) externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' ownershipType: type: string enum: - internal - external type: type: string enum: - ach - check - card - domestic-wire - virtual-card description: Plaid-backed internal accounts are returned as ach. nickname: type: string description: Present for internal accounts. counterPartyName: type: string description: Present for external accounts. counterPartyEmail: type: string description: Counterparty (payee) email. Present for external accounts. isVerified: type: boolean description: > Present for internal accounts. For ach, `false` while micro-deposit verification is outstanding and `true` once it completes. Absent for external accounts, where verification does not apply. bankAccount: type: object description: Present when type=ach. properties: accountType: type: string enum: - checking - savings routingNumber: type: string accountNumberLast4: type: string card: type: object description: Present when type=card. properties: lastFourDigits: type: string network: type: string expiration: type: string description: MM/YY paperCheck: type: object description: Present when type=check. properties: printName: type: string address: $ref: '#/components/schemas/AddressResponse' domesticWire: type: object description: Present when type=domestic-wire. properties: routingNumber: type: string description: ABA routing number of the receiving bank accountNumberLast4: type: string address: $ref: '#/components/schemas/AddressResponse' createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' CreateInternalAchAccountRequest: type: object required: - ownershipType - type - bankAccount properties: ownershipType: type: string enum: - internal type: type: string enum: - ach externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' nickname: type: string bankAccount: type: object description: > The account and routing numbers. Available to selected partners; otherwise add the account through the Plaid link flow. When accepted, the account is created in a verified state. required: - accountNumber - routingNumber properties: accountNumber: type: string routingNumber: type: string CreateInternalPlaidAccountRequest: type: object x-internal: true required: - ownershipType - type - details description: > Created from the tokens returned by the Plaid Link SDK. Submitted by the portal using the scoped session token (Bearer) minted by POST .../accounts/link. properties: ownershipType: type: string enum: - internal type: type: string enum: - plaid externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' nickname: type: string details: type: object required: - plaidToken - plaidAccountId properties: plaidToken: type: string description: Plaid public_token from Link onSuccess plaidAccountId: type: string description: Selected account id from Link metadata CreateInternalCardAccountRequest: type: object x-internal: true required: - ownershipType - type - details description: > Created from a vaulted-card token (Basis Theory) collected client-side in the portal; the full card number never reaches the API. Submitted with the scoped session token (Bearer). properties: ownershipType: type: string enum: - internal type: type: string enum: - card externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' nickname: type: string details: type: object required: - token - cardBin - expirationMonth - expirationYear - lastFourDigits - cardOwner - address properties: token: type: string description: Vault token for the card (Basis Theory token id) tokenProvider: type: string enum: - basistheory default: basistheory cardBin: type: string description: First 6 digits expirationMonth: type: string description: MM expirationYear: type: string description: YYYY lastFourDigits: type: string cardOwner: type: object required: - firstName - lastName properties: firstName: type: string lastName: type: string address: type: object required: - line1 - city - state - postalCode properties: line1: type: string line2: type: string city: type: string state: type: string postalCode: type: string CreateExternalAchAccountRequest: type: object required: - ownershipType - type - counterPartyName - counterPartyEmail - bankAccount properties: ownershipType: type: string enum: - external type: type: string enum: - ach externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' counterPartyName: type: string description: Counterparty name counterPartyEmail: type: string format: email description: Counterparty (payee) email bankAccount: type: object required: - accountNumber - routingNumber properties: accountNumber: type: string routingNumber: type: string CreateExternalCheckAccountRequest: type: object required: - ownershipType - type - counterPartyName - counterPartyEmail - paperCheck properties: ownershipType: type: string enum: - external type: type: string enum: - check externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' counterPartyName: type: string description: Counterparty name counterPartyEmail: type: string format: email description: Counterparty (payee) email paperCheck: type: object required: - address properties: address: $ref: '#/components/schemas/Address' CreateExternalDomesticWireAccountRequest: type: object required: - ownershipType - type - counterPartyName - counterPartyEmail - bankAccount - address properties: ownershipType: type: string enum: - external type: type: string enum: - domestic-wire externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' counterPartyName: type: string description: Counterparty name counterPartyEmail: type: string format: email description: Counterparty (payee) email bankAccount: type: object required: - accountNumber - routingNumber properties: accountNumber: type: string routingNumber: type: string description: ABA routing number of the receiving bank address: allOf: - $ref: '#/components/schemas/Address' description: Counterparty address on the wire CreateExternalVirtualCardAccountRequest: type: object required: - ownershipType - type - counterPartyName - counterPartyEmail properties: ownershipType: type: string enum: - external type: type: string enum: - virtual-card externalId: $ref: '#/components/schemas/ExternalId' metadata: $ref: '#/components/schemas/Metadata' counterPartyName: type: string description: Counterparty name counterPartyEmail: type: string format: email description: Email the single-use virtual card is delivered to ExternalId: type: string description: > Your own unique identifier for the resource. Unique per partner per resource type (reusing one returns 409 DUPLICATE_EXTERNAL_ID). Distinct from the Idempotency-Key header, which dedupes the request rather than identifying the resource. maxLength: 255 pattern: ^[A-Za-z0-9_-]+$ 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 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 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). 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 securitySchemes: ApiKey: type: apiKey in: header name: api-key SessionToken: type: http scheme: bearer bearerFormat: JWT description: Scoped session token minted by POST .../accounts/link. ````