Profiles

This API is in early access. Sign up to the User Events API early access program to use it.

The Profiles API let you 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 is closely related to the People API, which gives you a view of the customers who have profiles. See People.

In addition to this API reference, the following resources are available in the Develop Help Center:

JSON Format

A profile is represented by a JSON object with the following properties.

Name Type Required Comment
source string yes The product or service associated with the profile. Examples: "support", "Salesforce", "Amazon"
type string no The type of profile. Examples: "Contact", "Lead"
identifiers object yes One or more user identities. See Identifiers object below
name string no The name of the person of the profile
photo_url string no A URL pointing to a profile picture. Example: a Gravatar URL.
attributes object no JSON Schema compliant object containing details about the profile
Location tracking

We will automatically attach a current location to the profile object if we are able to. Set do_not_track_location to true inside the attributes payload, if you don't want this feature.

Identifiers object

An identifiers object consists of one or more user identities. Each identity consists of an identifier for the application or system where the identity is used, and the identity itself. An identity can be an email address, a user name, or an alphanumerical id, among others. Example: "flickr_id": "bluebirdskies".

To add an identifier for a Zendesk Support user

  1. Specify the "source" of the profile as "support".
  2. Omit the profile's "type" property.
  3. Add a "user_id" identifier to the identifiers object.
Standard identifiers

We encourage APIs users who want to use email addresses and phone numbers as identifiers to submit them as "email" and "phone" respectively.

If there are no "email" or "phone" identifiers submitted for a given profile, the APIs show an empty string ("") to denote their absence on returned Profile objects.

Special attributes

If name or photo_url are found as part of attributes, it will be promoted up to the root level of the profile object.

Example
{
  "profile": {
    "source": "support",
    "identifiers": {
      "email": "john@doe.com",
      "user_id": "361959350832",
      "phone": ""
    },
    "name": "John Doe",
    "photo_url": "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50",
    "attributes": {
      "favorite_color": "green"
    }
  }
}

Identifier Query Syntax

You can refer to Profile and Person records in our system with the Identifier Query Syntax.

An Identifier Query consists of all necessary information that can help pinpoint the exact match out of all Profile and Person records within our system. You can supply the information about profile_source, profile_type (optional), identifier_key, and identifier_value with : as the delimiter:

  • <profile_source>:<profile_type>:<identifier_key>:<identifier_value>
  • <profile_source>:<identifier_key>:<identifier_value> (in the case of missing <profile_type>, it will be set to "default")

Some examples:

Identifier Query Explanation
support:user_id:abc123 profile_source=support, profile_type=default, identififer_key=user_id, identifier_value=abc123
mycontacts:email:docker@kube.io profile_source=mycontacts, profile_type=default, identififer_key=email, identifier_value=docker@kube.io
amazon:customer:email:sun@shi.ne profile_source=amazon, profile_type=customer, identififer_key=email, identifier_value=sun@shi.ne
mywebsite:visitor:fb_id:1000098 profile_source=mywebsite, profile_type=visitor, identififer_key=fb_id, identifier_value=1000098

Profile Sources/Types Filter Syntax

You can use the Profile Sources/Type Filter Syntax to narrow down the list of profiles to be returned when you try to retrieve a person record.

Filter on Profile Source

If you want to get back all profiles with a specific profile source and any profile types, you can just use <profile_source> in the query. For example: amazon, shopify, etc.

Filter on Profile Source and Type

If you want to get back all profiles with exact match on both profile source and profile type, you can use <profile_source>:<profile_type> in the query. For example: amazon:seller, shopify:customer, etc.

Retrieve a Profile

GET /api/sunshine/profile?identifier={identifier_query}

Returns a profile.

Make sure to url-encode the query string before sending the request. In cURL, you can use the --data-urlencode option with the -G option. The -G option ensures the command makes a GET request instead of the POST request it would otherwise make.

Allowed For
  • Agents
Using cURL
curl -G "https://{subdomain}.zendesk.com/api/sunshine/profile" \
  --data-urlencode "identifier=shopify:user_id:361959350832" \
  -H "Accept: application/json" \
  -v -u {email_address}:{password}
Example Response
Status: 200
{
  "data":{
    "person_id":"5c42123e98326c0001b0b25d",
    "source":"shopify",
    "type":"default",
    "identifiers":{
      "user_id":"361959350832"
    },
    "attributes":{}
  }
}

Search Profiles by Attribute

POST /api/sunshine/profiles/search

Returns all profiles with a matching attribute value. The endpoint expects a JSON object with the following format:

