For full API documentation and to download a sample Postman collection, please visit https://api.dragonmetrics.com/.

Each API endpoint has different parameters that can be sent along in the request or properties returned in the response. However, a few elements of them are common to almost every endpoint in the API. Let's take a look at each one in a bit more detail.

Request

Authorization Request Header

All API calls must be authenticated using Basic HTTP Authentication. As the name implies, this protocol is quite simple.

All requests must include the following HTTP request header:

Authorization: Basic {CREDENTIALS}

Where {CREDENTIALS} is a Base64 encoding of the string {username}:{password}.

(Please remember that this is your API username and password, which will be different than the one you use to log into the user interface. If you do not have API credentials, please get in touch via the live chat icon in the bottom right of every page or email us at support@dragonmetrics.com)

For example:

Username: johdoe
Password: Lh78B30#grCgo%
Before Base64: johndoe:Lh78B30#grCgo%
After Base64: am9obmRvZTpMaDc4QjMwI2dyQ2dvJQ==
Full HTTP Request Header: Authorization: Basic am9obmRvZTpMaDc4QjMwI2dyQ2dvJQ==

Now you can make calls to the API, including this header in every request. If there is an issue with your authorization you'll receive a 401 (Unauthorized) error message.

IMPORTANT REMINDER: Although your username and password are encoded using Basic Authentication, they are not encrypted. Therefore, it's important to always send requests over HTTPS. All requests made over HTTP will be sending your username and password in plain text, and will result in a 403 (Forbidden) error response.

Limit

By default, all endpoints return a maximum of 50 results. Use the limit field in the request body to change this to your preferred value.

The maximum value for limit is 500. Requests with a limit greater than 500 will be returned with an error.

Example:

{
"campaign": "Test Campaign",
"begin_date": "01-08-2021",
"end_date": "07-08-2021",
"limit": 500
}

Start

Since the maximum value for limit is 500 results, the start field must be used to page through all results if there are more than 500 items.

The start field is the index of the first result in the set returned. The default for start is 0, which is the first item in the collection.

For example, to retrieve data from a collection that contains 1,000 results, two requests will be required. For the first request, set the limit to 500 and start of 0 to get items 0-499. To access the next page of results, leave limit to 500, but now set start to 500, which will return items 500-999.

Example:

{
"campaign": "Test Campaign",
"begin_date": "01-08-2021",
"end_date": "07-08-2021",
"start": 0,
"limit": 500
}

Response

General structure

Most endpoints follow a similar response structure, with 3 main objects returned: request, results, and paging.

{
"request": {
...
},
"results": {
...
},
"paging": {
...
}
}

Request object

The request object is an echo of how the request parameters made in the request body were interpreted by the API. In many cases, this should match your request body exactly, but if optional fields were omitted, you can see how default values may have been used by looking at the request object. If unexpected results are returned in the response, this object can be useful for debugging your request.

Response object

This is where the data requested will be delivered, and the structure will vary from endpoint to endpoint.

Paging Object

Every request contains a paging object, which helps make paging through results even easier.

This object shows the total number of items available in the set, and the value for start to get the next page, previous page, or the current page (assuming the same value for limit.

For example, if there are 2,000 total rows available, when using a limit of 500 when requesting the second page of results would look like the following:

"paging": {
"total": 2000,
"prev_start": 0,
"current_start": 500,
"next_start": 1000
}

Let's take a look at this in a bit more detail:

  • The first property, total, is the total number of results in the set

  • prev_start is the value for start to retrieve the previous page of results (assuming the same value for limit).

  • current_start is the value for start to retrieve the current page of results (assuming the same value for limit).

  • next_start is the value for start to retrieve the next page of results (assuming the same value for limit).

Error Object

If a request was invalid or there was a problem with the response, the server will respond with an error object describing the issue.

For example, if you make a request with a begin date of October 1st, 2021 and an end date of September 30, 2021 you'll receive the following response along with an HTTP 422 response code:

{
"error": {
"code": 10012,
"message": "Begin date must be before end date",
"description": "The requested date range is not valid. The begin date must be before the end date."
}
}
Did this answer your question?