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 a Sunshine plan, and is enabled by an admin in your account. In Admin Center, go to Sunshine > Settings (https://your_subdomain.zendesk.com/admin/sunshine/settings), select the Profiles and Events API, and click Save.

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

If you don't use Postman, you can sign up for a free account on the Postman website and download the app.

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
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, or Twitter as "email", "facebook", and "phone_number", "sdk", and "twitter" 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".

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 identifiers added to a profile is automatically added as an identity to the user in Zendesk Support. 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": "phone_number",
        "value": 12345678
      },
      {
        "type": "coolbike_id",
        "value": "0987654321"
      }
    ],
    "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:email:[email protected] profile_source=amazon, profile_type=customer, identifier_type=email, identifier_value=[email protected] GET /api/v2/user_profiles?identifier=amazon:customer:email:[email protected]hi.ne
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 profile_source:profile_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

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "created_at": "2020-02-03T01:37:16Z",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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.

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 profile_source:profile_type:identifier_type:identifier_value
Example Body
{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}}' \
  -H "Content-Type: application/json" \
  -X PUT \
  -v -u {email_address}:{password}
Example Response
Status 200

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "created_at": "2020-02-03T01:37:16Z",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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.

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": "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":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}} \
  -H "Content-Type: application/json" \
  -X PATCH \
  -v -u {email_address}:{password}
Example Response
Status 200

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "created_at": "2020-02-03T01:37:16Z",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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 Unique ID that represents a profile
Using curl
curl  "https://{subdomain}.zendesk.com/api/v2/user_profiles/{profile_id}" \
  -v -u {email_address}:{password}
Example Response
Status 200

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "created_at": "2020-02-03T01:37:16Z",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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.

Allowed For
  • Agents
Available Parameters
Name Type In Required Description
profile_id string Path true Unique ID that represents a profile
Example Body
{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "created_at": "2020-02-03T01:37:16Z",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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 Unique ID that represents a profile
Example Body
{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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 PATCH \
  -v -u {email_address}:{password}
Example Response
Status 200

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "created_at": "2020-02-03T01:37:16Z",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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 Unique ID that represents a profile
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 integer Path true Unique ID that represents a user
Using curl
curl "https://{subdomain}.zendesk.com/api/v2/users/{user_id}/profiles" \
  -v -u {email_address}:{password}
Example Response
Status 200

{
  "profile": [
    {
      "attributes": null,
      "created_at": "2020-02-03T01:37:16Z",
      "id": "fc650a2c-463a-11ea-b77f-2e728ce88125",
      "identifiers": [
        {
          "type": "email",
          "value": "[email protected]"
        },
        {
          "type": "phone_number",
          "value": "+612345678"
        }
      ],
      "membership": "gold",
      "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 integer Path true Unique ID that represents a user
Example Body
{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "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":"phone_number","value":"+612345678"}],"attributes":{"membership":"gold"}}} \
  -H "Content-Type: application/json" \
  -X PUT \
  -v -u {email_address}:{password}
Example Response
Status 200

{
  "profile": {
    "attributes": {
      "membership": "gold"
    },
    "created_at": "2020-02-03T01:37:16Z",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      },
      {
        "type": "phone_number",
        "value": "+612345678"
      }
    ],
    "name": "Jane Smith",
    "source": "company",
    "type": "contact",
    "updated_at": "2020-02-03T01:37:16Z",
    "user_id": 123456
  }
}