Getting started with the REST API

In this article, we will show you an example on how to build a LeadApp that prints out the total number of users through our REST API.

The sample code is in PHP and Python.

Note: API URLs are zone specific and in examples, there is just one of these:

  • NOR zone – https://restapi-nor.leaddesk.com/v2/
  • QED zone – https://restapi-qed.leaddesk.com/v2/
  • CEU zone – https://restapi-ceu.leaddesk.com/v2/

You can check which is the correct zone for you in your Admin account. Go to the Settings page and the API subpage, the correct URL will be shown as the REST API URL.

The above client is in the QED zone and uses the QED version of the REST API URL.

Requirements and Preparations

If you’re using PHP, here is the environment we used in the sample code:
PHP >= 7.0
guzzle >= 6.0

use GuzzleHttp\Client; $client = new Client(); $baseUrl = "https://restapi-nor.leaddesk.com/stable";

If you’re using Python, here is the environment we used in the sample code:
Python >= 3.4
requests >= 2.1

Import libraries and define the base url.

import requests

BASE_URL = "https://restapi-nor.leaddesk.com/stable"

How to get access token

LeadDesk REST API uses OAuth 2 authentication. In this example, we use ‘leaddesk_client_id’ as ‘grant_type’ to get the Bearer Token.

This example uses PHP:

$resToken = $client->request(
    "POST",
    $baseUrl. "/oauth/access-token",
    ["json" =>
       [
          "grant_type" => "leaddesk_client_id",
          "client_id" => "", //Found in Admin > General settings > API;
          "client_secret" => "", //Found in Admin > General settings > API;
          "leaddesk_client_id" => 0, //your Leaddesk customer ID;
       ]
    ]
);

$resTokenJson = json_decode($resToken->getBody(), true);
$accessToken = $resTokenJson["access_token"];

And in Python:

res_token = requests.post(
    "{}{}".format(BASE_URL, "/oauth/access-token"),
    json={
        "grant_type":"leaddesk_client_id",
        "client_id": "",  # 
        "client_secret": "",  # 
        "leaddesk_client_id": 0 # 
    }

)
res_token.raise_for_status()
access_token = res_token.json()["access_token"]

How to request to LeadDesk API

In this step, we will use the method “GET” to the “/users” endpoint to fetch users data. As our API supports pagination, we are fetching the first page of the user list, 5 users per page.

LeadDesk REST API has various endpoints and supports methods GET, POST, PATCH and DELETE. See more from our the specification documentation.

Here is an example in PHP:

$response = $client->request(
    "GET",
    $baseUrl. "/users",
    [
        "http_errors" => false,
        "headers" => [
            "Authorization" => "Bearer ". $accessToken,
        ],
        "query" => [
            "per_page" => 5,
            "page" => 1,
        ]
    ]
);

$result = [
    "code" => $response->getStatusCode(),
    "data" => json_decode($response->getBody(), true)
];

And in Python:

response = requests.request(
    "GET",
    "{}{}".format(BASE_URL, "/users"),
    headers={
        "Authorization": "Bearer {}".format(access_token)
    },
    params={
        "per_page": 5,
        "page": 1
    }
)

result = {
    "code": response.status_code,
    "data": response.json()
}

Output

After fetching the data, we simply print out the total user number of the client. If everything works fine, you will see the output.

In PHP:

if ($result["code"] >= 200 && $result["code"] <= 299) {
    echo "Hello world, we have {$result["data"]["_meta"]["count"]} users in LeadDesk.\n";
} else {
    echo "Fail to get users data.\n";
    var_dump($result);
}

And in Python:

if result.get("code") >= 200 and result.get("code") <= 299:
    print("Hello world, we have {} users in LeadDesk.\n".format(result["data"]["_meta"]["count"]))
else:
    print("Fail to get users data.\n")
    print(result)