Our APIs help your business quickly turn data into insights that drive financial outcomes. Create loyal customers, drive revenue growth and arm your teams with the knowledge they need to succeed.
CloudLink offers over 300 Reporting APIs, providing you the flexibility to scale and integrate CloudLink applications with your business and products.
Our powerful Integration APIs allow you to write data between CloudLink and other applications, enabling you to accelerate value from your ecosystem of products.
Purpose of the Document
This document will go through the CloudLink API technical guide. By the end of this document you should be able to authenticate your calls and be able to call any reporting API.
You should be able to Filter & Sort any API returned data as well as manage the pagination of the data for the bigger APIs.
Consuming APIs
To start consuming the APIs, you should have:
- Valid API Keys that you can get by asking Texada to generate.
- Use the proper URL for the targeted region / environment, please refer to CloudLink APIs - Getting Started.
- Pass the Access Token and the API Key to each API call.
For the rest of this documentation we will be using USEast as a region and Demo Production as a tenant. This is to facilitate the URL examples in this document.
Getting an Access Token
Before calling any reporting API, you have to have a valid access token. To get an access token, make a POST request to /auth with 2 headers.
The 3 headers are “Content-Type”, “Tenant” and “x-api-key”:
- Tenant: the lowercase tenant name which is located in the URLs for any CloudLink application. Example: https://use.cloudlink.texadasoftware.com/demo/CustomerSearch/, where demo in this case is the tenant name.
- x-api-key: the API key shared for by Texada. Each environment (Sandbox/Production) has a different API Key.
cURL:
cURL -X POST "https://use-api.cloudlink.texadasoftware.com/v1/demo/auth" -H "Tenant: demo" -H "x-api-key: myApiKey"
Calling APIs
All subsequent API calls will need 3 headers:
- Tenant: The lowercase tenant name which is located in the URLs for any CloudLink application. Example: https://use.cloudlink.texadasoftware.com/demo/CustomerSearch/, where demo in this case is the tenant name.
- x-api-key: The API key shared by Texada. Each environment (Sandbox/Production) has a different API Key.
- Authorization: set to “Bearer“ + “ “ + {ACCESS-TOKEN}. So, if your access token is “abc”, the header needs to be set to “Bearer abc”.
cURL:
cURL -X GET "https://use-api.cloudlink.texadasoftware.com/v1/demo/activities" -H "Tenant: demo" -H "Authorization: Bearer myAccessToken" -H "x-api-key: myApiKey"
Query Parameters
Query parameters are parameters that can be sent to the API service by putting them in the API’s URL. These parameters can be used to Filter, Sort and paginate the API’s results. This is what this document will cover next.
Filtering Parameters
To filter the API returned data, add a query parameter whose name is the name of the field you want to filter by and whose value is the value you want to filter by.
Filter on Equality
To get activities whose statusId = 2 (completed) and for a certain CustomerId = 123456:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?statusId=2&customerId=123456
Filter by Matching Multiple Values
To get activities whose statusId = 2 or statusId =1 and for a certain CustomerId = 123456:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?statusId=1,2&customerId=123456
Filter by Nullable Fields
To filter where a certain field equals null or does not equal null, use the values “NULL” or “NOT_NULL”.
To get activities whose are attached to a campaign, where campaignId is not null:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?campaignId=NOT_NULL
Filter by a Range of Values
To filter data where a field is greater than or less than a certain value, use a query parameter whose name is “filter[{field}][{operator}]={value}”.
- “{field}” is the name of the field you want to filter by.
- “{operator}” is one of:
- gt (strictly greater than)
- gte (greater than or equal to)
- lt (strictly less than)
- lte (less than or equal to)
- “{value}” is the value that is used for the filter.
For date ranges, we recommend using “gte” (greater than or equal to) for the earlier date and “lt” (strictly less than) for the later date. This is because the values are converted to date times and if a time is not entered, it will just be converted to 00:00:00 (midnight).
To get activities entered in one day:
Sorting Parameters
To sort the API-returned data, add a query parameter with the name “sort” whose value is the name of the field to sort by. To reverse the sorting direction, use a “-” in front of the field name.
Sort in ascending order on a single field
To get activities sorted by enterDate ascending, oldest to newest:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?sort=enterDate
Sort in ascending order on multiple fields
To get activities sorted by multiple fields (changeDate & enterDate), use a comma-separated list:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?sort=changeDate,enterDate
Sort in descending order on a single field
To get activities sorted by enterDate descending, newest to oldest, use a “-“ in front of the field name:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?sort=-enterDate
Pagination Parameters
APIs return data in sets of 1000 records by default. These sets are called “pages”.
- Max page size = 1000
- Default page size = 1000
- Pages have zero-based numbering, first page number is 0 not 1
To change the page returned by an API, add a query parameter whose name is “page” and whose value is the page number:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?page=3
To change the size of the pages, add a query parameter whose name is “size” and whose value is the number of records per page. The maximum size is 1000:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=25
Each API call returns the pagination information as a JSON object at the end of the API response.
One or more query parameters can be used for each API call.
Get records 1-1000:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?page=0
Get records 76-100:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=25&page=3
Get records 1-1000 which changed after 2019-09-04:
Advanced Pagination
Some programming can be done to use the pagination in order to download all the data behind one API.
First, get the record count by calling the /count API. For Activities, this is the API:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities/count
After getting the count, calculate the number of calls needed to get all records:
- Count / Page size = number of calls
The maximum page size (number of records per request) is 1000.
Get all the pages by making parallel requests. The recommendation is to make 10 parallel requests at a time.
Make the 10 requests in parallel:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=0
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=1
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=2
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=3
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=4
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=5
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=6
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=7
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=8
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=9
Wait for those 10 to finish, then make additional requests:
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=10
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=11
https://use-api.cloudlink.texadasoftware.com/v1/demo/Activities?size=1000&page=12
…up to 13,000 records in this case.