# External IDs in the Bimp API: mapping objects to your system

URL: https://bimpsoft.com/en/help/developers/api-external-ids/
Updated: 2026-11-06

> An external ID is a "source + externalId" pair that links a Bimp object (UUID) to an identifier in your store or marketplace. Six methods with the ExternalId suffix are available for four resources: products, counterparty, customer order and sales. The link is created by api-saveExternalId.

## What an external ID is

An external ID is a link between a Bimp object and its identifier in your system, stored as a `source` + `externalId` pair. Because of it, the integration does not have to store Bimp UUIDs: it looks up the Bimp object by its own identifier and creates the link after the first import. Typical examples are a product ID on a website, a user ID in a store, or a marketplace order number.

Link fields:

| Field | What it means |
|---|---|
| `source` | Identifier of the external system (`prom`, `rozetka`, `shopify`). Case-insensitive: the value is trimmed and converted to lower case |
| `externalId` | Identifier of the object in the external system (string) |
| UUID of the Bimp object | Named in the request according to the resource (see the table below) |

For one Bimp object you can store a separate `externalId` for each `source`.

## Which resources support external IDs

Four resources support external IDs; all paths start with `/org2/`, and the methods are `POST`.

| Resource | Path | Object UUID parameter | Reference |
|---|---|---|---|
| Products | `/org2/nomenclature/api-…ExternalId` | `nomenclatureUuid` | [nomenclature](/en/help/developers/api-reference/nomenclature/) |
| Counterparties | `/org2/counterparty/api-…ExternalId` | `counterpartyUuid` | [counterparty](/en/help/developers/api-reference/counterparty/) |
| [Customer orders](https://bimpsoft.com/en/help/sales/customer-order/) | `/org2/invoiceForCustomerPayment/api-…ExternalId` | `orderUuid` | [invoice-for-customer-payment](/en/help/developers/api-reference/invoice-for-customer-payment/) |
| Sales | `/org2/salesInvoice/api-…ExternalId` | `salesInvoiceUuid` | [sales-invoice](/en/help/developers/api-reference/sales-invoice/) |

The full set of paths for each resource is `api-saveExternalId`, `api-readExternalId`, `api-readByExternalId`, `api-readExternalIdsList`, `api-readWithoutExternalId`, `api-deleteExternalId`.

## Which methods are available

All six methods work the same way for every resource. Below, `<uuidField>` is the parameter from the table above.

| Method | What it does | Request body | `data` in the response |
|---|---|---|---|
| `api-saveExternalId` | Creates or updates a link | `<uuidField>`, `source`, `externalId` (all required) | `{"success": true}` |
| `api-readExternalId` | Returns the object's external ID for `source` | `<uuidField>`, `source` (required) | `{"externalId": "..."}` or `null` |
| `api-readByExternalId` | Finds a Bimp object by external ID | `source`, `externalId` (required) | Bimp object (see below) or `null` if there is no link |
| `api-readExternalIdsList` | List of links with filters | `pagination` (required), `source`, `<uuidField>` | array of links |
| `api-readWithoutExternalId` | Objects without a link for `source` | `pagination`, `source` (required) | array of Bimp objects |
| `api-deleteExternalId` | Deletes a link | `<uuidField>` (required), `source` | `true` |

`pagination` looks like `{"offset": 0, "count": 100}` (maximum `count` is 100), see [Limits, pagination and errors](https://bimpsoft.com/en/help/developers/api-limits/).

What the read methods return, by resource:

| Resource | `readByExternalId` and `readExternalIdsList` | `readWithoutExternalId` |
|---|---|---|
| Products | `readByExternalId`: `nomenclatureUuid`, `name`; list: `nomenclatureUuid`, `name`, `source`, `externalId` | `nomenclatureUuid`, `name` |
| Counterparty | `readByExternalId`: `counterpartyUuid`, `name`; list: `counterpartyUuid`, `name`, `source`, `externalId` | `counterpartyUuid`, `name` |
| Customer order | `orderUuid`, `date`, `number`, `source`, `externalId` | `orderUuid`, `number`, `date`, `amount`, `comment`, `counterpartyName`, `counterpartyUuid`, `currency`, `statusName` |
| Sales | `salesInvoiceUuid`, `date`, `number`, `source`, `externalId` | `salesInvoiceUuid`, `number`, `date`, `amount`, `comment`, `counterpartyName`, `counterpartyUuid`, `currency` (the list may be fuller) |

## How to map an order to your system

The typical flow for customer orders looks like this, and for products and counterparties it is identical.

1. For a new order from the store, check whether it already exists in Bimp. Call `api-readByExternalId`:

   ```bash
   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readByExternalId \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"source": "myshop", "externalId": "ORD-10452"}'
   ```

   The response `{"success": true, "data": null}` means the order has not been imported yet.

2. Create the order with the `/org2/invoiceForCustomerPayment/api-create` method, see the reference.
3. Save the link:

   ```bash
   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-saveExternalId \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"orderUuid": "<ORDER_UUID>", "source": "myshop", "externalId": "ORD-10452"}'
   ```

   ```json
   { "success": true, "data": { "success": true } }
   ```

4. To find orders not yet mapped to your system, call `api-readWithoutExternalId`:

   ```bash
   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readWithoutExternalId \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"pagination": {"offset": 0, "count": 100}, "source": "myshop"}'
   ```

Full scenarios are in [Syncing orders with an online store](https://bimpsoft.com/en/help/developers/sync-orders/) and [Syncing the product catalog](https://bimpsoft.com/en/help/developers/sync-catalog/).

## How to delete a link

The `api-deleteExternalId` method deletes the link for the given `source`. If `source` is not passed, all external links of this object are deleted. The method returns `true` both when the link was deleted and when there was none.

```bash
curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-deleteExternalId \
  -H "access-token: <COMPANY_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"nomenclatureUuid": "<NOMENCLATURE_UUID>", "source": "prom"}'
```

> [!WARNING] Without the `source` parameter, `api-deleteExternalId` deletes the links to all external systems for this object.

## FAQ

**Which Bimp objects support external IDs?**

Four resources: products (nomenclature), counterparty, customer order (invoiceForCustomerPayment) and sales (salesInvoice). The same six methods are available for each.

**What is the source parameter?**

An identifier of the external system, for example prom or rozetka. The value is case-insensitive: Bimp trims spaces and converts it to lower case. One object can have a separate external ID for each source.

**How do I find objects that are not yet mapped to my system?**

Call readWithoutExternalId of the corresponding resource with the pagination and source parameters. The method returns objects that have no link for this source.

**What does readByExternalId return if there is no link?**

A successful response with data: null, not an error.