> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recotap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Map External IDs

> Bulk write external IDs into Recotap accounts matched by domain

`PATCH /accounts/external-ids`

Bulk writes your system's external IDs into existing Recotap accounts, matched by domain. Max 100 mappings per request. Designed for the **initial ID backfill**. Use [List Unmapped Accounts](list-unmapped-accounts) first to identify which accounts need IDs, then call this endpoint to write them all in one pass.

```bash theme={null}
curl -X PATCH "https://eapi.recotap.com/api/v1/accounts/external-ids" \
  -H "X-Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      { "domain": "acme.com", "externalId": "crm-001" },
      { "domain": "globex.com", "externalId": "crm-002" }
    ]
  }'
```

**Request body**

| Field      | Type  | Required | Description                    |
| ---------- | ----- | -------- | ------------------------------ |
| `mappings` | array | Yes      | Min 1, max 100 mapping objects |

**Mapping object**

| Field        | Type   | Required | Description                                                                |
| ------------ | ------ | -------- | -------------------------------------------------------------------------- |
| `domain`     | string | Yes      | Domain used to match the Recotap account e.g. `"acme.com"`                 |
| `externalId` | string | Yes      | Your system's unique ID to write onto the matched account e.g. `"crm-001"` |

**Response `data`**

```json theme={null}
{
  "matched": 2,
  "updated": 2,
  "notFound": []
}
```

| Field      | Type      | Description                                                           |
| ---------- | --------- | --------------------------------------------------------------------- |
| `matched`  | number    | Accounts found by domain                                              |
| `updated`  | number    | Accounts successfully written                                         |
| `notFound` | string\[] | Domains that did not match any Recotap account e.g. `["unknown.com"]` |

<Warning>
  Existing `externalId` values are overwritten without warning. If the same domain appears more than once in the request, the last mapping takes precedence.
</Warning>