{
  "query": {
    "where": "attribute_name",
    "equals": "value"
  }
}

The attribute name can be the profile property name "source" or "type", an identifier such as "identifiers.user_id", or an attribute such as "attributes.birthday.month".

Note: Only profiles created after April 26th, 2019, are searchable using this endpoint.

Allowed For
  • Agents
Using cURL

In the following example, the cURL command reads the JSON query from a file.

data.json

{
  "query": {
    "where": "source",
    "equals": "shopify"
  }
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/profiles/search \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST

Additional examples:

{
  "query": {
    "where": "type",
    "equals": "customer"
  }
}
{
  "query": {
    "where": "identifiers.user_id",
    "equals": "12345"
  }
}
{
  "query": {
    "where": "attributes.birthday.month",
    "equals": "February"
  }
}
{
  "query": {
    "where": "email",
    "equals": "joe@zendesk.com"
  }
}
{
  "query": {
    "where": "name",
    "equals": "John Doe"
  }
}

Search Profiles with Event

POST /api/sunshine/profiles/search

Returns all profiles with a matching associated event. The endpoint expects a JSON object with the following format:

{
  "query": {
    "with": "event.property_name",
    "equals": "value"
  }
}

For information on event property names and values, see Search Events.

Note: Only profiles and events created after April 26th, 2019, are searchable using this endpoint.

Allowed For
  • Agents
Using cURL

In the following example, the cURL command reads the JSON query from a file.

data.json

{
  "query": {
    "with": "event.source",
    "equals": "zendesk.support"}
  }
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/profiles/search \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST

Additional examples:

{
  "query": {
    "with": "event.type",
    "equals": "checkout"
  }
}
{
  "query": {
    "with": "event.properties.shipping.address.zipcode",
    "equals": "94103"
  }
}

Create or Update Profile

POST /api/sunshine/profile

Creates or updates a profile.

Identifier(s) can be removed by setting the value of the particular identifier(s) to null. For example, the request payload below will remove the identifier user_id and employee_id from the profile:

{
  "profile": {
    "source": "support",
    "type": "default",
    "identifiers": {
      "organization_id": "93993-2349-34433",
      "user_id": null,
      "employee_id": null
    }
  }
}

A payload to remove identifier(s) is valid only if it contains at least one identifier with proper value

Attribute(s) can be removed by setting the value of the particular attribute(s) to null. For example, the request payload below will remove the attribute favorite_color from the profile:

{
  "profile": {
    "source": "support",
    "type": "default",
    "identifiers": {
      "user_id": "361959350832"
    },
    "attributes": {
      "favorite_color": null
    }
  }
}
Allowed For
  • Agents
Using cURL

In the following example, the cURL command reads JSON event data from a file. The request updates an existing profile by adding a property to the attributes object.

data.json

{
  "profile": {
    "source": "support",
    "type": "default",
    "identifiers": {
      "user_id": "361959350832"
    },
    "attributes": {
      "favorite_color": "green"
    }
  }
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/profile \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 202 OK

Attach Profiles to Another Person

POST /api/sunshine/profiles/attach

When a profile is created, it's attached to a new person record. As a result, profiles attached to different person records might refer to the same real-world person. Use this endpoint to move one or more profiles to a single person record known as the target person.

The endpoint takes an array of profiles you want to move, along with a target_person object. The target_person object specifies a profile that belongs to the target person. It uses an identifier query to specify the target person profile. Example:

{
  "profiles": [...],
  "target_person": {
    "identifier": "shopify:user_id:361959350832"
  }
}

If no such person exists, the endpoint returns an HTTP error code of 422.

Allowed For
  • Agents
Using cURL

In the following example, the cURL command reads JSON event data from a file. The request attaches the profile in the profiles array to the target person record that contains the profile specified by the identifier query. You can attach multiple profiles to the target person record by including multiple profiles in the profiles array.

data.json

{
  "profiles": [
    {
      "source": "support",
      "type": "default",
      "identifiers": {
        "user_id": "361959350832"
      }
    }
  ],
  "target_person": {
    "identifier": "shopify:user_id:361959350832"
  }
}

The profiles payload above can also be expressed in identifier query, such as:

{
  "profiles": [
    {
      "identifier": "source:default:user_id:361959350832"
    }
  ],
  "target_person": {
    "identifier": "shopify:user_id:361959350832"
  }
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/profiles/attach \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST
Example Response

When all of the profiles passed inside the payload are correctly formatted and do exist in the system, we will return:

Status: 202 OK

If one or more, but not all of the profiles inside the payload are incorrectly formatted or do not exist in the system, we will still return a 202, with an addition of a Warning HTTP header:

Status: 202 OK
Warning: Invalid profile(s) are found in your request. Please make sure the profile(s) are correctly formatted and currently exist in our system. The invalid profile(s) are at these indexes: "

And you will get a response body as well, with the invalid profiles indexes:

{
  invalid_profile_indexes: 
}

For example, if you're passing the below attach profiles request:

{
  "profiles": [
    {
      "identifier": "source:default:user_id:361959300000"
    },
    {
      "identifier": "source:default:user_id:361959311111"
    },
    {
      "identifier": "source:default:user_id:361959322222"
    },
    {
      "identifier": "source:default:user_id:361959333333"
    },
    {
      "identifier": "source:default:user_id:361959344444"
    }
  ],
  "target_person": {
    "identifier": "shopify:user_id:361959350832"
  }
}

And let's assume profiles with the following user_id do not exist in the system: - 361959300000 (position 0 in the request) - 361959333333 (position 3 in the request) - 361959344444 (position 4 in the request)

The response you'll be getting with this request will be:

Header:
Status: 202 OK
Warning: Invalid profile(s) are found in your request. Please make sure the profile(s) are correctly formatted and currently exist in our system. The invalid profile(s) are at these indexes: [0, 3, 4]

Body:
{
  invalid_profile_indexes: [0, 3, 4]
}

If all of your profiles are invalid or not found, then you'll be getting similar response with a 422 HTTP code, like:

Header:
Status: 422 Unprocessable Entity
Warning: Invalid profile(s) are found in your request. Please make sure the profile(s) are correctly formatted and currently exist in our system. The invalid profile(s) are at these indexes: [0, 1, 2, 3, 4]

Body:
{
  invalid_profile_indexes: [0, 1, 2, 3, 4]
}

Attach new profile to existing Person

POST /api/sunshine/profile

Profiles can also be attached to a pre-existing Person when they are created. When creating a profile, include target_person with either an identifier query or a person_id to attach the profile to the specified person.

If no such person exists, the endpoint returns an HTTP error code of 422.

Allowed For
  • Agents
Using cURL

data.json

{
    "profile": {
        "source": "zendesk",
        "identifiers": {
            "id": "def"
        },
        "target_person": {
            "identifier": "zendesk:id:123"
        }
    }
}

OR

{
    "profile": {
        "source": "zendesk",
        "type": "default",
        "identifiers": {
            "id": "def"
        },
        "target_person": {
            "id": "5cf80e85dbdb750001939d43"
        }
    }
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/profiles \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST

Attaching Profiles to another Person (DEPRECATED)

This endpoint is deprecated. Use the Attach Profiles to Another Person endpoint above instead.

POST /api/sunshine/profile

Allowed for
  • Agents
Using cURL

This example is a carry over from the previous example. Say you have 2 profiles A and B. You would like to attach profile A and B together. You will be able to specify target_person_id. You will be able to retrieve the person_id by querying for the Profile.

{
  "profile": {
    "target_person_id": "person_id_to_attach_to",
    "source": "support",
    "type": "default",
    "identifiers": {
      "user_id": "361959350832"
    }
  }
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/profile \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST

Create or Update profiles for a person in bulk

POST /api/sunshine/profile/bulk

Batch updates or creates the profiles inline for the same person.

Allowed For
  • Agents
Using cURL

In the following example, the cURL command reads JSON event data from a file. The request updates an existing profile by adding a property to the attributes object.

data.json

{
  "profiles": [
    {
      "source": "sap",
      "identifiers": {
        "email": "foo@bar.com"
      },
      "attributes": {
        "favorite_color": "blue"
      }
    },
    {
      "source": "support",
      "identifiers": {
        "user_id": "123"
      },
      "attributes": {
        "favorite_color": "red"
      }
    }
  ]
}

cURL command

curl https://{{subdomain}}.zendesk.com/api/sunshine/profile/bulk \
  -d @data.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 202 OK

Delete profile

DELETE /api/sunshine/profile?identifier={identifier_query}

Delete a profile.

Make sure to url-encode the query string before sending the request. In cURL, you can use the --data-urlencode option with the -G option. The -G option ensures the command makes a GET request instead of the POST request it would otherwise make.

Allowed For
  • Agents
Using cURL
curl "https://{subdomain}.zendesk.com/api/sunshine/profile" \
  --data-urlencode "identifier=shopify:user_id:361959350832" \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 202 OK