REST API Reference

Introduction

The BigChange API is organised around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

Something missing?

Our documentation is a priority to us and we strive to constantly improve it. Please reach out if you find an inaccurancy or have a suggestion on how we might make things better.

Authentication

Step 1 - Obtain credentials

BigChange uses OAuth 2.0 and the Client Credentials Grant to provide authentication for machine to machine use cases for all API endpoints.

To gain access, you must register the details of your application on the platform. Once approved, the application will be granted access and provided a client ID and client secret. It is critical that you safely store these credentials in a manner appropriate to the development platform you are using.

Step 2 - Request access token

Your application client id and client secret can now be exchanged for an access token, providing short-lived credentials for your application to access the API.

To obtain an access token, you will need to make a POST request to our token endpoint.

Step 3 - Call the API

Your application should then pass the retrieved access token as a Bearer token in the authorization header of your HTTP request to any of our documented API endpoints:

curl / cURL

curl --request GET \
  --url https://api.bigchange.com/v1/contacts \
  --header 'authorization: Bearer ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --header 'customer-id: 14532'

Accessing Customer Data

You'll also need to provide a customer-id header in every request. This will be provided to you when a BigChange customer has approved that your application can access their data. During development phase, we recommend that you use the sandbox customer id you will be provided.

Requests

HTTP Verbs

Where possible, the BigChange REST API strives to use appropriate HTTP verbs for each action.

• GET: Used to fetch a specific or a collection of resources.
• POST: Used to create a new resource.
• PUT: Used to update a existing resource.
• PATCH: Used to partially update an existing resource.
• DELETE: Used to delete resources.
  

Creating resources

The REST API creates resources by using requests aligned to the POST verb. Successful responses do not usually include the newly created resource in their response payload. Instead, the id of the new resource will be provided in the response body, alongside the the location header, providing the URL of the endpoint where the newly created resource can be obtained:

JSON response header

 api-supported-versions: 1.0 
 date: Wed,21 Jun 2023 10:56:47 GMT
 location: api-url-here/v1/contacts/14512231
 x-powered-by: ASP.NET 

Updating resources

The API uses both PUT and PATCH verbs to update resources, each used for different use cases and behaviours.

• PUT endpoints are generally used to update data that needs to change at the same time. Where request payloads can have both required and optional attributes, the latter will be set to a default value when omitted in a request. Every documented attribute in a PUT request body payload will replace any existing state, regardless of whether your request included it.

• PATCH endpoints are used to update data that can change independently. PATCH request payload attributes are entirely optional and you can provide as much or as little of the payload, depending on the data your application needs to update. Only the attributes included in a PATCH request will replace any existing state. All other state will be left untouched.

Responses

Status codes

The BigChange API makes use of standard HTTP status codes to indicate the outcome of a request.

Code	Description
200 - OK	The request has been fulfilled.
201 - Created	The request has been fulfilled and a new resource has been created.
204 - No Content	The request has been fulfilled but there is no need to send any data back.
400 - Bad Request	The request was badly formatted and/or not understood by the server.
401 - Unauthorized	The provided authentication credentials are incorrect or not present.
403 - Forbidden	The request lacks authentication credentials with the permissions to fulfill the request
404 - Not Found	The request could not locate a resource referenced by the URL.
429 - Too Many Requests	The request was not accepted because the application has exceeded the rate limit.
500 - Internal Error	The request triggered an unexpected error which will be logged and investigated.

Errors

When a request cannot be fulfilled, the API will return the appropriate status code and message, as well as more detailed information in the response body as structured below.

JSON response body

{  
  "status": 404,
  "title": "The Contact with id 12345 was not found.",
}

Eventual Consistency

Our API operates on an eventual consistency model, meaning that write operations might not be immediately reflected by subsequent reads. Reads will generally be consistent within a few milliseconds, but this can take longer.

Integrators should design their system to be resilient to delays in read consistency. This can be achieved by retrying after a short delay when an expected change isn't yet visible.

Versioning

The BigChange REST API uses a URI based versioning scheme. The current API version is v1.

The API will evolve over time and whilst every effort is made to develop in an unimpactful way, there may be situations where we need to make breaking changes and publish a new API version. We consider breaking changes to be:

• Renaming or removing an existing field or endpoint
• Changing the URL structure of an existing endpoint
• Changing the parameters that an existing endpoint provides
• Changing error response codes that an endpoint provides
• Modifying or adding a new validation to an existing resource
• Changing the data type of an existing field
• Requiring a parameter that wasn't previously required

Where breaking change is necessary a new version of the API will be published and documented. Older API versions will remain functional for a determined amount of time to ensure that existing integrations can continue to operate uninterrupted.