Maintaining a Map of Internal and External IDs

In the Bulk API data model, internal IDs and client-side external IDs form a unique pair to act as a safeguard against data duplication. When you create Tulip backend data records initially with POST calls, IDs in the Tulip platform backend have no association with client-side external IDs. if you want to be able to identify records by client-side IDs, you must associate external IDs with internal IDs.

• Maintain Tulip ID that corresponds to Client-side IDs on the client-side using some persistence layer that the client would keep updated to know which record IDs exist in Tulip.
  -OR-
• Use the IdMappings endpoint for checking Tulip’s IDs before performing GET, PUT or POST calls into Tulip API.

Use the IdMappings Endpoint#

To help you maintain a mapping between external and internal IDs, the Bulk API service includes a direct endpoint for retrieving Tulip’s internal IDs: IdMappings. You can use it to check the backend for the existence of records using either Tulip internal IDs or client-side external IDs, as well as maintain the Internal IDs locally at the client side (recommended).

Use the /idMappings/{plural_resource_name} route with a GET method for fetching the mapping between internal Tulip id and externalId fields for existing records.

All ID Mappings routes are paginated (taking perPage and minId querystring parameters) so that the full set of ID Mappings can be fetched in order to look up IDs to use as foreign keys.

• Possible values for the {plural_resource_name} URL parameter are listed in the API reference for the ID Mappings resource.
• The parameter perPage specifies how many mappings to return at a time (defaulting to 1000) and minId specifies the lowest value for the id field to return in a request.
• Results are always returned sorted by id, so the next page of mappings can be requested by setting minId to be equal to one greater than the id of the last result returned in the previous response.

For a Customer resource, the following call returns all IDs that Tulip has in its table.

Note: Since you can potentially request all the IDs in a large table, the results are paginated per the API params. See the Tulip Bulk API developer documentation for details.

Sample request:#

Request Customers ID Mappings paginated

 <server_url>/dataAccess/v1/idMappings/customers?1000 
 Format: /dataAccess/v1/idMappings/{plural_resource_name}{?perPage,minId,externalId,filters} 

Response

{
    "idMappings": [
        {
            "externalId": "JERRY01",
            "id": 1
        },
        {
            "externalId": "KRAMER01",
            "id": 2
        },
        {
            "externalId": "EILENE01",
            "id": 3
        }
    ],
    "minimumId": 0,
    "perPage": 1000,
    "totalCount": 3
} 

ID Mappings routes also accept an externalId parameter but not all resources in Tulip support getting mappings by ExternalID.

Notes:

• Not all resources in Tulip support getting mappings by ExternalID. However, when specified, Tulip returns only ID Mappings for records with the specified externalId. This enables finding specific externalId references without having to page through all results.
  
• For resources that do not have a single field corresponding to an External ID, ID Mappings routes return strings containing all of the fields that are necessary to uniquely identify the record. This consists of key/value pairs separated by the = symbol, and joined together with the : symbol.

For example, a CustomerAssociation* resource may have as single record’s externalId as returned by /idMappings/customerAssociations and will look like:

idMappings Example: Getting by externalId

Format:
GET <Api-host>/dataAccess/<api-version>/idMappings/{plural_resource_name}{?perPage,minId,externalId,filters}
 
GET <Api-host>/dataAccess/<api-version>/idMappings/customerAssociations?externalId=14501

Sample Response:
customerId=14501:storeId=39:employeeId=5188:listTypeId=1

Important Note: Resources of this kind (CustomerAssociations) do not support the externalId querystring parameters and must be invoked by specifying an internal (Tulip) ID in the request body.

What’s Next?#

Bulk Data Operations with Internal & External IDs