Getting started with profiles

The Profiles API lets you create a single view of a customer across applications and systems. API profiles are not comprehensive user profiles as these are traditionally understood. Instead, API profiles act like name tags for a person in different external applications. The information lets you associate data streams from different applications to a single user in Zendesk.

A profile consists of one or more identifiers for a person in an application, as well as a few optional attributes about the person used in the application. Each profile is associated with a Zendesk user. If the person is not a Zendesk user, the Profiles API creates a Zendesk user record for the person when it creates their first profile.

You can use profiles to break down data silos. For example, you can use profiles with the Events API to associate events in your company's system with the person an agent is trying to help in Zendesk Support. Because the profile also contains your customer's Zendesk user id, you can pull the user's tickets, comments, and other Zendesk interactions into your company's system.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk does not support or guarantee the code. Zendesk also can't provide support for third-party technologies such as curl.

Requirements

Get a Zendesk Support account on a Zendesk Suite plan. It is automatically enabled to use the API.

You can sign up for a 14-day trial account. If you're interested in becoming a Zendesk developer partner, you can convert your trial account into a sponsored Zendesk Support account.

You'll also need agent or admin permissions in the account to use the API.

User story

You work for a fictional company named Acme. The company uses Zendesk Support for customer service and your team is tasked with building a Zendesk app for its agents. You get the following story:

As a Support agent, I'd like to see the actions the customer took in the Acme system before submitting the ticket in Support.

You decide to use the Events API to send Acme system events to Zendesk. Because the events originate in the Acme system, each event will be associated with an Acme identifier for the customer, such as an email address. The problem is that you can't associate the Acme events to a user in Support unless you can tie the user in Support to an Acme identifier.

The solution is to create a profile for the user in Support that has the user's Acme identifier. After creating the profile, you'll be able to associate events in the Acme system with the user that an agent is trying to help in Support.

Create a profile

Profiles are usually created as part of tracking user events with the Events API. The event tracking API expects a profile object with each event. However, you can also create profiles proactively with the Profiles API.

You decide to create a profile for each new Acme customer. Each profile will contain at least one Acme identifier for the customer.

You create profiles with the following endpoint:

PUT /api/v2/user_profiles?identifier={identifier_query}

The request body takes a profile object with the following JSON format:

{
  "profile": {
    "source": "acme",
    "type": "customer",
      "identifiers": [
        {
          "type": "email",
          "value": "[email protected]"
        },
        ...
      ],
      "attributes": {
        "my_property_name": "some_value",
        ...
      }
  }
}

The API path includes an identifier parameter that takes an identifier query. Example:

identifier=acme:customer:email:[email protected]

You must include an identifier query in all PUT requests, including the ones to create profiles. The identifier query plays two roles when you create a profile.

First, it defines the source and type of your new profile. In the example, the profile's source is "acme" and its type is "customer".

Second, the identifier query prevents duplicate data. The identifier query searches for a profile that has the same source-type-identifier combination as the profile you're attempting to create. If a matching combination is found, the API replaces the existing profile with yours. If not, it creates a profile.

You don't include a Zendesk user id in the profile. If the API finds a user in Zendesk who shares an identifier listed in the identifiers array in your profile, it automatically associates the new profile with that user. If the API can't find a Zendesk user who shares any of the identifiers, it creates an anonymous Zendesk user with same name as the profile name and associates the profile with the user.

To automatically associate the profile to an existing Zendesk user, the API tries to match the following identifier types in your profile with the corresponding user identity types in Zendesk: "email", "facebook", "phone_number", "sdk", and "twitter". These are known as standard identifier types. For example, to get the API to look for a match, make sure to specify the type of an email identifier in the profile as "email", not "e-mail" or "email_address".

Try it yourself

To create a profile

1. Get the user's identifiers from your user management system.

   Assume the Acme system returns the following user data for the user:

   • "email": "[email protected]"
   • "phone": 16505556789
   • "contact_preference": "email"
   • "year_joined": 2017

2. Transfer the identifier data to a JSON object that has the following format:

   {
      "profile": {
        "source": "acme",
        "type": "customer",
        "identifiers": [
          {
            "type": "email",
            "value": "[email protected]"
          },
          {
            "type": "phone_number",
            "value": "16505556789"
          }
        ],
        "attributes": {
          "contact_pref": "email",
          "joined": "2017"
        }
      }
    }

   Note: The API doesn't accept numeric values. All numbers must be strings. Example: "16505556789".

   The property names in the attributes object can be anything you like.

3. Save the JSON object in a file named profile.json.

4. In your command-line interface, navigate to the folder containing profile.json.

5. Paste the following curl command into your command-line interface and press Enter.

   curl "https://{subdomain}.zendesk.com/api/v2/user_profiles?identifier=acme:customer:email:[email protected]" \
      -d @profile.json \
      -H "Content-Type: application/json" \
      -v -u {email_address}:{password} -X PUT

   Make sure to replace the placeholder values with your own. Also make sure to enclose the URL in quotes.

   Windows users: Replace the line-continuation backslashes (\) in this and the other examples with caret (\^) characters.

   Example response

   Status: 201 Created
   
    {
    "profile": {
        "id": "03F3SW90DXZP8NY7ABG6FYS9A9",
        "user_id": "415233562812",
        "source": "acme",
        "type": "customer",
        "name": "[email protected]",
        "attributes": {
            "contact_pref": "email",
            "joined": "2017"
        },
        "identifiers": [
            {
                "type": "email",
                "value": "[email protected]"
            },
            {
                "type": "phone_number",
                "value": "16505556789"
            }
        ],
        "created_at": "2021-04-21T06:01:02Z",
        "updated_at": "2021-04-21T06:26:12Z"
      }
    }

