Requests

LeadDesk REST API is used by HTTP requests sent for the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted to protect the authentication. The interface responds to different methods depending on the action required. Here are the generic rules for different HTTP methods (“verbs”).

Command Description
GET GET is used for simple retrieval of information about your resources. GET can be used to fetch single objects or a collection of objects. The information you request will be returned to you in JSON format. Any request using the GET method is read-only and will not affect any of the objects you are querying.
POST To create or add new objects, your request should specify the POST method. The POST request includes all the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint with object definition in HTTP request body. Usually only JSON format is accepted. POST method can also be used to add relation between objects e.g. one could assign contact_list to campaign with POST command.
PUT PUT is not generally supported.
PATCH PATCH is used to update the information about a resource in your account. Partial updating is supported, so only defined values will be updated to resource. Parameters are sent as in HTTP request body. Usually update object is accepted only in JSON format.
DELETE DELETE method can be used to destroy a resource and remove it from your account. Remove can also be used to remove relation between resources e.g. removing user from campaign. This will remove the specified object if it is found. If delete is successful then empty HTTP response with status 204 (No Response) will be sent. If resource is not found, the operation will return a response indicating that the object was not found 404 (Not Found). Usually DELETE command don’t take any parameters, but the URI itself will describe what should be removed.

HTTP statuses

Generic HTTP status codes will be used to describe if the request was successfully processed or if an error occurred. Below is a list of HTTP status code ranges and how they should be interpreted.

Range Description
2XX HTTP statuses in range 2XX will be used when operation was successful.
4XX HTTP status in range of 4XX is sent in case of error. 4XX range is reserved for errors that are usually results of request that can’t be completed as such. User could be lacking proper access rights or resource is not found. This is something the user can usually resolve by changing the parameters.
5XX 5XX range is reserved for errors that are caused by internal problems within LeadDesk. Request cannot be completed at the moment. It can be attempted again later.

In all error cases the response also contains some JSON formatted details about the error. Error parameter is something that can be used in client side and same error should always return same id. Different errors could result in same HTTP status code but they usually should have different id. Message is human readable error report for the client developer. Human readable text is subject to changes if API is developed so it must not be used in client code to check the type of error.

Error example

 
HTTP/1.1 404 Not Found  Content-Type: application/json  {    "error": <error_code> For example: "user_not_found"    "error_description": <human readable error message describing the error>  }

It’s also possible to get even more additional parameters returned in special error cases.

Validation error

If validation of parameters fails then error object will also contain “error_validation” object describing which parameter has failed validation.


HTTP/1.1 422 Unprocessable Entity  Content-Type: application/json  {     "error": "validation_failed",     "error_description": "Parameter validation failed",     "error_validation": {       "per_page": [         "The per page must be at least 1."       ]     }  }

 

Commonly used status codes

List of commonly used status codes and their generic explanation

Status code Description
200 OK Request was fulfilled successfully. Returned content depends on the command and resource.
201 Created Creation request was fulfilled successfully. Object was created and it’s content is usually returned in the response.
204 No content Request was fulfilled but there’s no content to be send back. This is usually only used with DELETE requests.
400 Bad Request Generic error when something in the request is wrong. It could be lacking some mandatory fields or has non-acceptable values for properties. Check the response JSON object for more details.
401 Unauthorized Error which is caused mainly by invalid authentication. Authorization token could be expired or invalid.
403 Forbidden You are not allowed to do such operation. E.g. creation with read-only token.
404 Not Found When requested resource is not available, then not found error is usually returned. This can also happen if resource exists, but you don’t have visibility to it (e.g. teamleader attempting to modify campaign from different office).
415 Unsupported Media Type Server refuses to accept the request because the payload is in an unsupported format. E.g. request’s json body is malformed.
422 Unprocessable Entity Request included parameter values that are not valid or are erroneous.
405 Method Not Allowed Given HTTP method is not allowed with requested resource. e.g. Some resources can’t be deleted.
500 Internal Server Error Something is wrong in LeadDesk infrastructure. Request could not be fulfilled at the moment, but it should be runnable later on when problem is fixed. Check the response JSON object for more details.
501 Not Implemented Error caused by requesting an operation that is not yet fully implemented.
503 Service Unavailable Error that will be reported when API has been completely or partially been disabled.

Content types

