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", "phone_number", "sdk", "twitter", and "external_id", 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 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": "[phone]"
        }
      ],
      "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": "[phone]"
      }
    ],
    "name": "Jane Smith",
    "source": "company",
    "type": "contact",
    "updated_at": "2020-02-03T01:37:16Z",
    "user_id": "123456"
  }
}

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:identifier_type:identifier_value

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": "[phone]"
      }
    ],
    "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:identifier_type:identifier_value
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": "[phone]"
      }
    ],
    "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":"[phone]"}],"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": "[phone]"
      }
    ],
    "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:identifier_type:identifier_value

Example Body

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "type": "external_id",
        "value": "0987654321"
      },
      {
        "type": "phone_number",
        "value": "[phone]"
      }
    ],
    "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":"[phone]"}],"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": "[phone]"
      }
    ],
    "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": "[phone]"
      }
    ],
    "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":"[phone]"}],"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": "[phone]"
      }
    ],
    "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": "[phone]"
      }
    ],
    "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":"[phone]"}],"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": "[phone]"
      }
    ],
    "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:identifier_type:identifier_value

Example Body

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "type": "external_id",
        "value": "0987654321"
      },
      {
        "type": "phone_number",
        "value": "[phone]"
      }
    ],
    "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":"[phone]"}],"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": "[phone]"
      }
    ],
    "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