If a Zendesk user with the email "[email protected]" or the phone number "16505556789" doesn't exist in your account, a new Zendesk user is created and the profile is associated with the user. If a user exists with either one of those identities, the profile is associated with the user.

Since a profile name is not provided in the request, the value of an identifier type is used according to the profile naming rules. The email identifier type "[email protected]" is set as the profile name. See the table in Standard identifiers for more information.

If any standard identifier in the profile is not present in the Zendesk user record, the identifier is added to the record as a Zendesk user identity. The profile record remains separate and unaffected.

Get a profile

After creating the profile for the customer, you can use it to retrieve the events triggered by that customer in the Acme system.

You retrieve the events by specifying the id of the profile in the following endpoint:

GET /api/v2/user_profiles/{profile_id}/events

The first step is getting the customer's profile to get the profile's id. You don't need to know an identifier that the customer uses in Zendesk to get the profile. You can use the identifier that the customer uses in the Acme system. You specify the identifier using an identifier query.

One identifier for Jane Doe in Acme's system is the email address "[email protected]". Therefore, your identifier query can be as follows:

acme:customer:email:[email protected]

Try it yourself

To get a profile

• Paste the following curl command into your command-line interface and press Enter.

  curl "https://{subdomain}.zendesk.com/api/v2/user_profiles?identifier=acme:customer:email:[email protected]" \
      -v -u {email_address}:{password}

  Make sure to replace the placeholder values with your own.

  Example response

  Status: 200 OK
  
   {
    "profile": {
        "id": "03F3SW90DXZP8NY7ABG6FYS9A9",
        "user_id": "415233562812",
        "source": "acme",
        "type": "customer",
        "name": "[email protected]",
        "attributes": {
            "contact_pref": "email",
            "joined": "2017"
        },
        "identifiers": [
            {
                "type": "phone_number",
                "value": "16505556789"
            },
            {
                "type": "email",
                "value": "[email protected]"
            }
        ],
        "created_at": "2021-04-21T06:41:25Z",
        "updated_at": "2021-04-21T06:41:25Z"
      }
    }

You can then use the profile id ("id": "01BX5ZZKBKACTAV9WEVGEMMVRY") to get the events triggered by the customer in the Acme system. Example:

curl https://{subdomain}.zendesk.com/api/v2/user_profiles/01BX5ZZKBKACTAV9WEVGEMMVRY/events \
  -H "Accept: application/json" \
  -v -u {email_address}:{password}

For more information, see the Events API reference docs.

In Zendesk apps, you can get profiles for a user object such as a ticket requester. See Accessing profiles in Zendesk apps.

Update a profile

You can make changes to an existing profile with a PATCH request:

PATCH /api/v2/user_profiles?identifier={identifier_query}

The endpoint uses an identifier query to select the profile to update.

Try it yourself

Jane Doe recently supplied Acme with an office phone number. You want to add the phone number to her Acme profile.

1. Specify the additional office phone number in a JSON object that has the following format:

   {
      "profile": {
        "identifiers": [
          {
            "type": "office_phone",
            "value": "16505554387"
          }
        ]
      }
    }

2. Save the JSON object in a file named patch.json.

3. Run the following PATCH request in your command-line interface:

   curl "https://{subdomain}.zendesk.com/api/v2/user_profiles?identifier=acme:customer:email:[email protected]" \
      -d @patch.json \
      -H "Content-Type: application/json" \
      -v -u {email_address}:{password} -X PATCH

   Make sure to replace the placeholder values with your own.

   Example response

   Status: 200 OK
   
    {
    "profile": {
        "id": "03F3SW90DXZP8NY7ABG6FYS9A9",
        "user_id": "415233562812",
        "source": "acme",
        "type": "customer",
        "name": "[email protected]",
        "attributes": {
            "contact_pref": "email",
            "joined": "2017"
        },
        "identifiers": [
            {
                "type": "phone_number",
                "value": "16505556789"
            },
            {
                "type": "email",
                "value": "[email protected]"
            },
            {
            "type": ""office_phone",
            "value": "16505554387"
            }
        ],
        "created_at": "2021-04-21T06:41:25Z",
        "updated_at": "2021-04-21T06:41:25Z"
      }
    }

If you want to change an identifier rather than add one, you must replace the profile. Start by making a GET request for the profile, modify the identifiers object in the response, then make a PUT request with the modified profile.

If you're getting the user's events by profile id, remember that the profile id will change.

Next steps

You created a profile for a fictional customer and then used it to list the events the customer triggered in Acme. You also updated a customer's profile.

Keep experimenting with the API. Write a small script that ties into your user management system and uses a profile to get a list of the customer's tickets in Zendesk.

If you're building a Zendesk app, you can get the events associated with a user object such as a ticket requester. See Accessing events in Zendesk apps.

For the reference docs, see Profiles API.