Skip to main content

API & webhooks

Use Simplesat's API to export responses, sync customers from a CRM, trigger surveys from your product and act on new responses.

With Simplesat's REST API, your code can export responses and answers, keep customers in step with a CRM, and send a survey email when something happens in your product. Simplesat can also post new responses to an endpoint you choose. If your data is headed for a BI tool or warehouse, check the ready-made connections below before you write any code.

How it works

The base address is https://api.simplesat.io/api/v1/, and endpoint paths such as responses/search/ are relative to it. Requests and replies are JSON, and every call sends an API key in the X-Simplesat-Token header.

API keys explains how to create a key and choose its scopes. For every endpoint, field and example, see the full reference at developer.simplesat.io.

Connect a BI tool or data warehouse

Simplesat has ready-made connections for these tools:

  • Power BI

  • Data Studio

  • Fivetran

  • ConnectWise Reports and Dashboards

  • Google BigQuery

  • Amazon Redshift

  • Snowflake

  • Databricks

Each has its own article, such as Power BI integrations and Data Studio integrations. For any other tool, use the response and answer searches below.

What the API can do

What you can do

Endpoint

Scope a Custom key needs

Search responses

POST responses/search/

Responses Read

Get one response

GET responses/<id>/

Responses Read

Create or update a response for a ticket

POST responses/create-or-update/

Responses Write

Search answers

POST answers/search/

Answers Read

Get or update one answer

GET or PUT answers/<id>/

Answers Read or Write

List customers

GET customers/

Customers Read

Create or update a customer

POST customers/

Customers Write

Create or update up to 1,000 customers

POST customers/bulk/

Customers Write

Get or update one customer

GET or PUT customers/<id>/

Customers Read or Write

Create a team member

POST team-members/

Team members Write

Get or update one team member

GET or PUT team-members/<id>/

Team members Read or Write

List active surveys

GET surveys/

Surveys Read

List questions

GET questions/

Questions Read

Send an event-based survey email

POST surveys/<survey_token>/email/

Responses Write

The API can't list all team members, delete customers or team members, unsubscribe or resubscribe a customer, or return counts of answers per question. For those, use the Team members and Customers pages and survey dashboards in Simplesat.

Export responses and answers

For a bulk export, page through POST responses/search/ or POST answers/search/. There's no need to fetch each response from responses/<id>/, because a response search result already carries the same detail, including the ticket, team members, customer, custom attributes and every answer.

To get every page:

  1. Send the search with your filters in the request body. Put page and page_size in the query string, for example responses/search/?page_size=1000. A page holds 100 results by default and up to 1,000.

  2. POST the same body to the next link in the reply.

  3. Repeat until next is empty.

Both searches filter by created date with start_date and end_date. For an incremental sync, response search can also filter by when responses last changed, with modified_start_date and modified_end_date. Answer search can't.

Heads up: A misspelled date field is ignored without an error, and a search with no dates falls back to the last 30 days by created date.

To export a long history, split it into shorter date ranges. A search that runs too long stops with HTTP 503 and "Query timed out. Please try to narrow down your filter."

Add and update customers

POST customers/ creates a customer, or updates the existing customer with the same email address.

Warning: Sending custom_attributes or tags replaces all of the customer's existing ones. Include every attribute or tag the customer should keep.

Custom attributes need no setup, because writing a value to a new name creates the attribute. A misspelled name creates one too. Each value must be text, a whole number, true or false, or a list. An object or a decimal number is refused. For more on customers and their attributes, see Customers.

POST customers/bulk/ takes up to 1,000 customers in one call. It replies HTTP 200 first, then checks each row against the same rules as POST customers/ and drops any row that fails, with no error. Validate rows before you send them, and confirm afterward that the customers arrived.

The older path, POST /api/customers/create-or-update/, still works, but attributes it writes are saved with ss_api_ in front of their names. Sent through customers/, the same attribute becomes a second, separate one. Use customers/ for new code.

Trigger a survey email

Set up an event-based email survey as Direct email surveys describes, and it goes out whenever your system calls POST surveys/<survey_token>/email/. You can look up an active survey's token, along with its name, metric and type, with GET surveys/.

Send new responses to an endpoint

