Anatomy of a profile

The following is a sample profile:

{
  "profile": {
    "id": "01BX5ZZKBKACTAV9WEVGEMMVRY",
    "name": "Jane Doe",
    "source": "acme",
    "type": "customer",
    "identifiers": [
      {
        "type": "email",
        "value": "[email protected]"
      }
      {
        "type": "external_id",
        "value": "myusername"
      }
    ],
    "attributes": {
      "contact_pref": "email",
      "joined": "2017"
    },
    "user_id": "321654",
    "updated_at": "2020-02-24T03:33:28.591Z",
    "created_at": "2020-02-24T03:33:28.591Z"
  }
}

A profile contains the following information:

• source
• type
• identifiers
• attributes
• user_id
• name

Each profile has a unique, system-generated id.

The source, type, and identifiers properties are required. The attributes, user_id, and name properties are optional.

All profile properties are strings, including number values.

source

A source is a user-defined name for the application or system where the identifiers listed in the profile are used.

A source could be almost any application or system where the person is known. Examples include Github, Slack, a professional association, an IT department at work, a local public library, AWS, Trello, Steam, a gaming forum, a local gym, a video streaming service, an airline, an internet provider, and so on.

Because you define the name of a source, make sure you choose a descriptive name and use it consistently in profiles.

type

A type is a user-defined name that lets you create different kinds of profiles for a given source. For example, you might want to create one set of company profiles for customers and another for employees. You could use a type named "customer" for the customer profiles and a type named "employee" for the employee profiles. All the profiles would share the same source.

You can use type to define multiple profiles for one person for one source. For example, a person can be both an employee and a customer of a company. The person would have two profiles -- one with their employee identifiers and one with their customer identifiers.

To prevent data duplication, a person should only have one profile for a given combination of type and source. For example, a person should only have one "customer" profile for a company.

Because you define type names, make sure you choose descriptive names and use them consistently with profiles.

identifiers

An identifier is used in the source application or system to recognize or establish that somebody is a particular person. For example, an email address or phone number are commonly used to uniquely identify a person in a system. The system may also generate its own identifiers such as a user id.

Each profile contains a list of one or more identifiers for a person for a given source. Each identifier is unique to the person associated with the profile.

Each identifier consists of a type and a value. You define the values of the properties. For example, you can define an identifier of type "member_id" with a value of "0634335".

Zendesk recommends using the following standard identifier types to associate profiles to Zendesk users:

• "email"
• "external_id"
• "phone_number"
• "facebook"
• "twitter"

Example:

"identifiers": [
  {
    "type": "email",
    "value": "[email protected]"
  }
  {
    "type": "external_id",
    "value": "myusername"
  }
]

The “external_id” identifier type is a unique identifier from another system. You can use the external ID to refer and find the user and associated events in Support.

However, the standard identifier types are not mandatory. To learn more, see Creating profiles.

The values of the "email" and "twitter" standard types are automatically converted to lowercase.

attributes

Attributes are optional, user-defined properties about the person. An attribute is typically information about the person that's used in the source application or system, such as a language preference.

Because you define the attribute names, make sure you choose descriptive names and use them consistently with profiles.

Example:

"attributes": {
  "contact_pref": "email",
  "joined": "2017"
}

user_id

The user_id property in a profile is the person's user id in Zendesk. See Users in the Zendesk API docs.

Normally the Zendesk system populates the user_id property when the profile is created. See Creating profiles. You can still specify a user_id yourself but it's not mandatory. Specifying a user id will associate the profile to the user in Zendesk. If the user id you specified doesn't exist in Zendesk, an anonymous Zendesk user is created and the profile is associated with the new user.

name

The name is an optional name for the person in the profile. The name is not linked to the user's name in Zendesk. If you don't specify a name property in the profile, the name is set to the value of an identifier based on predefined rules. See the table in Standard identifiers for more information.