Making an API call

This section is a worked example of how to make a call to the API.

The steps described are:

  1. Viewing the reference documentation for the endpoint you want to call
  2. How to add parameters to the call
  3. How to add a request body to the call
  4. How to add an access token to the call
  5. How to handle errors
  6. Interpreting the response


This topic assumes you have authenticated your user against the API and obtained an access token.

If you have not done this, see the topic How to authenticate API calls.


This scenario shows you how to change a subscriber group's name using the API. To do this, you make a PATCH request to the /subscriber-groups/{subscriberGroupId} endpoint.

When you make an API call you can choose to make the request using your browser's search bar or you can use a utility such as Postman or cURL. This example shows you how to make a call using cURL.

Viewing the reference documentation

To find out what endpoints are available and what they can be used for, you can refer to the API reference documentation.

The information in the reference documentation provides you with an overview of the endpoints that are available in the API, what they are used for and the mandatory information you must include in your calls to each endpoint.

The information in the reference documentation includes:

  • A list of all of the API's endpoints and descriptions of what each endpoint is used for
  • The methods each endpoint accepts
  • The parameters you can pass in to your calls
  • The response and error codes the endpoint returns
  • If the endpoint accepts a request body, an example request body is documented
  • The content included in responses from the API

In this case you should refer to the documentation for the Subscriber Group endpoints.

Adding parameters

From the reference documentation for the PATCH/subscriber-groups/{subscriberGroupId} endpoint, you can see that the subscriberGroupId parameter is mandatory. If you don't include this parameter, the call will fail because you have not told the endpoint which group you want to modify.

In endpoint URLs, parameters are denoted in curly brackets {}. In this example you are using the /subscriber-groups/{subscriberGroupId} endpoint, so the parameter is {subscriberGroupId}.

For example, if the unique identifier of the group you want to edit is 20, your cURL request would read:

Example cURL Request
curl -X PATCH ""


If you don't know the group's unique ID, you can retrieve a list of your company's groups and their corresponding unique identifiers by making a GET request to the /subscriber-groups endpoint.

Adding a request body

The reference documentation for this endpoint tells you that you need to include a request body in your call. For this endpoint, you use the request body to tell the endpoint what you want to change the group's name to.

Where a request body is required, the reference documentation details the format in which the body can be supplied, the fields you need to include in the request and the request body's structure. In this case you need to provide a JSON object which includes the name you want to apply to the group.

For example, if you want to change the group's name to "Charlie's Group", the request body would look like this:

Example Request Body
  "name": "Charlie's Group"

Now that you have added parameters and a request body to the call, your cURL request looks like this:

Example cURL Request
curl -X PATCH "" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"Charlie's Group\"}"

Adding your access token

You must provide your access token with every API call you make. You include your access token in the request's HTTP authorization header as a bearer credential.

For example, if your access token is: d567fde24865df35defff57862dw2r42, your cURL request would look like this:

Example cURL Request
curl -X PATCH "" -H "Authorization: Bearer d567fde24865df35defff57862dw2r42" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"Charlie's Group\"}"


If you do not have an access token, you must request one.

Please refer to the topic How to authenticate API calls for further information on how to do this.

Handling errors

The API returns an error if your request could not be completed. For example, you might receive an error because:

  • You did not provide a required parameter in the call
  • You did not provide a valid request body in the call
  • There was an error on our end

To help you interpret the cause of an error, the API returns a human-readable error message in the call's response body. The message explains what caused the error and helps you to troubleshoot it.

For example, in this scenario if you make a call to the PATCH/subscriber-groups/{subscriberGroupId} endpoint and you provide a subscriberGroupId that does not exist on your account, you will receive a 404 error.

This is an example of how the error appears in the response body:

Error Example
 error: {
   message: 'Error caused because the subscriberGroupId does not match any of the account's subscriber groups.',

Your response to the error will differ depending on the type of error that has been thrown.

  • Responding to Errors in the 4xx Range
    If you receive an error in the 4xx range it means there is a problem with the information provided in your call. For example, you may have provided a resource identifier that does not exist on your account, you may not have the permission to perform the action or you may have provided an invalid request body. We recommend that you review your call against the Reference documentation and validate that the resource(s) you are interacting with exist on your account.

  • Responding to Errors in the 5xx Range
    If you receive an error in the 5xx range it suggests there may have been an incident on our end. We recommend that you visit the status page to check if the service you are querying is down. If the error persists please contact the support team to report the issue.


If you are having difficulty resolving an error, please contact the support team.

In your ticket, please include the complete call you are trying to make as well as the response you are receiving.


View the topic Response and error codes for further information.

Interpreting the response

If your request is successful, the endpoint returns a 200 response code and a response body. Every endpoint's Reference documentation includes a response example and a response schema. This provides you with an overview of the information that is returned by each endpoint. 

In this scenario, a 200 response means that the group's name has been successfully updated. The response body for a successful request to this endpoint returns an array of information relating to the group you updated.

An example response body for this endpoint looks like this:

Response Body Example
  "content": {
    "id": 20,
    "name": "Charlie's Group",
    "hideTariffDetails": true,
    "numberOfUsersAttached": 5,
    "numberOfSubscribersAttached": 20

In this example, you can see from the response body that:

  • The group's unique identifier is 20 - this is represented in the id field.
  • The group's name is Charlie's Group - this is represented in the name field.
  • The users in the group cannot see billing information about the subscribers in the group - this is represented in the hideTariffDetails field.
  • There are 5 users in the group - this is represented in the numberOfUsersAttached field.
  • There are 20 subscribers in the group - this is represented in the numberOfSubscribersAttached field.


To find out what information is included in an endpoint's response, refer to its Reference documentation.