Configurable API

You can use the Slate Configurable API to export data in a format easily consumed by other web services. The Configurable API provides access to data in a clean, well-documented, tightly-scoped API.

Each Configurable API endpoint uses a query. You select its base, exports, and filters to control the data that an external service can retrieve. A grantee token authorizes requests to that API.

The Open API provides standard endpoints for Slate objects. It requires a valid Slate session for a user with Administrator permissions. For external services that use a token, use Configurable API.

To import data into Slate through a source format, see Importing Data with Web Services. That article covers push and pull methods and their authentication settings.

🔑 Requires the role Administrator (All Access)

Configuring the API

The Slate API builder is used to create a new API which will serve as a collection of endpoints.

To configure the API:

1. Go to Database → Slate Configurable API.

2. Select New API.

3. In the popup, enter an unique key and a name:

   • The name is for user reference.

   • The key is part of the endpoint where data is requested.

4. Click Save.

Adding endpoints

To add endpoints:

1. Select New Endpoint.

2. Configure the following settings:

   • Key: Enter a computer-friendly key (lowercase, no spaces). The key becomes a part of the URL that accesses the query. The final URL will have the form of /manage/service/api/{API KEY}/{ENDPOINT KEY}

   • Name: Enter a person-friendly, internal name for the endpoint.

   • Base: Select the base of the query, to be executed when this endpoint is called. Note: This cannot be changed later.

   • Parameter: Add an optional custom parameter to the endpoint.

     

3. Click Save.

4. Add any required exports. Any formatting you supply to the export will be carried over into the API. For example, you you can:

   • Give countries ISO alpha-2 codes

   • Render birthdates in the MM/DD/YYYY format

5. Filter the results as needed.

Access API documentation

Select Documentation on the API configuration page. In the documentation, select an endpoint and an operation to see its request URL, parameters, response fields, and request samples:

For an external request, include the grantee token as described in the following section.

Generating a token to authorize external access

Create a grantee to give an external service access to your API. Each request must include the grantee token in the Authorization header.

1. Go to Database → Slate Configurable API and select an API.

2. Select Edit Permissions.

3. Select Add Grantee.

4. Configure the following settings:

   • Active: Select Active.

   • Type: Select User Token.

   • Name: Enter a name that identifies the service or integration.

   • Token: Copy the generated token and store it in a secret manager or another secure credential store. If the token is exposed (appears in a public repository, client-side JavaScript, a screenshot, shared request logs), reset it and update the integration with the replacement token.

   • Allowed Networks: Optionally restrict access to specific IP addresses or CIDR subnets. Separate entries with commas, for example, 192.0.2.10,198.51.100.0/24. Use the public IP addresses from which the service sends requests.

   • Permissions: Select Access API. This permission allows the grantee to request data from the endpoints in this API. Each endpoint returns the data defined by its exports and filters.

5. Select Save.

Use the token in a request

1. Select Documentation.

2. Select an endpoint, then select a sample language.

3. Copy the request sample. If the sample contains Authorization: Bearer undefined, replace undefined with the grantee token.

4. Send the request from your external service over HTTPS.

For example, the cURL header has this format. Replace YOUR_GRANTEE_TOKEN with your token:

--header 'Authorization: Bearer YOUR_GRANTEE_TOKEN'

Use the endpoint URL from this API, in the form /manage/service/api/{API KEY}/{ENDPOINT KEY}. The API and grantee must be active, and the grantee must have Access API selected. If you set Allowed Networks, the request must come from an allowed address.

Filter an endpoint with a parameter

A parameter passes a value from the request URL to an endpoint filter. The parameter name must match in the declaration, filter, and request.

For example, use a Person endpoint to retrieve one person by GUID:

1. Create and save an endpoint with the Person base.

2. Open the endpoint and select Edit.

3. In Parameters, enter <param id="person" type="uniqueidentifier" />, then select Save.

4. Add the Person GUID export and any other exports that the service needs.

5. Add the Person GUID filter. Enter @person as its operand, then save the filter.

6. Open Documentation and select the endpoint's List operation.

7. Enter a person's GUID in the person parameter. Copy the request sample and replace the token placeholder with your grantee token.

The request URL has this format. Replace PERSON_GUID with the person's GUID:

/manage/service/api/{API KEY}/{ENDPOINT KEY}?person=PERSON_GUID

The declaration uses person, the filter uses @person, and the URL uses person=. The filter limits the response to the matching person. The List operation returns an array, including when only one record matches. If no record matches, it returns an empty array: [].

For this example, omitting person or leaving its value empty also returns []. Supply a valid GUID to retrieve a person. A value that is not a valid GUID causes an error.