Using external ID with profiles
An external ID is used in Zendesk as an additional identifier such as an employee number, customer reference number, or a user ID from another system. A Zendesk user can only have one unique external ID. It is an optional attribute for Zendesk users and an identifier type for profiles. This means the external ID can be used to associate a profile to a Zendesk user. External ID values are not case sensitive.
Note: The identifier type external_id is a reserved identifier type in a profile like email, facebook, phone_number, and twitter.
This article describes several scenarios where an external ID may be used to associate a profile with a Zendesk user record.
Creating a new Zendesk user and profile using external ID
A new profile and linked Zendesk user record can be created using the Profiles API. You include optional attributes and identifier types in the request payload. To learn more about creating profiles, see Creating profiles.
Example
In this example, the Create or update profile by identifier API endpoint is used to create a profile and the Zendesk user.
Request identifier parameter
bike_shop:customer:external_id:ch105
Request body
{"profile": {"identifiers": [{"type": "external_id","value": "ch105"},{"type": "email","value": "[email protected]"}],"name": "Claire Holt"}}
Response
{"profile": {"id": "01EFBG6RD3TGWSCATKEF4ZYDZF","user_id": "418109427253","source": "bike_shop","type": "customer","name": "Claire Holt","attributes": {},"identifiers": [{"type": "external_id","value": "ch105"},{"type": "email","value": "[email protected]"}],"created_at": "2020-08-10T06:16:30Z","updated_at": "2020-08-10T06:16:30Z"}}
A profile and Zendesk user record is created with the name "Claire Holt", email "[email protected]", and external ID "ch105".
Creating a profile for a Zendesk user with no external ID
If an external ID is not defined on a Zendesk user record, you can use the Profiles API to create or modify a profile, and add an external ID to the profile and Zendesk user record.
Example
A Zendesk user record with user ID "418149471354" has no external ID. Using the Create or update profile by user ID endpoint, a new profile is created and associated to the Zendesk user.
Request user ID parameter
418149471354
Request identifier parameter
bike_shop:customer:email:jblunt@example.com
Request body
{"profile": {"identifiers": [{"type": "external_id","value": "jb001"},{"type": "email","value": "[email protected]"}],"name": "James Blunt"}}
Response
{"profile": {"id": "01EFB7CPEYF9FSKHCCRW9CKZSC","user_id": "418149471354","source": "bike_shop","type": "customer","name": "James Blunt","attributes": {},"identifiers": [{"type": "external_id","value": "jb001"},{"type": "email","value": "[email protected]"}],"created_at": "2020-08-10T03:42:27Z","updated_at": "2020-08-10T03:45:18Z"}}
A new profile is created and associated with the Zendesk user. The external ID "jb001" in the request payload is added to the profile and user record.
Creating a profile for an existing Zendesk user using external ID
You can add an external ID to a profile to link it to a Zendesk user record. When a Zendesk user record has a defined external ID but the associated profile does not, a matching external ID can be added.
Example
In this example, the Zendesk user record has an external ID "abc123" with no associated profile.
A new profile is created with the Create or update profile by identifier endpoint. The external ID in the request payload (in bold) matches the Zendesk user's external ID.
Request path parameter
laserbeam_videos:customer:external_id:abc123
Request body
{"profile": {"identifiers": [{"type": "external_id","value": "abc123"},{"type": "email","value": "[email protected]"}],"name": "Jane Doe"}}
Response
{"profile": {"id": "01EF0TQ676BARZZNPZJSW7WNJP","user_id": "403500523153","source": "laserbeam_videos","type": "default","name": "Jane Doe","attributes": {},"identifiers": [{"type": "external_id","value": "abc123"},{"type": "email","value": "[email protected]"}],"created_at": "2020-08-06T02:48:35Z","updated_at": "2020-08-10T02:59:30Z"}}
A new profile is created and associated to the Zendesk user with the external ID "abc123" defined in the request payload.
Updating the profile when the Zendesk user external ID is changed
An external ID on a Zendesk user record can be changed with the Support Users API. If a Zendesk user's external ID is changed and mismatches the associated profile's external ID, you can update the profile using one of the Profiles API PUT methods.
Example
The profile has an external ID "12345678". However, the associated Zendesk user's external ID was changed to "abc123" with the Create Or Update User API.
The profile's external_id identifier type is updated to match the external_id for the user with the Create or update profile by user ID API. The request identifier parameter specifies external_id: 1234545678 for the profile to be updated.
Request user ID parameter
018429223153
Request identifier parameter
laserbeam_videos:default:external_id:12345678
Request body
{"profile": {"identifiers": [{"type": "external_id","value": "abc123"}]"name": "Jane Doe"}}
Response
{"profile": {"id": "02B2EN9BM781EZABCPC5MAMC40","user_id": "4018429223153","source": "laserbeam_videos","type": "customer","name": "Jane Doe","attributes": {},"identifiers": [{"type": "external_id","value": "abc123"}],"created_at": "2020-08-06T02:48:35Z","updated_at": "2020-08-06T02:48:35Z"}}
The profile is updated with the external ID "abc123" in the request body, which matches the external ID of the Zendesk user record.