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 Support Enterprise and Support Suite Enterprise plans with a Sunshine plan. 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:

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:

Run in Postman

For information about using Postman for Sunshine APIs, see Setting up Postman for Sunshine API calls.

JSON Format

Profiles are represented as JSON objects which have the following keys:

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 named "sunshine_user" and associates the profile to the user by Zendesk user id.

If name in the profile object is not provided, it will default to being named "sunshine_user".

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
Available 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": "+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
Available 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": "+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
Available 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": "+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 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
Available 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
Available 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":"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
Available 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
Available 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}

Get profiles by user ID

  • GET /api/v2/users/{user_id}/profiles

Retrieves the profiles of a specified Zendesk user.

Allowed For
  • Agents
Available 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": "fc650a2c-463a-11ea-b77f-2e728ce88125",
      "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
Available 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": "+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":"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"
  }
}