JSON API Tutorial

Introduction

With Unified Messaging, we also upgraded our available JSON APIs - integrating Userlike into your own platforms and workflows has never been easier. Below you find the general documentation as well as a detailed description of each API resource available.

We prepared some cURL-based examples. With the help of the cURL tool you can test drive our API quickly from the command line. This should give you a straightforward understanding how to use our API.

TopicDescription
Resource endpointsAvailable resource endpoints of the JSON API
AuthenticationAccessing the API
Request headersAdditional Request Headers
Rate limitsAPI rate limits
Result paginationNumber of results per requests to the list endpoint of a resource
Result filteringFilter list endpoints for specific resource items
Searching resourcesSearch list endpoints for specific resource items
Conversation resourceWork with Conversation resources
Contact resourceWork with Contact resources
Operator resourceWork with Operator resources
Code samplesWorking (python) code examples

Resource endpoints

Currently, the following resource endpoints are available using the Userlike JSON API:

Resource endpointsDescriptionAllowed methods
http://www.userlike.com/api/um/conversations/
http://www.userlike.com/api/um/conversations/{id}/
List of conversations

Single conversation
GET | DELETE

GET | PATCH | DELETE
http://www.userlike.com/api/um/contacts/
http://www.userlike.com/api/um/contacts/{id}/
List of contacts

Single contact
GET | DELETE

GET | PATCH | DELETE
http://www.userlike.com/api/um/operators/
http://www.userlike.com/api/um/operators/{id}/
http://www.userlike.com/api/um/operators/{id}/slots/
List of operators

Single operator

Single operator's slot data
GET

GET | PATCH | DELETE

GET | PATCH | DELETE

The specifics for each resource are described further below, after the introduction of the general features of the JSON API.

Authentication

All API requests must be authenticated with an API token, i.e. the API token must be passed as an Authorization header with each request:

Userlike offers two types of authentication tokens: the "Customer authentication token", allowing access to the resources of all organizations, and the "Organization authentication token", allowing access to the resouces of a single organization.

For most setups, using one or the other does not make a real difference. Customers of our "Flex" plan, however, will appreciate the granular access to their different organizations when using the Customer authentication token.

Organization authentication token

The Organization authentication token gives you access to the resources (conversations, contacts, ...) of a single organization. You can find it in the "API Settings", under the "Config" section of your Dashboard:

Customer authentication token

The Customer authentication token by default gives you access to the resources (conversations, contacts, ...) of your default organization. You can find it in the "API Settings", under the "Company" section of your Dashboard":

But when you need to access the resources of a different organization, you can now simply provide the extra header "Userlike-Organization-Id" with your request, there indicating the id of the desired organization:

To find out the IDs of your different organizations, go to your "Organization" overview and start editing the respective organization. In the URL bar you can now see the ID of the organization:

If you provide a wrong Organization ID, the request will again be made against your default organization resources.

Additional request headers

Content-Type: required for PATCH requests

When you want to update existing resources, you have to send a PATCH request with a valid JSON body. Additionally, you must specify the content type of your request being "application/json" - otherwise your body data cannot be processed correctly.

USERLIKE-OPERATOR-ID: switching operator context

By default, API requests run in the context of the account's operator. If you want to limit the privileges of requests made via the JSON API without affecting the capabilities of the owner, you can make your requests in the context of a less privileged operator.

In these cases we'd recommend the creation of a dedicated API operator, to whom you then assign a (customized) role with the desired set of capabilities. For all API request you can now send this operator's ID by setting the custom "Userlike-Operator-Id" header:

All requests made this way will check for your "API" operator's capabilities before performing any actions. This way you could ensure, for example, that no destructive operations are allowed via the API. Learn more about roles and capabilities.

API rate limits

You can make up to 1000 API requests per day to a specific resource of an organization. After the resource limit is reached, you'll receive an response with HTTP status code 429.

Each resource has it's own limit, as does each organization. This means that requesting conversations of organization A does not affect the count for requesting contacts from the same organization - nor does it affect the count for requesting conversations of organization B. The following three example calls all add to a different call counter:

In this context, requests for a specific resource of an organization (e.g. conversations) all add to the same count, no matter if they are made to the list or single endpoint, or what HTTP method is used. So a "DELETE" of a single conversation adds a hit to the same counter as does a "GET" to the same organization's conversation list endpoint. The following three example calls all add to the same call counter:

Resource (per organization)Methodscombined requests/day
http://www.userlike.com/api/um/conversations/
http://www.userlike.com/api/um/conversations/{id}/
GET | DELETE