Primary content type for the API is JSON. Majority of the commands will only response with JSON format. If some else content type is requested an error will occur. Character-set used in the API is always UTF-8.

Request header example


Accept: application/json  Content-Type: application/json

Response header example


content-type: application/json; charset=utf-8

Data format

Date

Time and date are always represented in ISO 8601 format. Input for time and/or date are expected to be in ISO 8601 format as well.

Example


2018-12-30T16:18:40+02:00

Parameters

Parameter passing differs between the used HTTP methods. Here are the generic rules that apply per method.

POST/PATCH

When passing parameters to create (POST) or update (PATCH) an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly. Also notice that JSON structure is case sensitive so all the attribute keys needs to be written with lowercase letters to make them work.

Example


POST https://api.cloud.leaddesk.com/2/users  Accept: application/json  Content-Type: application/json  {     "username":"example"  }

POST is generally used for creating new resources and adding new entries or relations to existing resources.

PATCH is generally used for modifying an existing resources and it usually replaces all the properties that are defined in the request.

Sub-resources

PATCH request on sub-resources only is possible and is identical to making the lower level request with the single attribute. Here’s an example of identical requests:


PATCH https://api.cloud.leaddesk.com/2/campaigns/1  Accept: application/json  Content-Type: application/json  {     "users": [        {"id": 1},        {"id": 2}     ]  }  PATCH https://api.cloud.leaddesk.com/2/campaigns/1/users  Accept: application/json  Content-Type: application/json  [     {"id": 1},     {"id": 2}  ]

Operation mode

PATCH in general overwrites data and POST on the other hand adds data. So if you patch an array, then all the previous entries will be removed. Using POST you can add new relations without removing the previous ones. If the sub-resource is associative array or the entries can be uniquely identified then PATCH will only change the given entry and not the whole array.

This request would assign products having ids 1 and 6 to campaign 123. Previously attached products will be removed.


PATCH https://api.cloud.leaddesk.com/2.0.0/campaigns/123  Accept: application/json  Content-Type: application/json  {     "products": [         {"id": 1},         {"id": 6}     ]  }

This request would add products having ids 1 and 6 to campaign 123. Currently attached products will be preserved. If these products are already attached, then the command does nothing for these products.


POST https://api.cloud.leaddesk.com/2.0.0/campaigns/123  Accept: application/json  Content-Type: application/json  {     "products": [         {"id": 1},         {"id": 6}     ]  }

 

Response

If the request creates a new resource into LeadDesk then the response will contain the id of the newly created resource. HTTP status is then 200. Response can contain other values as well, but id is always present. Check the documentation for more detailed response format.


{     "id": 1  }

If the command doesn’t create new entities then empty response will be sent with HTTP status 204. This happens when existing resources are modified or only relations between resources are added.

GET

When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &.

Example


GET https://api.cloud.leaddesk.com/2/users?per_page=50&page=5  Accept: application/json

DELETE

Delete command usually takes no parameters. Resource that will be deleted is identified in the URI itself. Successful delete operation usually returns 204 “NO CONTENT” response.

Example


DELETE https://api.cloud.leaddesk.com/2.0.0/users/123

Resources

Collections

When requesting a list of items (aka. collection) from the API the response will usually be formatted with following general rules. Response will be an JSON object containing following items collection, links and meta. Collection item is an array containing all the objects limited by the pagination. Links object contains the links for next and previous page if available. Meta item is an object with additional information for the collection, like total amount of such items in the system.

Example


{

"collection": [

<user-object-1>,

<user-object-2>

],

"_links": {

"self": "https://api.cloud.leaddesk.com/2/agents?page=2",

"prev": "https://api.cloud.leaddesk.com/2/agents?page=1",

"next": "https://api.cloud.leaddesk.com/2/agents?page=3"

},

"_meta": {

"total": 201

}

}

Unless resource definition specifies otherwise the GET request accepts two generic parameters.

per_page

  • How many items to retrieve per request. Maximum is by default 500 items and default is 25.

page

  • What page is requested. e.g. requesting a page 2 with per_page=25 would give out items from 26…50.

Objects

Requesting a single resource/object will give out response based on these generic rules. Object properties will be returned in the root level of the response. underscore prefix is reserved for internal use and normal object properties can’t start with an underscore. Response will also contain _link object which will contain links for further resource inside this resource. See the resource documentation for model descriptions. When reading the object values you should not make any assumptions of the order or count of the properties. This will ensure the client code will be most compatible against changes in the API.

