Endpoints and Requests

Noteworthy conventions are:

• URLs should be hyphenated (e.g. /businesses/{businessId}/business-units)
• Attribute names are camelCased. (e.g. { "businessId": "..." })

Basic Response Object Structure

Each request that has a response body is structured in the following ‘blocks’

{  
  "body":{...},  
  "error":{...}  
}

Body will be an array when the response is a list, and an object if the response is a single item, or multiple lists/arrays.

Error is typically an object with two keys: code that is the http response code, and description which includes a reason that yielded the error/exception.

Error Codes

By default we follow the standard http response codes used by the industry.

404 Bad Request is used for requests using unsupported methods (the standard suggests a 405 in these cases).

409 Conflict is used if a request is rejected due to unique constraint conflicts (e.g. trying to create two phone number objects with the same phone number).

429 is used if a request is rejected due to API request limit throttling.