GET | PATCH | DELETE
1000
http://www.userlike.com/api/um/contacts/
http://www.userlike.com/api/um/contacts/{id}/
GET | DELETE

GET | PATCH | DELETE
1000
http://www.userlike.com/api/um/operators/
http://www.userlike.com/api/um/operators/{id}/
http://www.userlike.com/api/um/operators/{id}/slots/
GET | DELETE

GET | PATCH | DELETE

GET | PATCH | DELETE
1000

Filtering

You can filter the results of each resource's list endpoint. These filters are specific to each resource, so we'll explain them for each resource further below. Here we'll only highlight some details that apply to filters in general.

Ordering filter

By default, the list of resources returned by all list endpoints are sorted by their ID, in descending order - meaning that the most recently created resources are coming first.

For some resource list endpoints, you can provide an alternative ordering by providing the field by which the result list should be ordered. Prefixing the ordering field with an "-" (minus) sign will reverse the order from "ascending" to "descending":

For each resource list endpoint we'll indicate which fields are available for alternative ordering.

Filters and pagination

Applying filters to an API requests means that the pagination is applied to the filtered result set, and the previous and next links provided in a filtered response will already have these filter set. This means that you can easily browse the single pages of a filtered result set by following these links.

Combining filters

You can apply more than one filter to an API request. The single filters are "ANDed" together, i.e. they will return all resource items that match each filter criterion.

The more filters you add, the more specific your request will be and chances are that there are no items matching all criteria.

Exclude IDs

For any requests, to any resource endpoints, you can provide a "blacklist" of resource IDs. Just provide a comma-separated string with all IDs you wish to exclude via the "exclude_ids" filter. Resource(s) thus specified will not be fetched, updated or deleted.

This allows for more effective bulk actions, e.g. fetching all conversations that are not assigned to one specific Operator with only two API calls:

First you filter all conversation resources for the Operator whose conversations you want to exclude, extracting the single conversation IDs from the result list. Then you make another call to the conversation list resource endpoint, providing this list of IDs to be excluded, as comma-separated value:

Delete IDs

For DELETE requests to list endpoints, you can provide a "whitelist" of resource IDs. Just provide a comma-separated string with all IDs you wish to delete via the "delete_ids" filter. Only the resource(s) thus specified will be deleted.

This allows for safer bulk delete actions, since only the specified IDs will be deleted, no matter what other filters or limits are provided:

Searching

Searching is really a special kind of filtering, available for the "Conversation" and "Contact" list endpoints. For each resource, certain fields will be searched and all matching results will be returned, ordered by a specific ranking. We will explain the individual fields and ranking for each resource below.

To search an endpoint for specific resources, simply add the "search_query" parameter to your request, followed by the search keyword:

Multiple keywords

You can search for multiple keywords in one request by providing the "search_query" parameter with a white-space separated value. Since you cannot use literal whitespaces in your request URLs, use one of the following encodings:

EncodingValueExample
"Percent" encoding%20?search_query=userlike%20gregor
"Plus" encoding+?search_query=userlike+gregor

Multiple keywords are "ORed", meaning that a search for "userlike+gregor" will return results that match either the first or the second keyword:

Ranking

The ranking of all results matching your keyword(s) is determined by two factors: where the matching content was found and how often it was found. A match in a contact's name ranks higher than a match in a contact's notes, and three matches in one conversation rank higher than only one match in another.

Ranking factorExampleDescription
WeightAThe ranking prominence follows the natural order of the letters, i.e. "A" ranks higher than "B" ranks higher than "C"
Occurrence3The more occurences, the higher the ranking

The ranking of each resource's search fields are described below.

Stemming

We do some (basic) stemming by treating every keyword you provide as a potential prefix - if you provide the keyword "walk", we search for "walk*", which would also return results for e.g. "walked" or "walking". Multiple keywords are all treated as prefixes as well:

Provided search keyword(s)Actual search
?search_query=useruser*Matches "user", but also e.g. "userlike"
?search_query=user+greguser* || greg*Matches e.g. "user", "userlike", "greg" or "gregor"

Keep this in mind if your search returns too many (undesired) results, and provide more specific search keyword(s).

Conversation resource

Resource endpointsDescriptionAllowed methods
http://www.userlike.com/api/um/conversations/
http://www.userlike.com/api/um/conversations/{id}/
List of conversations

Single conversation
GET | DELETE

