Skip to main content
Every resource created through the Payouts API has an object, Melio-issued id (ent_, acct_, pay_). In addition, every created resource accepts an optional externalId: your own unique identifier for the resource. Use it to correlate Melio resources with records in your own system and to look resources up without having to store Melio ids.

​
Setting an external ID

Send externalId when you create a resource:

​
Uniqueness and conflicts

An externalId is unique per partner, per resource type. The same value can be used once for an entity and once for a payment, but reusing it for two resources of the same type is rejected: This makes externalId a useful recovery tool. If a create fails with DUPLICATE_EXTERNAL_ID, the resource already exists. Fetch it with a lookup (below) and reuse it rather than creating a duplicate.

​
Looking resources up by external ID

Each list endpoint accepts an externalId query parameter that returns the single resource matching your id:
Because the id is unique per resource type, this returns at most one resource.

​
External IDs in webhooks

Webhook deliveries include your external IDs so you can route an event to your own records without a follow-up GET:
  • externalId - your id for the affected resource, if one was set.
  • entityExternalId - your id for the business entity that holds the resource (present on account and payment events).
See Webhooks for the full delivery shape.

​
External IDs vs. idempotency keys

An externalId identifies a resource; it is not a request-deduplication key. Deduplicating a retried create request is the job of the Idempotency-Key header. The two are complementary and are often sent together on a create: the Idempotency-Key makes the request safe to retry, and the externalId names the resulting resource. See Idempotency.