> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/embedded-ap-ar/home/common-concepts/foreign-id/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

A **foreign ID** is a unique identifier provided by your system to reference objects such as invoices, customers, payments, etc. within Mercoa. Unlike platform-generated IDs, foreign IDs allow you to map your internal records to Mercoa platform objects for easier integration and reconciliation.

## API Usage

You can provide foreign IDs when creating, retrieving, or updating objects via supported API endpoints. The following object types support foreign IDs:

* [Entity](/common-concepts/entities)
* [Entity Group](/common-concepts/entity-groups)
* [Entity User](/common-concepts/entity-users)
* [Invoice](/accounts-payable/invoices)
* Payment Method (via [Bring Your Own Payments](/common-concepts/payment-methods/bring-your-own-payments))

For each of these object types, the foreign ID can be used in place of the Mercoa object ID, in both URL path parameters as well as query parameters. Foreign IDs are also included in webhook notifications for easier mapping.

**Important:**

* Each foreign ID **must be unique** within its specified scope (typically per creator entity/account). Attempting to reuse a foreign ID within the same scope will result in an error.
* Foreign IDs are typically visible to external systems via webhooks and API responses, making them suitable for cross-system mapping.

## Use Cases

### Using Foreign IDs with the SDK

Traditionally, you would store the Mercoa-generated ID in your database after creating a user or entity. On each later API call, you would then retrieve and use this Mercoa ID.

```js
// Your application's user ID
const your_DB_id = 'user-123';

// Retrieve the Mercoa ID from your database
const { mercoaId } = await getUser(your_DB_id);

// Use the Mercoa ID to interact with Mercoa via the SDK
const mercoaUser = await mercoa.user.get(mercoaId);
```

When using foreign IDs with Mercoa, you skip storing Mercoa IDs entirely. Just use your existing database ID directly -- Mercoa handles the mapping internally.

```js
// Your application's user ID
const your_DB_id = 'user-123';

// Use your DB ID directly with the Mercoa SDK -- no need to store Mercoa IDs
const mercoaUser = await mercoa.user.get(your_DB_id);
```

### Using Foreign IDs with the API

If you prefer to use the API, the traditional approach is similar: you pass a Mercoa-generated ID in your request URLs.

```http
GET /api/users/{mercoaId}
Authorization: Bearer <your_api_key>
```

With Mercoa, you can use your own foreign ID directly in all API routes that accept an entity ID. Just substitute your database's user ID in place of a Mercoa ID.

```http
GET /api/users/{foreignId}
Authorization: Bearer <your_api_key>
```

## Examples

### Create a User with a Custom Foreign ID

```http
POST /api/users
Content-Type: application/json

{
  "foreignId": "user-123",
  "email": "user@example.com",
  "name": "John Doe"
}
```

### Retrieve a User by Foreign ID

```http
GET /api/users/user-123
```

### Update an Entity by Foreign ID

```http
PUT /api/entities/user-123
Content-Type: application/json

{
  "name": "Acme Corporation",
  "address": "123 Main St, Cityville, NY",
}
```

### Create a Payment with a Foreign ID

```http
POST /api/payments
Content-Type: application/json

{
  "foreignId": "payment-321",
  "amount": 5000,
  "currency": "USD",
  "payerEntityId": "entity-456",
  "invoiceId": "invoice-789"
}
```

## Summary

Mercoa's API and SDK fully support using your system's foreign IDs (`foreignId`) in place of Mercoa IDs, across major endpoints. This feature streamlines your integration and allows you to build fintech solutions with less overhead and greater flexibility. For the most complete and current list of supported endpoints, see the official Mercoa [API Reference documentation](/api-reference/).