GET | PATCH | DELETE
Conversation list endpoint - GET

Fetch a list of conversations you had with your webvisitors. Returns a JSON object with an results array, by default containing the last 10 conversations that have been created. The response JSON further contains pagination details.

The conversation resource items returned by the list endpoint only contain the last message of the conversation. If you want to get the full conversation data, you must make a request to the conversation single endpoint, which we show how to do further below.

Conversation list endpoint - DELETE

Delete a list of conversations you had with your webvisitors. Response contains no data and has HTTP status 204..

Making a DELETE request to the conversation list endpoint will irrevocably bulk delete a number of conversations: 10 by default, 100 being the maximum allowed limit.
Conversation list endpoint filters

The conversation list endpoint lets you filter its resources for the following fields:

FieldSample valueDescription
contact_uuidMGEwYWJmZmEtN2M1OS01NGI2LWE2OWYtZWYxNDY4OWM0YWQ3Get all conversations you had with a specific contact
operator_id23Get all conversations of a specific operator by their ID
statuspendingGet all conversations you assigned a certain status
topicsSupportGet all conversations you assigned a certain topic label
um_widget_id42Get all conversations that were hold (at least partially) via a specific chat widget.
to_date2018-11-07Get all conversations that were updated before a specific date
from_date2018-11-05Get all conversations that were updated after a specific date
iso_to_date_time2018-09-22T14:01:54.9571247ZGet all conversations that were updated before a specific time
iso_from_date_time2018-07-22T14:01:54.9571247ZGet all conversations that were updated after a specific time

You can use these filters alone or in combination to extract exactly the resource items you need.

You can also use these filters to immediately delete the filtered resource items.

Making a filtered DELETE request to the conversation list endpoint will also irrevocably bulk delete a number of conversations: 10 by default, 100 being the maximum allowed limit.

Make sure you also read the general remarks on result filtering.

Conversation list endpoint searching

The conversation list endpoint lets you search its resources by matching your search keyword(s) against certain data fields of or related to your conversations. If your keyword(s) match(es) any of the contents of the following fields, the respective conversation will be part of the result set:

FieldRankingDescription
Contact's nameAGet all conversations whose contact's name matches the keyword
Contact's emailAGet all conversations whose contact's email matches the keyword
Contact's streetAGet all conversations whose contact's street name matches the keyword
Contact's cityAGet all conversations whose contact's city matches the keyword
Contact's countryAGet all conversations whose contact's country matches the keyword
Contact's notesBGet all conversations where your notes about the contact matches the keyword
Conversation contentCGet all conversations whose content matches the keyword

We intentionally rank matches in the associated contacts' data higher than matches in the conversations' own content, since that data is much more structured and qualified.

You can also use the search feature to immediately delete the matching conversations:

Making a search DELETE request to the conversation list endpoint will irrevocably bulk delete the matched conversations: 10 by default, 100 being the maximum allowed limit.

Make sure you also read the general remarks on resource searching.

Conversation list endpoint ordering

The conversation list endpoint results can be alternatively ordered by the following fields:

FieldValueDescription
orderingupdated_atOrder the conversations according to when they were last updated, in ascending order (oldest first).
ordering-updated_atOrder the conversations according to when they were last updated, in descending order (latest first).

Make sure you also read the general remarks on result filtering.

Conversation single endpoint - GET

Fetch a specific conversation you had with one of your contacts by providing its ID. The returned JSON object contains the full conversation, including all its parts.

If you need the full conversation data for a specific set of conversations, first filter the resource items accordingly using the list endpoint. Then use the conversation IDs you get from the filtered result set to fetch the single resource items, which will contain the full data.

The 'transcript' key contains a list of chat-messages and events that happened during a conversation. Here is an example of one list entry:

Note that translations are only available for flex customers.

Conversation single endpoint - PATCH

Update certain data of a specific conversation you had with one of your contacts. The returned JSON object contains the full and updated conversation.

The following fields can be updated:

FieldSample valueDescription
operator_assigned_to16Assign the conversation to the Operator with the respective ID
status"closed"Update the conversation's status
topics["Support", "Webshop"]Update the conversation's (multiple) topic label(s).
subject"Help with product XY needed"Update the conversation's subject

You can update one or more of these fields with a single patch request.

Conversation single endpoint - DELETE

Delete a specific conversation you had with one of your contacts by providing its ID. Response contains no data and has HTTP status 204.

Contact resource

Resource endpointsDescriptionAllowed methods
http://www.userlike.com/api/um/contacts/
http://www.userlike.com/api/um/contacts/{id}/
List of contacts