To have Simplesat POST responses to your own endpoint, use one of three integrations in Simplesat Tools, under Integrations:

  • Send data to API endpoint upon receiving a new response

  • Send data to API endpoint upon receiving a new response or an update to a response

  • Send data to API endpoint upon receiving an update to an existing response

Setting one up needs permission to manage integrations, which the Owner and Admins have.

  1. Connect the Simplesat Tools page with a Simplesat API key if it isn't connected yet. Your keys are under Admin → API keys.

  2. Expand the integration you want, then click Activate integration. Field mapping stays empty until you do.

  3. Enter your endpoint's full URL in the Endpoint row, under Field mapping.

  4. Leave Request set to Use data from response → Request. Mapping it to a single field breaks the integration.

  5. Click Save.

Your endpoint gets the whole response as JSON, with each answer also keyed by its question ID. You can't change the body's shape from Field mapping.

Each integration waits 5 minutes after the response before sending, to give the customer time to finish the survey. Simplesat adds no signature or authentication header to these requests.

If you'd rather not host an endpoint, use Zapier instead, as set out in Zapier integrations. The New Feedback trigger receives each new rating, and Zapier can send it on anywhere.

To send new responses to Slack or Microsoft Teams, see Slack integrations or Microsoft Teams integrations.

Rate limits

A workspace can make 120 calls a minute, shared by all of its keys, including keys that AI assistants use. The count resets at the start of each minute.

Counted calls reply with X-RateLimit-Limit and X-RateLimit-Remaining, plus X-RateLimit-Reset as a Unix time in seconds. A call over the limit gets HTTP 429 and a Retry-After header. Wait the number of seconds it gives, then retry.

These calls don't count toward the limit:

  • The survey email endpoint, surveys/<survey_token>/email/

  • The older /api/customers/create-or-update/

  • Calls refused for a bad key or a missing scope

Troubleshooting

My search request returns HTTP 405

Send POST to responses/search/ or answers/search/, and to each next link as you page through, because the searches don't accept GET.

My date-filtered search returns the last 30 days instead of my dates

A misspelled date field is ignored without an error, and a search with no dates covers the last 30 days. Check your field names against these. Response search reads start_date and end_date or created_start_date and created_end_date, plus modified_start_date and modified_end_date. Answer search reads only start_date and end_date.

My request returns 200 OK with no data

Check that the address includes /api/, since a call without it returns 200 with no data. The base address is https://api.simplesat.io/api/v1/.

I get 401 Authentication credentials were not provided

Despite the wording, the problem is the address. The call went outside the public API, for example to /api/customers/ without v1. Use the addresses under https://api.simplesat.io/api/v1/.

I get 403 No API Key Provided, Invalid credentials or Invalid Token

The key is missing from the X-Simplesat-Token header, mistyped, deleted or out of date. API keys walks through each fix.

I get 403 You do not have permission to perform this action

The key is Custom and doesn't have the scope this call needs. Find the endpoint's scope under What the API can do, then edit the key, as described in API keys, and select that scope.

I get 503 Query timed out

The search took too long. Use a shorter date range or add filters, and page through the results.

I suddenly get 429s on an integration that hasn't changed

The limit is 120 calls a minute for the whole workspace, across all its keys, so another tool, script or AI assistant calling the API at the same time uses the same allowance. Wait the seconds in Retry-After, then retry, and spread your calls across the minute.

FAQ

Do you have an API?

Yes. Once you've created a key, following API keys, work from the reference at developer.simplesat.io.

Do you have an SDK I can embed in my website?

No. Simplesat has no SDK or client library, so your code calls the REST API directly. To put a survey on your website, use a web embed, as Web embed surveys describes.

Can I get updates to existing responses, not just new ones?

Yes. Filter response search by modified_start_date and modified_end_date.

Is there an endpoint that lists all team members?

No. You can read one team member at a time by ID, with GET team-members/<id>/. The full list is on the Team members page.

Can I delete or unsubscribe a customer through the API?

No. Do it from the customer's record on the Customers page.

Can you raise our rate limit?

The limit is 120 calls a minute per workspace. To get more done within it, use a larger page_size on searches, send customers in batches through customers/bulk/, and spread calls across the minute. Survey emails sent through surveys/<survey_token>/email/ don't count toward the limit.

Will the API change without notice?

The reference at developer.simplesat.io calls the endpoints stable but still a work in progress.

Did this answer your question?