> ## 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.

# External IDs

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:

```bash theme={null}
curl https://api.example.com/v2/entities \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "partner-biz-1234",
    "...": "..."
  }'
```

| Constraint         | Rule                                                       |
| ------------------ | ---------------------------------------------------------- |
| Length             | Up to 255 characters                                       |
| Allowed characters | Letters, digits, `-`, and `_` (pattern `^[A-Za-z0-9_-]+$`) |
| Uniqueness         | Unique per partner, per resource type                      |

## 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:

| Status         | `code`                  | Meaning                                                             |
| -------------- | ----------------------- | ------------------------------------------------------------------- |
| `409 Conflict` | `DUPLICATE_EXTERNAL_ID` | The supplied `externalId` is already in use for this resource type. |

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:

```bash theme={null}
curl "https://api.example.com/v2/entities?externalId=partner-biz-1234" \
  -H "Authorization: Bearer <api-key>"
```

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](/docs/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](/docs/idempotency).