Single contact
GET | DELETE

GET | PATCH | DELETE
Contact list endpoint - GET

Fetch a list of contacts. Returns a JSON object with an results array, by default containing the last 10 contacts that have been created. The response JSON further contains pagination details.

Contact list endpoint - DELETE

Delete a list of contacts. The response contains no data and has HTTP status 204..

Making a DELETE request to the contact list endpoint can potentially bulk delete a number of contacts: 10 by default, 100 being the maximum allowed limit.
Contact list endpoint filters

The contact list endpoint lets you filter its resources for the following fields:

FieldSample valueDescription
id23Get the contact matching the given ID
emaildavid@userlike.comGet the contact with the specified email
nameDavid VoswinkelGet all contacts matching a specific name
to_date_time2018-09-22T14:01:54.9571247ZGet all contacts that were active before a specific time
from_date_time2018-07-22T14:01:54.9571247ZGet all contacts that were active after a specific time
verifiedtrueGet all contacts that have a verified email or mobile number
localeen_USGet all contacts that match the given locale

You can use these filters to extract exactly the resource items you need.

You can also use these filters to immediately delete the filtered resource items.

Making a filtered DELETE request to the contact list endpoint can potentially bulk delete a number of contacts: 10 by default, 100 being the maximum allowed limit.

Make sure you also read the general remarks on result filtering.

Contact list endpoint searching

The contact list endpoint lets you search its resources by matching your search keyword(s) against certain data fields of your contacts. If your keyword(s) match(es) any of the contents of the following fields, the respective contact will be part of the result set:

FieldRankingDescription
Contact's nameAGet all conversations whose contact's name matches the keyword
Contact's emailAGet all conversations whose contact's email matches the keyword
Contact's streetAGet all conversations whose contact's street name matches the keyword
Contact's cityAGet all conversations whose contact's city matches the keyword
Contact's countryAGet all conversations whose contact's country matches the keyword
Contact's notesBGet all conversations where your notes about the contact matches the keyword

An example contact search:

You can also use the search feature to immediately delete the matching contacts:

Making a search DELETE request to the contact list endpoint will irrevocably bulk delete the matched contacts: 10 by default, 100 being the maximum allowed limit.

Make sure you also read the general remarks on resource searching.

Contact list endpoint ordering

The contact list endpoint results can be alternatively ordered by the following fields:

FieldValueDescription
orderingcreated_atOrder the contacts according to when they were created, in ascending order (oldest first).
ordering-created_atOrder the contacts according to when they were created, in descending order (latest first).
orderingnameOrder the contacts by their names, in ascending order (A-Z).
ordering-nameOrder the contacts by their names, in descending order (Z-A).
orderingemailOrder the contacts by their email, in ascending order (A-Z).
ordering-emailOrder the contacts by their email, in descending order (Z-A).

Make sure you also read the general remarks on result filtering.

Contact single endpoint - GET

Fetch a specific contact by providing its ID. The returned JSON object contains the full contact representation, including any additional data.

Contact single endpoint - PATCH

Update certain data of a specific contact. The returned JSON object contains the full and updated contact.

The following fields can be updated:

FieldSample valueDescription
emailmy.contact@customer.comUpdate the contact's email address
name"Jane Doe"Update the contact's name
additional_data[["Nickname", "Janie"], ["Kids", 3]]Update the contact's additional data, provided as a list of 1 to 3 key-value pairs (lists)
salutation"mrs"Update how the contact whishes to be saluted
gender"f"Update the contact's gender
street"Sunset Blvd"Update the contact's street
city"Cologne"Update the contact's city
country"DE"Update the contact's country, providing a valid two-digit iso code.
phone_number"+49521234567"Update the contact's phone number
mobile_number"+49521234567"Update the contact's mobile number
contact_by_phoneTrueUpdate if the contact wants to be contacted via phone
contact_by_emailTrueUpdate if the contact wants to be contacted via email
contact_by_userlike_messengerTrueUpdate if the contact wants to be contacted via Userlike Messenger
contact_by_userlike_channelsTrueUpdate if the contact wants to be contacted via Userlike Channels
url_facebook"https://facebook.com/xy"Update the contact's Facebook url
url_twitter"https://twitter.com/xy"Update the contact's Twitter url
url_linkedin"https://linkedin.com/xy"Update the contact's Linkedin url
url_profile_picture"https://url_profile_picture.com/xy"Update the contact's profile picture url

