Getting started with Setyl’s API

This guide will assist you in getting started with Setyl’s API. To begin utilizing our API, please follow these steps:

Activate API for your company

To enable access to Setyl’s API, please contact Setyl support.

Note: Please note that you can only proceed with the subsequent steps once your company has been granted access to Setyl’s API.

Generate an API Key

To access Setyl’s API, you will need to obtain an API Key and a Consumer ID. To generate your API Key, please visit the Company Settings page.

Note: Please ensure that your Setyl account has the Owner role in order to access the page.

Click on the Add New API Key button to create a new API Key.

Note: Please make sure not to close the page before copying the Private API Key and Consumer ID. Once the page is closed, you will not be able to retrieve them again.

You have the flexibility to create multiple API Keys and utilize them to access your Setyl data through the API. In the event that your API Key is compromised, you can regenerate it by using the Rotate API Key option or, alternatively, delete the existing key and generate a new one.

Note: Keep your API Keys private!

Make your first call to API

You now have all the necessary steps completed to make your first call to Setyl’s API. Here’s an example of a curl command to the People API to help you get started. Remember to include the API Key as an Authorization: Bearer header and the Consumer ID as an X-Setyl-Consumer-ID header (refer to the example below).

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Setyl-Consumer-ID: YOUR_CONSUMER_ID" \
  https://app.setyl.com/api/v1/people

Replace YOUR_API_KEY with your actual API Key and YOUR_CONSUMER_ID with your Consumer ID in the curl command.

Note: It is essential to ensure that API calls to Setyl’s API are made server-side to prevent any potential token leakage.

Extras

Paging Data

Certain queries made to Setyl’s API may yield multiple pages of data. In such cases, the API response will include a cursor property that contains a token to retrieve the next page of results. If the cursor property does not contain a token, it indicates that you have reached the last page of data, and no further requests are necessary.

Below is an example curl command for the People API that includes a cursor parameter to request the next page:

curl --location --request 'https://app.setyl.com/api/v1/people' \
--header 'X-Setyl-Consumer-ID: YOUR_CONSUMER_ID' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"cursor": "CURSOR-TO-REQUEST-NEXT-PAGE"}'

Please ensure you replace YOUR_CONSUMER_ID with your actual Consumer ID and YOUR_API_KEY with your API Key. Additionally, remember to update the cursor value with the appropriate token to request the subsequent page of results.

Rate limiting

To ensure proper usage and protect the platform, Setyl’s API endpoints have rate limits in place. There are two types of rate limits: one based on the number of requests from a single IP address and another based on the total number of requests to Setyl’s API. These rate limits are calculated per minute.

Here are the rate limits:

  • Per IP: 50 requests
  • All requests: 500 requests

If these limits are exceeded, an HTTP status code of 429 will be returned. In such cases, you should retry the request after waiting for a while. The exact waiting time in milliseconds can be obtained from the RateLimit-Reset header, which is included in all responses with the 429 status code.