Profiles API
The Profiles API allows you to create a single view of a customer across applications and systems. A profile can contain the various identities of a user in different applications and systems.
This API has a direct relationship to a Zendesk user.
The Profiles API is available on the Suite Team plan and above. It is activated in the Admin Center by an admin.
In addition to this API reference, the following resources are available in the Develop Help Center:
- To get started, see Getting started with Sunshine profiles in the Develop Help Center
- To learn more about using the API, see the Profiles API developer guide
- To ask questions, provide answers, and join discussions, visit the Sunshine Profiles & Events API community
Run in Postman
You can import the Profiles API endpoints as a collection into your Postman app, then try out different requests to learn how the API works. Click the following button to download the collection:
For information about using Postman for Sunshine APIs, see Setting up Postman for Sunshine API calls.
JSON Format
Profiles are represented as JSON objects with the following properties:
| Name | Type | Read-only | Mandatory | Description |
|---|---|---|---|---|
| attributes | object | false | true | JSON schema compliant object containing details about the profile |
| created_at | string | true | false | An auto-generated datetime of when the object was updated |
| id | string | true | false | Profile ID |
| identifiers | array | false | true | The identifier for the application or system where the identity is used |
| name | string | false | false | The person's name for the profile |
| source | string | false | true | The application or system associated to the profile. Note that the value 'zendesk' is reserved for future use. |
| type | string | false | true | The profile type |
| updated_at | string | true | false | An auto-generated datetime of when the object was updated |
| user_id | string | false | false | Zendesk user ID that the profile belongs to |
Identifiers array
The identifiers array consists of one or more values used to identify a person in an application or system. Each identifier consists of a type and a value property which are arbitrary. For example, an identifier can be of type "member_id" with a value of "0634335".
Standard identifiers
It is recommended to submit the identifier types email, Facebook, phone, SDK, Twitter, or external ID as "email", "facebook", "phonenumber", "sdk", "twitter", and "externalid", respectively. If a Zendesk user identity has been previously created with a "google" type property, it will be internally matched with an identifier type of "email". When the value for identifier types "email" and "twitter" are added or modified, any upper case letters are automatically converted to lower case.
Each profile is associated with a Zendesk user. When creating a profile, the API first looks for a Zendesk user who has a Zendesk identity that matches a standard identifier in the new profile. If a match is found, it associates the profile to the Zendesk user by Zendesk user id (user_id). If no match is found, it creates an anonymous Zendesk user and associates the profile to the user by Zendesk user id.
If the name in the profile object is not provided, the value of an identifier type will be used for the profile name according to the following rules:
| Identifier type used | If type not present | Profile name | Example |
|---|---|---|---|
| "email" | email address | Â "[email protected]" | |
| "external_id" | "email" | "User " + external id | "User FooBar123" |
| "phone_number" | "external_id" | "User " + phone number | "User 0411 555 666" |
| "twitter" | "phone_number" | "Twitter user " + username | "Twitter user FooBar" |
| "facebook" | "twitter" | "Facebook user " + username | "Facebook user FooBar" |
| "sdk" | "facebook" | "SDK user " + sdk value | "SDK user FooBarSDK" |
If none of the listed identifier types are present, the first identifier present in the identifiers object is used. The profile name is set as the identifier's "{type} user {value}". Example: 'Shado user FooBar'.
Note: Any email, phone, Facebook, SDK or Twitter identifier added to a profile is automatically added as an identity to the user in Zendesk Support. Any external ID identifier added to a profile is automatically added as the external_id attribute on the Zendesk user. Please verify the identifier type belongs to the user before creating a profile or submitting changes.
Example
{"profile": {"id": "01BX5ZZKBKACTAV9WEVGEMMVRY","name": "Jane Smith","source": "coolbikes","type": "rider","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "coolbike_id","value": "0987654321"},{"type": "phone_number","value": 12345678}],"attributes": {"favorite_color": "red","height": "103cm"},"user_id": "123456","updated_at": "2019-12-24T03:33:28.591Z","created_at": "2019-12-24T03:33:28.591Z"}}
Identifier queries
You can reference profile records in Zendesk using identifier queries. You specify an identifier query as a URL parameter in a request.
An identifier query contains the necessary information to find a match of profile records within our system. You must specify a profile source, profile type, identifier type, and identifier value with : as the delimiter:
<profile_source>:<profile_type>:<identifier_key>:<identifier_value>
Examples
| Identifier query | Explanation | Endpoint example |
|---|---|---|
mysystem:customer:system_id:abc123 |
profile_source=mysystem, profile_type=customer, identifier_type=system_id, identifier_value=abc123 |
GET /api/v2/user_profiles?identifier=mysystem:customer:system_id:abc123 |
mycontacts:default:email:[email protected] |
profile_source=mycontacts, profile_type=customer, identifier_type=email, identifier_value=[email protected] |
GET /api/v2/user_profiles?identifier=mycontacts:customer:email:[email protected] |
amazon:customer:external_id:0987654321 |
profile_source=amazon, profile_type=customer, identifier_type=external_id, identifier_value=0987654321 |
GET /api/v2/user_profiles?identifier=amazon:customer:external_id:0987654321 |
mywebsite:visitor:fb_id:1000098 |
profile_source=mywebsite, profile_type=visitor, identifier_type=fb_id, identifier_value=1000098 |
GET /api/v2/user_profiles?identifier=website:visitor:fb_id:1000098 |
Get profile by identifier
GET /api/v2/user_profiles?identifier={identifier}
Returns a profile that matches the given identifier query criteria. See Using identifier queries with profiles.
Allowed For
- Agents
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| identifier | string | Query | true | An identifier query to identify the profile. Uses the format of source:type:identifiertype:identifiervalue |
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles?identifier=company:contact:email:[email protected]" \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profile": {"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}}
Create or update profile by identifier
PUT /api/v2/user_profiles?identifier={identifier}
Creates or updates a profile. See Creating Sunshine profiles for details.
The required identifier path parameter takes an identifier query. See Using identifier queries with profiles.
If the profile has more than one identifier, all the identifiers should belong to a single user and a single profile.
When identifiers for multiple users are provided, the request will fail.
When creating a new profile for a user exceeds the maximum number of profiles, the request will fail.
Note that the source 'zendesk' is reserved and cannot be used to create a profile.
Allowed For
- Agents
Access also depends on agent role permissions set in Support > People > Roles > People.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| identifier | string | Query | true | An identifier query to identify the profile. Uses the format of source:type:identifiertype:identifiervalue |
Example Body
{"profile": {"attributes": {"membership": "gold"},"identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith"}}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles?identifier=company:contact:email:[email protected]" \-d '{"profile":{"name":"Jane Smith","source":"company","type":"contact","user_id":123456,"identifiers":[{"type":"email","value":"[email protected]"},{"type":"external_id","value":"0987654321"},{"type":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}}' \-H "Content-Type: application/json" \-X PUT \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profile": {"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}}
Partial update profile by identifier
PATCH /api/v2/user_profiles?identifier={identifier}
Partially updates the specified profile. See Patching a profile.
The required identifier path parameter takes an identifier query. See Using identifier queries with profiles.
If the profile has more than one identifier, all the identifiers should belong to a single user and a single profile.
When identifiers for multiple users are provided, the request fails.
Note that the source 'zendesk' is reserved and cannot be used to create a profile.
Allowed For
- Agents
Access also depends on agent role permissions set in Support > People > Roles > People.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| identifier | string | Query | true | An identifier query to identify the profile. Uses the format of source:type:identifiertype:identifiervalue |
Example Body
{"profile": {"attributes": {"membership": "gold"},"identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith"}}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles?identifier=company:contact:email:[email protected]" \-d '{"profile":{"name":"JaneSmith","source":"company","type":"contact","user_id":123456,"identifiers":[{"type":"email","value":"[email protected]"},{"type":"external_id","value":"0987654321"},{"type":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}}' \-H "Content-Type: application/json" \-X PATCH \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profile": {"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}}
Get profile by profile ID
GET /api/v2/user_profiles/{profile_id}
Returns a profile for a given profile ID.
Allowed For
- Agents
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| profile_id | string | Path | true | Sunshine profile ID |
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}" \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profile": {"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}}
Update profile by profile ID
PUT /api/v2/user_profiles/{profile_id}
Updates a profile specified by a profile ID. If the profile has more than one identifier, all the identifiers should belong to a single user and a single profile. When identifiers for multiple users are provided, the request fails.
Note that the source 'zendesk' is reserved and cannot be used to create a profile.
Allowed For
- Agents
Access also depends on agent role permissions set in Support > People > Roles > People.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| profile_id | string | Path | true | Sunshine profile ID |
Example Body
{"profile": {"attributes": {"membership": "gold"},"identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith"}}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}" \-d '{"profile":{"name":"JaneSmith","source":"company","type":"contact","user_id":123456,"identifiers":[{"type":"email","value":"[email protected]"},{"type":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}}' \-H "Content-Type: application/json" \-X PUT \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profile": {"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}}
Partial update profile by profile ID
PATCH /api/v2/user_profiles/{profile_id}
Partially updates of a profile with profile ID using a JSON merge patch. See Patching a profile.
If the profile has more than one identifier, all the identifiers should belong to a single user and a single profile. When identifiers for multiple users are provided, the request fails.
Allowed For
- Agents
Access also depends on agent role permissions set in Support > People > Roles > People.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| profile_id | string | Path | true | Sunshine profile ID |
Example Body
{"profile": {"attributes": {"membership": "gold"},"identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith"}}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}" \-d '{"profile":{"name":"Jane Smith","source":"company","type":"contact","user_id":123456,"identifiers":[{"type":"email","value":"[email protected]"},{"type":"external_id","value":"0987654321"},{"type":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}}' \-H "Content-Type: application/json" \-X PATCH \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profile": {"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}}
Delete profile by profile ID
DELETE /api/v2/user_profiles/{profile_id}
Deletes the profile specified by the profile ID.
Allowed For
- Agents
Access also depends on agent role permissions set in Support > People > Roles > People.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| profile_id | string | Path | true | Sunshine profile ID |
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}" \-X DELETE \-v -u {email_address}:{password}
Example Response
Status 204 No Content
Get profiles by user ID
GET /api/v2/users/{user_id}/profiles
Retrieves the profiles of a specified Zendesk user.
Allowed For
- Agents
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| user_id | string | Path | true | Zendesk user ID |
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/users/{user_id}/profiles" \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profiles": [{"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}]}
Create or update profile by user ID
PUT /api/v2/users/{user_id}/profiles?identifier={identifier}
Creates or updates a profile of a Zendesk user.
The required identifier path parameter takes an identifier query. See Using identifier queries with profiles.
When creating a new profile for a user exceeds the maximum number of profiles, the request will fail.
Allowed For
- Agents
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| identifier | string | Query | true | An identifier query to identify the profile. Uses the format of source:type:identifiertype:identifiervalue |
| user_id | string | Path | true | Zendesk user ID |
Example Body
{"profile": {"attributes": {"membership": "gold"},"identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith"}}
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/users/{user_id}/profiles?identifier=company:contact:email:[email protected]" \-d '{"profile":{"name":"JaneSmith","source":"company","type":"contact","user_id":123456,"identifiers":[{"type":"email","value":"[email protected]"},{"type":"external_id","value":"0987654321"},{"type":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}}' \-H "Content-Type: application/json" \-X PUT \-v -u {email_address}:{password}
Example Response
Status 200 OK{"profile": {"attributes": {"membership": "gold"},"created_at": "2020-02-03T01:37:16Z","id": "01ARZ3NDEKTSV4RRFFQ69G5FAV","identifiers": [{"type": "email","value": "[email protected]"},{"type": "external_id","value": "0987654321"},{"type": "phone_number","value": "+612345678"}],"name": "Jane Smith","source": "company","type": "contact","updated_at": "2020-02-03T01:37:16Z","user_id": "123456"}}