You can update one or more of these fields with a single patch request.

In contrast to a single conversation, you can update nearly all fields of a contact via the API. This allows you to enrich your Userlike contacts with data from another CRM system you might have, for example.

Contact single endpoint - DELETE

Delete a specific contact by providing its ID. Response contains no data and has HTTP status 204.

Operator resource

Resource endpointsDescriptionAllowed methods
http://www.userlike.com/api/um/operators/
http://www.userlike.com/api/um/operators/{id}/
http://www.userlike.com/api/um/operators/{id}/slots/
List of operators

Single operator

Single operator's slot data
GET

GET | PATCH | DELETE

GET | PATCH | DELETE

In contrast to the other resources, the operator resource's list endpoint does not offer bulk deletion. This is to prevent destructive API calls that could seriously affect the operation of your Userlike account.

Operator list endpoint - GET

Fetch a list of operators. Returns a JSON object with an results array, by default containing the last 10 operators that have been created, including their current chat slot utilization. The response JSON further contains pagination details.

Operator list endpoint filters

The operator list endpoint lets you filter its resources for the following fields:

FieldSample valueDescription
id23Get the operator matching the given ID
emaildavid@userlike.comGet the operator with the specified email
nameDavid VoswinkelGet all operators matching a specific name
operator_group_id132Get all operators belongig to a specific operator group

You can use these filters to extract exactly the resource items you need.

Make sure you also read the general remarks on result filtering.

Operator list endpoint ordering

The operator list endpoint results can be alternatively ordered by the following fields:

FieldValueDescription
orderingcreated_atOrder the operators according to when they were created, in ascending order (oldest first).
ordering-created_atOrder the operators according to when they were created, in descending order (latest first).
orderingnameOrder the operators by their names, in ascending order (A-Z).
ordering-nameOrder the operators by their names, in descending order (Z-A).
orderingemailOrder the operators by their email, in ascending order (A-Z).
ordering-emailOrder the operators by their email, in descending order (Z-A).

Make sure you also read the general remarks on result filtering.

Operator single endpoint - GET

Fetch a specific operator by providing its ID. The returned JSON object contains the full operator representation, including operator group and organization.

Operator single endpoint - PATCH

Make various changes to a specific operator.

{{_i}At this time, PATCH can be used to update an operator's away status. The response will have the format of the slot view as described below.

Operator single endpoint - DELETE

Delete a specific operator by providing its ID. The response contains no data and has HTTP status 204.

Since deleting an operator can affect the operation of your Userlike account, we take some precautions to prevent you from causing serious harm when making a DELETE call.

We make sure you do not accidentially:

  • Delete the owner your Userlike account
  • Delete the operator making the request (which in most cases is the owner)
  • Delete the last operator of an organization

When you make a call that would cause one of these actions, you'll get a response with status 403 - Forbidden. In the JSON body you'll find the details on why you request was denied.

Operator single endpoint - slot view

For single operator resource items, we offer an additional endpoint that only returns the specific operator's slot data when making a GET request to it. Apart from that, all other requests behave exactly the same as those to the regular operator resource single endpoint.

Use this reduced "view" on a specific operator's chat slot utilization if all you need is this subset of the operator's data. For example, when you are using the JSON API to sync your operators' chat availability with an external support system.

The fields of an operator's slot data are:

FieldDescription
availabilityThe operator's presence status, combined from the fields "available" and "connected". Its value can be "available", "unavailable" or "offline".
availableWhether the operator is available to chat
connectedWhether the operator is currently connected to the message center
freeNumber of free chat slots
usedNumber of used chat slots
totalNumber of the operator's total chat slots

Python Examples

We prepared a few examples on how to access the Userlike API using Python. It's pretty straightforward, we use the Python library "requests" for the HTTP requests, always adding the required Authorization headers.

Simple example: fetch last conversations

This very basic example shows you how to retrieve the list of the latest 10 conversations you had with your customers with a small Python script.

More complex example: assign all open conversations to a new Operator

This larger example shows you how to work with different endpoints and request types to fulfill a task.

Imagine the following use case: you finally have a new Operator on your team and want to assign them all customer conversations that still have the status "open".

For this, you first have to get the id of the new Operator by filtering the Operator resource endpoint with their email address. Second, you have to get the list of all conversation (ids) whose status is "open", by filtering the Conversation resource list endpoint. Finally, you have to update these single conversations by assigning the new Operator to them, sending patch requests to each individual Conversation resource endpoint.