INTRODUCTION

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”).

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.

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

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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/users</span>  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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/campaigns/1</span>  Accept: application/json  Content-Type: application/json  {     "users": [        {"id": 1},        {"id": 2}     ]  }  PATCH <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/2/campaigns/1/users</span>  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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/campaigns/123</span>  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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/campaigns/123</span>  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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/users?per_page=50&page=5</span>  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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/users/123
</span>

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": "<span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/agents?page=2</span>",

"prev": "<span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/agents?page=1</span>",

"next": "<span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/agents?page=3</span>"

},

"_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": "<span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/users/12345</span>"

"custom_fields": "<span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/users/12345/custom_fields</span>"

}

}

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:

• http://tools.ietf.org/html/rfc6749
• http://oauth.net/2/

Grant type – password

Authentication happens with user credentials (username and password).

POST <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/oauth/access-token</span>

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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/oauth/access-token</span>

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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/oauth/access-token</span>

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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/oauth/access-token</span>

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 <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/users</span>

Authorization: Bearer D9hc9iRvLwoKxH2R43hy19QzzeLgplAEOlSL7igd

DELETE <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/products/12345</span>

Authorization: Bearer D9hc9iRvLwoKxH2R43hy19QzzeLgplAEOlSL7igd

Curl example

curl -X GET -H "Authorization: Bearer D9hc9iRvLwoKxH2R43hy19QzzeLgplAEOlSL7igd" <span style="color: #8300e9;">https://restapi-nor.leaddesk.com/stable/users
</span>