This document describes the API and endpoint analysis done on Zendesk developer portal. The purpose of this document is to provide authentication details and API / Connector development between Zendesk and Adobe experience Launch.
This section provides a summary of all analysis activities performed on Zendesk
| Sl. No | Activity |
|---|---|
| 1 | Understanding the business of zendesk |
| 2 | Creating a test business account to access API endpoints |
| 3 | Identify Authentication API and available authentication methods |
| 4 | Connect to endpoints using Postman tool and analyze data |
| 5 | Identify all relevant available event data endpoints and the data schema |
| 6 | Select endpoints to build edge extensions. |
Zendesk is a service-first CRM company that builds software designed to improve customer relationships.
A listing of products available from Zendesk
| Names | Description |
|---|---|
| Zendesk for Service | Zendesk provides the complete customer service solution. It Provides customer interaction messaging, live chat, social, email, or voice. Builds an integrated help center and community forum. Uses automation and AI-powered bots to help customers |
| Zendesk for Sales | Zendesk Sell is an easy-to-love sales tool designed to help sales teams boost productivity, make data-driven decisions, and deliver better customer experiences. |
Zendesk Customers should obtain a Zendesk Support account (also called subdomain) and use either email (user id) and password or api token/OAuth token for API access and authentication. Click here to create the Zendesk account.
Authentication model supported is basic, API Token and OAuth.
Authorization: Bearer {YOUR_TOKEN}
| Sl.No | Authentication | Notes | |
|---|---|---|---|
| 1 | Basic | Email (userid)/password Authorization: Basic {base64-encoded-string} Eg: [email protected]:pa$$w0rd |
|
| 2 | API Token | {email_address}/token:{api_token} Authorization: Basic {base64-encoded-string} |
|
| 3 | OAuth 2.0 | Grant Type | POST /services/oauth2/token HTTP/1.1 Host: login.salesforce.com Content-length: 307 Content-type: application/x-www-form-urlencoded |
| Open Id Connect | |||
| Password credentials | https://login.salesforce.com/services/oauth2/token -d 'grant_type=password' -d 'client_id=consumer-key' -d 'client_secret=consumer-secret' -d '[email protected]' -d 'password=my-password' -X POST |
||
| Implicit flow | https://login.salesforce.com/services/oauth2/token?grant_type=password&client_id=<<client_id >>&client_secret=<<client_secret >>&username=<< username >>&password=<<password >> | ||
Note: Salesforce OAuth details are available here
| Description | Major Features | Reference Links | |
|---|---|---|---|
| Custom Data – Events API | The Events API lets you build a timeline of all your customers’ interactions from any source. An event can be any programmatic event that your application or system can associate with a user. |
|
Events API |
| Custom Data – 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. |
|
Profiles API |
| Custom Data – Custom Objects API | Custom Objects API is used to create, read, update, and delete objects that a customer creates. It can also be used to define and manage relationships with other objects, including native Zendesk objects like tickets and users. |
|
Custom Objects API |
| Ticketing | Automatically create ticket in Zendesk. . Tickets can originate from a number of channels, including email, Help Center, chat, phone call, Twitter, Facebook, or the API. All tickets have a core set of properties. |
|
Ticketing |
Requesting an Authorization via /oauth2/authorize
| Error Code | HTTP Status Code | Meaning |
|---|---|---|
| invalid_request | 400 | The request is malformed, a required parameter is missing or a parameter has an invalid value. |
| unauthorized_client | 400 | The client is not authorized. |
| access_denied | 400 | The resource owner denied the request for authorization. |
| unsupported_response_type | 400 | Unsupported response type. |
| invalid_scope | 400 | The scope is malformed or invalid. |
| server_error | 400 | Unexpected error. |
| temporarily_unavailable | 400 | The authorization server is not able to handle the request. |
Requesting an Access Token via /oauth2/token
| Error Code | HTTP Status Code | Meaning |
|---|---|---|
| invalid_request | 400 | The request is malformed, a required parameter is missing or a parameter has an invalid value. |
| invalid_client | 401 | Client authentication failed. |
| invalid_grant | 400 | Invalid authorization grant, grant invalid, grant expired, or grant revoked. |
| unauthorized_client | 400 | Client is not authorized to use the grant. |
| unsupported_grant_type | 400 | Authorization grant is not supported by the Authorization Server. |
| invalid_scope | 400 | The scope is malformed or invalid. |
Revoking a Token via /oauth2/token/revoke
| Error Code | HTTP Status Code | Meaning |
|---|---|---|
| invalid_request | 400 | The request is malformed, a required parameter is missing or a parameter has an invalid value. |
| invalid_client | 401 | Client authentication failed. |
| invalid_grant | 400 | Invalid authorization grant, grant invalid, grant expired, or grant revoked. |
| unauthorized_client | 400 | Client is not authorized to use the grant. |
| unsupported_grant_type | 400 | Authorization grant is not supported by the Authorization Server. |
| invalid_scope | 400 | The scope is malformed or invalid. |
| unsupported_token_type | 400 | The Authorization Server does not support revocation of the presented token type. |
| Endpoints | Functionality | Request | Sample cURL | Response |
|---|---|---|---|---|
| /api/v2/user_profiles/events | create an event by posting information about the event and the person who triggered it | POST | curl https://{subdomain}.zendesk.com/api/v2/user_profiles/events \ -d @event.json \ -H “Content-Type: application/json” \ -v -u {email_address}:{password} -X POST | {“status”: “received”} |
Events are represented as JSON objects with the following properties:
| Name | Type | Read-only | Mandatory | Description | |
|---|---|---|---|---|---|
| created_at | string | false | false | ISO-8601 compliant date-time reflecting the time the event was created. If not set, the API sets the value when it receives the event | |
| description | string | false | false | An event description | |
| id | string | true | false | ID of the event | |
| properties | object | false | true | A custom JSON object with details about the event. Must comply with the JSON Schema specification | |
| received_at | string | true | false | ISO-8601 compliant date-time reflecting the time the event was received | |
| source | string | false | true | Application which sent the event. Note: 'zendesk' is a protected source name for Zendesk standard events. Any attempts to use this source when creating an event results in an error | |
| type | string | false | true | Event name |
An event consists of a JSON object describing both the event and the user who triggered the event.
| Name | Type | Required | Description |
|---|---|---|---|
| profile | object | yes | The user who triggered the event. For more information, see profile object |
| event | object | yes | The event triggered by the user. For more information, see the event object |
A profile object describes a user associated with an application or system. The object has the following properties:
| Name | Type | Required | Description |
|---|---|---|---|
| source | string | yes | The product or service associated with the profile. For example, "Support", "Salesforce", or "Chat" |
| type | string | yes | The type of profile. For example, "Contact" or "Lead" |
| identifiers | object | yes | One or more user identities. See the identifiers array |
Example request body:
{
"profile": {
"source": "shoppingnow",
"type": "customer",
"identifiers": [
{
"type": "shoppingnow_id",
"value": "361959350832"
},
{
"type": "external_id",
"value": "0987654321"
}
]
},
"event": {
"source": "shoppingnow",
"type": "order_completed",
"created_at": "2018-11-05T22:26:00Z",
"description": "Added item to cart",
"properties": {
"item": {
"name": "Canon 429 EOS HD",
"query": "camera",
"price": "499.99"
},
"shipping": {
"eta_date": "2019/01/02",
"address": {
"address1": "1019 Market Street",
"city": "San Francisco",
"state": "CA",
"zipcode": "94103"
}
}
}
}
}
Bearer Token needs to be send in header if opting for oauth token for authorization
Identifiers
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".
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
| Identifier type used | If type not present | Profile Name | Example |
|---|---|---|---|
| “email” | - | Email address | [email protected] |
| “external_id” | “email” | “User” + external_id | User FooBar123 |
| “phone_number” | “external_id” | “User” + phone_number | User 1111 222 333 |
| “twitter” | “phone_number” | “Twitter user” + username | Twitter user Foobar |
| “facebook” | “twitter” | “Facebook user” + username | Facebook user Foobar |
| “sdk” | “facebook” | “SDK user” + sdk_value | SDK user FoobarSDK |
| Data Point | Required/Optional | Notes |
|---|---|---|
| source | Required | A user-defined name for the application or system where the events occur. Example: "source": "acme" |
| type | Required | A user-defined name that lets you create different kinds of events from a given source Example: "type": "cart" |
| description | Optional | A description of the event to give more context to human consumers of the data. Example: "description": "Customer enabled 2-factor authentication" |
| properties | Required | A user-defined JSON object with details about the event. A property is typically information about the event that's used in the source application or system. Example: "properties": { "passcode_preference": "SMS" } "properties": { "customer": { "display_name": "Go to customer profile...", "url": "https://crm.acme.com/customers/123" } |
| Description | Request | cURL |
|---|---|---|
| This will send event data to zendesk Events manager | POST https://d3v-dxinfosys.zendesk.com/api/v2/user_profiles/events |
curl --location --request POST 'https://d3v-dxinfosys.zendesk.com/api/v2/user_profiles/events' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 5324f6bddbd7e49d05e3e145fe9b4d759f54bce5b86e3f2cf3da7b4f204d6943' \ --header 'Cookie: __cfruid=545ea0e9c48467e724305a1b1dcb4068dca1db86-1641978609' \ --data-raw '{ "profile": { "source": "123qw33", "type": "meow", "identifiers": [ { "type": "email", "value": "[email protected]" } ] }, "event": { "source": "123qw33", "type": "meow", "description": "123 new test source event meow", "properties": { "passcode_preference": "Call" } } }' |
- How to handle error scenarios from Zendesk api response?
Boundaries:
Custom Objects, Profiles, and Events API requests per minute 250 - 1000 per minute as per plan level.
For API Reference Documentation, Click here
Zendesk Events API
| Endpoints | Functionality | Request | cURL | Response |
|---|---|---|---|---|
| /api/v2/user_profiles/events | create an event by posting information about the event and the person who triggered it | POST | curl https://{subdomain}.zendesk.com/api/v2/user_profiles/events \ -d @event.json \ -H "Content-Type: application/json" \ -v -u {email_address}:{password} -X POST | {"status": "received"} |
/api/v2/user_profiles/events? identifier={identifier_query} |
look up a customer's profile with an identifier query. | GET | curl "https://{subdomain}.zendesk.com/api/v2/user_profiles/events?identifier=acme:customer:email:[email protected]" \ -v -u {email_address}:{password} | Status: 200 OK {"events": [{"id": "5c42123e98326c0001b0b25c", "type": "2fa_enabled", "source": "acme", "description": "Customer enabled 2-factor authentication", "created_at": "2020-03-30T04:37:34.851Z", "received_at": "2019-03-30T04:37:34.851Z", "properties": { "passcode_preference": "SMS" } } ], "links": [ { "next":"" } ] } |
| /api/v2/user_profiles/{profile_id} | delete events stored in Zendesk by deleting the profile associated with the events. | DELETE | curl "https://coolbikes.zendesk.com/api/v2/user_profiles/01E1G0NJSQPNPZRV096JXKXFAA" \ -v -u [email protected]:t1retube5 -X DELETE |
Status 204 OK |
Business
AEP uses the Events API of Zendesk to store and access user event data generated in one or more systems or applications used by different organization. For example, Zendesk can track user events that occur in a company's business-to-consumer (B2C) application as well as in a third-party app that a company uses for customer billing.
Zendesk can then use the event data to build solutions that create better relationships with your customers. The possibilities include:
-
Giving your company more context about the customer in one-on-one conversations
-
Following up with the customer after certain events
-
Providing a more personalized user experience in your application or system
The Events API lets you build a timeline of all your customers' interactions from any source. An event can be any programmatic event that your application or system can associate with a user. Examples include purchase transactions, website visits, or customer service interactions. Each event is associated with a customer who triggered the event.