Example


{

"id": 12345,

"username": "example-user",

...

"_links": {

"self": "https://api.cloud.leaddesk.com/2/users/12345"

"custom_fields": "https://api.cloud.leaddesk.com/2/users/12345/custom_fields"

}

}

Authentication

LeadDesk REST API will use OAuth 2 authentication. Few different grant types are supported and possibly more will be added in the future.

More info:

Grant type – password

Authentication happens with user credentials (username and password).


POST https://api.cloud.leaddesk.com/2/oauth/access-token

content-type: application/json

{

"grant_type":"password",

"client_id": "example-client-id",

"client_secret": "client-secret-password",

"username": "leaddesk-username",

"password": "very-secret-password"

}

content-type: application/json

{

"access_token": "CHGK3f04In4Zn6Kp6rfsUZlrJJCzXJH5wSAqAY2j",

"token_type": "Bearer",

"expires_in": 3600,

"refresh_token": "9ufdtxPDrkpGywUB4Wm6Rot8rejfQAwXkQCgB4v0"

}

Grant type – leaddesk_client_id (requires special grant)

Authentication happens with api client credentials. When client credentials are created they can be given scopes and access to specific Leaddesk clients.


POST https://api.cloud.leaddesk.com/2/oauth/access-token

content-type: application/json

{

"grant_type":"leaddesk_client_id",

"client_id": "example-client-id",

"client_secret": "client-secret-password",

"leaddesk_client_id": 1

}

content-type: application/json

{

"access_token": "CHGK3f04In4Zn6Kp6rfsUZlrJJCzXJH5wSAqAY2j",

"token_type": "Bearer",

"expires_in": 3600,

"refresh_token": "9ufdtxPDrkpGywUB4Wm6Rot8rejfQAwXkQCgB4v0"

}

 

Grant type – client_user (requires special grant)

API client can be given a permission to login to certain clients with username only. This is similar to leaddesk_client_id grant, but API client will get the scopes from the user instead of preconfigured scopes. Effective scopes will be the same as using the password grant.

Authentication request


POST https://api.cloud.leaddesk.com/2/oauth/access-token

content-type: application/json

{

"grant_type": "client_user",

"client_id": "example-client-id",

"client_secret": "client-secret-password",

"username": "example-username",

"leaddesk_client_id": 1

}

content-type: application/json

{

"access_token": "CHGK3f04In4Zn6Kp6rfsUZlrJJCzXJH5wSAqAY2j",

"token_type": "Bearer",

"expires_in": 3600,

"refresh_token": "9ufdtxPDrkpGywUB4Wm6Rot8rejfQAwXkQCgB4v0"

}

Grant type – refresh_token

Refresh request is used for refreshing the access token if it has expired. Refresh token is always valid longer than the access token. Notice that eventually the refresh token will also expire if refresh request is not sent. Refreshing will invalidate the original refresh token and access token. New access token will have all the same limitation than the original one.

 
POST https://api.cloud.leaddesk.com/2/oauth/access-token

Content-Type: application/json

{

"grant_type":"refresh_token",

"client_id": "example-client-id",

"client_secret": "client-secret-password",

"refresh_token": "OCqak57Um37Hacuw9vwbufnCWiRgqhiuUwKN4k9S"

}

content-type: application/json

{

"access_token": "Of3TqHd468uJB7J6QrqnK0r27jg907k7P7050ybv",

"token_type": "Bearer",

"expires_in": 3600,

"refresh_token": "jeKSWgaba90GYwi1b32LH91XAI3H08Umx45cgaSN"

}

Access token

After generating access token it can be used to access the API. Give the access token into Authorization header of the HTTP request. Here are few examples on using the access token.

Examples

 
GET https://api.cloud.leaddesk.com/2/users

Authorization: Bearer D9hc9iRvLwoKxH2R43hy19QzzeLgplAEOlSL7igd

DELETE https://api.cloud.leaddesk.com/2/products/12345

Authorization: Bearer D9hc9iRvLwoKxH2R43hy19QzzeLgplAEOlSL7igd

Curl example

curl -X GET -H "Authorization: Bearer D9hc9iRvLwoKxH2R43hy19QzzeLgplAEOlSL7igd" https://api.cloud.leaddesk.com/2/users