Simio API reference: conversational REST API

The Simio REST API lets you send campaigns, trigger automations and manage segments from your own systems. Base URL: https://getsimio.app/api

The Simio API is a REST API that lets you integrate conversational marketing into your own systems. Use it to send campaigns, trigger automations and build segments of contacts. This reference covers every endpoint, parameter and response shape you need to build a production integration.

Base URL

All API requests are made to the following base URL:

https://getsimio.app/api

The Simio web application is available at getsimio.app.

Authentication

Every request must include your company API key in the simio-api-key header. Keys are generated by an admin in the Simio application under Settings → Integrations & developers → Credentials. See the Authentication page for full details.

Request format

Send all request bodies as JSON with the Content-Type: application/json header. All string values must be UTF-8 encoded.

curl -X POST https://getsimio.app/api/campaigns/send \
  -H "simio-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": 42, "contacts": ["[phone]"] }'

Response format

Every response body is JSON. Successful responses use HTTP 2xx status codes. Sending endpoints are asynchronous: they return 202 Accepted once the request is queued, and messages are delivered in the background.

Error responses contain a detail key with a human-readable message:

{
  "detail": "Invalid API key"
}

Validation errors (422) return detail as a list describing each invalid field:

{
  "detail": [
    {
      "loc": ["body", "campaign_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Rate limits

Rate limits are applied per endpoint. When you exceed a limit, the API returns 429 Too Many Requests with a body of the form { "error": "Rate limit exceeded: ..." }. Wait before retrying, ideally with an exponential backoff.

Endpoint	Limit
POST /api/campaigns/send	10 requests per second
POST /api/automations/send	20 requests per second
POST /api/segments/create	10 requests per second
POST /api/segments/{segment_id}/contacts	1 request per minute
POST /api/batch/send	1 request every 10 seconds
POST /api/brevo/send	1 request every 10 seconds

If you need a higher rate limit for a high-volume integration, contact Simio support to discuss an increased quota.

HTTP status codes

Code	Meaning
200	Success
201	Created
202	Accepted: the request is queued for processing
400	Bad Request: invalid request body
401	Unauthorized: missing or invalid API key
403	Forbidden: no active subscription, or workspace not provisioned
404	Not Found: unknown campaign, automation or segment, or connector not connected
409	Conflict: for example, the maximum number of segments is reached
422	Unprocessable Entity: validation error
429	Too Many Requests: rate limit exceeded
500	Internal Server Error