Skip to main content

Making API Requests

Authentication​

Naturally, the first step to using the API is to get an access token. You would use a service account with a perpetual token for an integration. But for testing you can use your regular user session token. The platform uses Auth0 for authentication. This is how to get a user token - using your Auth0 credentials.

curl -X 'POST' \
  'https://api.{domain}.com/authenticate' \
  -H 'Content-Type: application/json' \
  -d '{"username": "[email protected]", "password": "password"}'

Response:

{"tokenType": "Bearer", "idToken": "ey..."}

Congratulations! 🥳 You now have API access. This user session token can be added to the header to perform authenticated requests using the format shown below. If successful below request will return a message containing the user-name for the session. Note the space between the tokenType and idToken. Regular user tokens are valid for 86400 seconds.

curl 'https://api.{domain}.com/ping/secured' \
  -H 'Authorization: Bearer ey...'

Headers​

Often the Authorization header is the only one needed for a request, but it is good practice including Content-Type where relevant. If another header is required we will make it known in the endpoint documentation.

Payload Validation​

All payloads are subject to some form of validation. The API Reference Documentation describes expected data-types and can help you build correct payloads for endpoints not listed in this documentation.

If a validation fails you can expect a 400 response containing a message describing the issue. An unexpected error can trigger a 500 error response, this will not have a helpful message.

List Pagination​

For list responses you should expect paginated results. This will be noted in the endpoint documentation. It is best practice to include all pagination parameters in the query string of your URL when making a request to an endpoint that returns a paginated list.

A pagination query string example is:

  • limit=10&page=1&orderBy=id&order=asc
    • limit=10 sets the max number of results per page to ten
    • page=1 will fetch the first page
    • orderBy=id order by the id field
    • order=asc sorted in ascending order

Response Pagination Headers​

The paginated response body contains only the wanted data, the pagination data is stored in the headers. The Link header contains a commas seperated list for resources for the previous, next and last page.

An example of a Link header returned with the first page of the fictional my-list endpoint is: 

,</my-list?limit=1&page=2&orderBy=id&order=asc>;rel="next",</my-list?limit=1&page=2&orderBy=id&order=asc>;rel="last"

In addition, there is an X-Total-Count header the provides a count of total pages. For above example this would hold the value "2".

Search Endpoints​

Advanced Topic

This topic is only relevant to using a search endpoint. We advise using it as a reference document when building towards a search endpoint. Until this time, it can be skipped over.

Most endpoints are self-explanatory but our search functionality requires some context. Search endpoints allow you to specify the search criteria for a given model in the payload. The results will be returned as a paginated list.

Search Input​

Type String

Always provide values as strings in a search input.

There are two methods to filter the response from a search endpoint. The Base Search Input is used for comparison operators. And, the Partial Match Search Input is used to match a parties string input, provided by you, to the values of listed fields. If the input string is contained in the field value the record will be returned. These two methods can be combined in a single payload.

Base Search Input​

In the most basic case - lets say we want all records where my_field is abc. We achieve this with the following payload:

{"my_field":  "abc"}

Now for a more complicated example. We want all records where: (1) "my_field" is "abc" or "def", (2) "my_other_field" is not "abc" and not "def", and (3) "my_number_field" is greater than zero. Then the payload should look like this.

{
   "my_field": "abc[OR]def",
   "my_other_field": "[NOT]abc[AND][NOT]def",
   "my_number_field": "[>]0" 
}

As these examples have illustrated this allows you to build a query in your search endpoints by combining the following operators: [AND], [OR], [>], [<], [>=], [<=] and [NOT].

Partial Match Search Input​

This is an option to facilitate part of a string value in specific fields. For example lets say that there is a "person" search endpoint with a field name, and you want to find everyone with "John" in their name. To do so we use the following payload:

{
   "query": "John",
   "queryTarget": "name"
}

Now, to above example let us add that there is also a field for the company_name where the person works, and you want to find records where either the name or company_name contains "John". Then you would use the following payload:

{
   "query": "John",
   "queryTarget": "name|company_name"
}