Ringsnitch API

Ringsnitch tracks the calls your marketing produces: which ad, keyword or page each call came from, and what happened on it.

Base URL: https://ringsnitch.tone.fyi

Authentication

Create an API key in the Ringsnitch console under API keys. Keys carry scopes; a request that needs a scope the key doesn't have gets 403 with insufficient_scope.

Send your API key in the Authorization header:

Authorization: Token token="YOUR_API_KEY"

Scopes

`calls:read`	Read calls and call details
`recordings:read`	Read recordings and transcripts
`trackers:read`	Read tracking numbers
`users:read`	Read users
`trackers:write`	Change tracking numbers and routing
`account:admin`	Full account administration

Rate limits

Each account can make 1,000 requests per 1 hour. Over the limit, requests get 429 with a Retry-After header. Responses carry X-Rate-Limit-Limit, X-Rate-Limit-Remaining and X-Rate-Limit-Window.

Pagination

List endpoints are paginated with page and per_page. Responses include page, per_page, total_pages and total_records.

Times

Timestamps are ISO 8601.

Errors

Errors return a JSON body: {"error": {"code": "...", "message": "..."}}.

Endpoints

GET `/v3/a/:account/calls.json`

List calls on the account, newest first.

Scope: calls:read

`start_date`	Only calls that started at or after this date.
`end_date`	Only calls that started before this date.
`fields`	Comma-separated list of additional fields to return. See Call fields.
`page, per_page`	Page number and page size (maximum 250).

GET `/v3/a/:account/calls/:id.json`

Get one call. Accepts fields.

Scope: calls:read

GET `/v3/a/:account/calls/:id/recording`

Download a call's recording (MP3), when one exists. The call's recording field holds this URL.

Scope: recordings:read

Webhooks

Webhooks are signed following the Standard Webhooks specification (webhook-id, webhook-timestamp, webhook-signature). Deliveries are retried on failure, and may occasionally arrive more than once.