Overview

It is possible to add external identifiers for most of the core resources in the API when creating and updating them. These external identifiers are stored and returned when querying for those resources, and can be used to filter the list endpoints for those resources.

Typically when importing a record from an external system, you would include that system's id for the record in the external id, or you could store for example a internal unique project reference number in that field.

📘
External identifiers must be unique for a given type of record

External identifiers must be unique for a given type of record. For example, you can only have one project with an external identifier of abc123 and trying to create another one would be met with an error. However, you can create a person with the external identifier abc123. Creating a second person with the same external identifier would again fail.

Each resource can have as many external identifiers as necessary. The data field for storing external identifiers can be identified by looking for the array field named with the pattern external{recordName}, e.g. externalPersons. The array contains objects which have at least the key externalId for the identifier, and it can contain also other data, e.g. fullname field for person for easier identification.

Example: A person with external identifier

Let's say we're building a HR system integration, and want to store the id of the employee in the HR system as an external identifier in the person we create in Operating.

Let's say we have an employee named John Doe, with an id of abc123 in the HR system.

We can create a person in Operating using the Create Person API, with a body like this:

{
  fullname: "John Doe",
  externalPersons: [
    {
      fullname: 'John Doe',
      externalId: 'abc123'
    }
  ]
}

Next time we query either the Read Person or List Persons endpoints, the externalPersons array will be included in the response with the externalId we added. You can also filter the List Persons endpoint with externalId parameter to find a person with a given externalId.

If we want to update the external identifiers for a given person, we can call the Update Person endpoint with a body that replaces the contents of the externalPersons with something else.

📘
When updating external identifiers for a resource, your input replaces all previous contents of the external identifiers array. It doesn't add to it.

The relevant API endpoints are under Persons.