The Xemplo follows the general patterns of REST. Applications can manage the resources (such as companies, workers, and invoices) of a Xemplo account by making HTTPS requests to URLs that represent those resources. For a list of Xemplo resources and operations, see Xemplo API Reference.

Overview

Before you call the Xemplo API, you need two items: a Xemplo account and an Client ID. For information about creating a Xemplo account and requesting a client ID, see Introduction.

If you know a few patterns, you can call any Xemplo API. The following sections introduce the common patterns. cURL examples are used to keep it simple.

Get an authorization token

All Xemplo APIs require authentication using your client ID and secret. Please see Authentication for more information on authenticating your API requests.

Create an HTTPS request

To perform operations on a resource, you make an HTTPS request that specifies the URL for the resource to act on, as well as the appropriate headers, method, request body, and query parameters.

Your Xemplo account will have its own xemplo.com subdomain where you will need to make your API calls. We will use "example.xemplo.com" to demonstrate below.

For example, the following cURL command passes a JSON object containing the values used to create a new company in a Xemplo account using the Create Company endpoint:

curl https://example.xemplo.com/api/v1/companies \
  -X POST \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "XYZ Business Solutions",
    "registeredName": "XYZ Business Solutions PTY LTD",
    "companyNumber": "123123123",
    "defaultCurrency": "AUD"
  }'

In the request:

• {ACCESS_TOKEN} is a valid Xemplo access token.
• A successful call returns a response with 200 status code and a response body with the newly created company as a JSON object that looks like the following:

{  
  "id": 123,
  "name": "XYZ Business Solutions"
}

Now that you've seen what a Xemplo API call looks like, you can review it line by line.

Specify a resource URL

You access a resource with its URL. See the URLs for each resource in the Xemplo API Reference. The base domain will be specific to your Xemplo account.

In the example, the first line of the preceding cURL command specifies the URL for the resource you want to work with. In our case, it was to the companies resource in the example Xemplo account.

curl https://example.xemplo.com/api/v1/companies

📘

Note the following:

The current major version of the Xemplo API is version 1. Make sure that v1 is specified in the resource path of your requests.

Specify the HTTP method

You specify an HTTP method to perform an action on a resource. The common actions in the Xemplo API are:

• GET to read or list resources.
• POST to create.
• PUT or PATCH to update.
• DELETE to delete.

In the following example, the call is creating a company and uses the POST method:

curl https://example.xemplo.com/api/v1/companies
  -X POST

Set the headers

You use HTTP headers to specify additional information about the call.

In the following example, the call specifies two headers:

curl https://example.xemplo.com/api/v1/companies
  -X POST
  -H 'Authorization: Bearer {ACCESS_TOKEN}'  
  -H 'Accept: application/json'  

📘

Note the following:

Authorization - This header is required. It contains the credentials used for the call and the type. The Xemplo access token is the bearer token.

Accept - You provide this header to specify the type of data the calls return. Currently, application/json is supported.

Create the request body

Typically, you use the request body to pass complex parameters (for operations such as create, update, and search) as a JSON object.

In the following example, the call has a request body containing a JSON object with the values used to create a new company:

curl https://example.xemplo.com/api/v1/companies \
  -X POST \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "XYZ Business Solutions",
    "registeredName": "XYZ Business Solutions PTY LTD",
    "companyNumber": "123123123",
    "defaultCurrency": "AUD"
  }'

More values could have been provided, but the above request supplies just the mandatory company properties.

Specify query string parameters

Use query string parameters for sorting, filtering, or paging in list operations. List operations use query string parameters to specify how to return the list of resources.

For example, the Search Companies endpoint lets you filter the list of companies returned by the type of company or status. The following cURL command returns the list of companies where the company type includes Employer of Record (EOR):

curl 'https://example.xemplo.com/api/v1/companies?type=EOR'
  -X GET  
  -H 'Authorization: Bearer {ACCESS_TOKEN}'  
  -H 'Accept: application/json'

All list and search operations are paginated and have a page size that specifies the number of resources returned in a single list endpoint call. For more information about how to return a set number of results from a Xemplo API, go to Pagination in Search APIs.

Handle the response

API calls return a JSON object that contains the resources requested or an errors list. Check the response status code to see whether the response succeeded or failed.

Success responses

Successful responses are marked by an HTTP 200 status code. Create and update operations return the details of the resources operated on. List and search operations also return a cursor if there's another page of resources to return.

In the previous Create Company example, a successful call returned a JSON object representing the new customer and it looked like the following:

{  
  "id": 123,
  "name": "XYZ Business Solutions"
}

Read the response payload:

• For an operation on a single object, the response contains a single JSON object of the relevant type. All of our entities will have at least an id property to identify it.
• For list and search operations, the response contains a JSON array of matching entries. A X-Total-Count header is also supplied indicating the total number of matching entries, as the response may contain just a single paged array of results.
• The Xemplo API doesn’t support bulk updates. You can work on only one object per request.