API Basics

Heads up! MonkeyPod's API is only available to Enterprise users and requires significant technical expertise to use. The API is considered to be in "beta" and remains under active development. We will make reasonable efforts to ensure its stability, but make no guarantees, warranties, or promises with respect to its availability or performance. 

We strongly recommend using the PHP SDK to interact with the API and that we’re unable to provide technical support for the API unless (1) you encounter a bug, or (2) you’re using an official SDK. Here is a link to the documentation for the SDK.

Authentication

API requests are authenticated with through the use of HTTP Bearer tokens. Upon request, users may be granted API access and assigned a bearer token, which must be used in each API request.

Authorization

Each API token is associated with a single user account, and the permissions associated with the token match those associated with the underlying user account.

Resources

A current list of API-supported resources can be found in the documentation for the PHP SDK.

Request / Response Structures

MonkeyPod's API follows basic REST conventions. Requests and responses are structured as JSON documents, which generally map to underlying MonkeyPod resources.

Requests to create or update a resource should provide the JSON representation of that resource as the body of the request.

API responses that include a JSON document will generally nest the resource under a top-level "data" element, for example:

{
  "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
  "resource": "entity",
  "data":{
    "id": "960a735b-3ee9-4440-9c6d-25cbf27c77fe",
    "type":"Individual",
    ...
  }
}

Resource IDs are UUIDs. In most cases, MonkeyPod's API allows resource creation requests to optionally provide an ID, which will be assigned to the created resource so that you can reliably reference it in future requests. If you decide to generate your own UUIDs, you are solely responsible for ensuring their global uniqueness (don't reinvent this wheel; there are many good libraries that support UUID generation). If you do not provide your own ID, one will be assigned upon resource creation and included in the response JSON.

Timestamps are included with most responses, and are presented in UTC and formatted according to the ISO 8601 standard.

Pagination data is included when a top-level response represents a collection of resources. In these cases, the following metadata is added at the JSON document root:

• "current_page" - the current page number, defaults to 1
• "first_page_url" - the API endpoint for the first page of the paginated response data
• "next_page_url" - the API endpoint for the next page of the paginated response data, or null if this is the last page
• "prev_page_url" - the API endpoint for the previous page of the paginated response data, or null if this is the first page
• "from" - of the total resources in the response, the first in the current page's set
• "to" - of the total resources in the response, the last in the current page's set
• "path" - the basic endpoint for the collection of resources, without any page specified in the URL
• "per_page" - the number of resources per page

HTTP Status Codes in API responses typically follow these conventions:

• 200 - a GET request successfully retrieved a resource or resource collection, or a PUT request successfully updated a resource
• 201 - a POST request successfully created a resource
• 204 - a DELETE request successfully deleted a resource
• 401 - request authentication failed
• 403 - the API request is unauthorized for the authenticated user
• 405 - the request method is not supported for this endpoint
• 422 - request input failed validation (see "errors" in the response JSON for more information)
• 500 - an unspecified error occurred while processing the API request