canonical: https://jentic.com/apis/saperly.com/saperly

# Saperly API

The Saperly API gives an AI agent its own phone line: it provisions phone numbers, binds them to connections that answer calls and messages, places and transfers outbound calls, and sends SMS. A connection runs in hosted mode, where an in-network voice assistant follows your instructions, or manual mode, where your own LLM receives each conversation turn. Calls expose recordings and transcripts, and the API also covers consent records, voices and custom voice samples, number price quotes, usage summaries, outbound webhooks signed with HMAC-SHA256, and scoped API keys with number allow-lists and spend caps.

## For AI agents

Provision phone numbers, place and transfer AI voice calls, send SMS, and read call transcripts and recordings, with consent tracking and scoped keys bounded by number and spend.

## Scope

Does not handle email, video meetings, or contact management. Use for AI phone numbers, calls, SMS, and consent records only.

## Capabilities

- Provision a phone number by country, numberType such as local or toll_free, and areaCode, after quoting its price
- Create a hosted or manual connection with its own instructions and bind it to a number to answer calls and SMS
- Place an outbound call from a Saperly number with per-call instructions, then end it or blind-transfer it to a number or sip: URI
- Send an SMS of up to 1600 characters from one of your numbers, checked against the recipient's opt-out status
- Fetch a call's transcript or a redirect to its recording after the call
- Record, check, and revoke consent per contact with consentType implied_inbound or explicit_outbound
- Mint child API keys limited by scopes, a numberScope allow-list, and spendLimitCents

## Use cases

### AI agent making outbound calls

An agent asked to confirm appointments searches Jentic for 'place a phone call', loads the voice.place operation, and calls each customer from a Saperly number with a per-call instructions prompt describing what to confirm. After the call it reads the transcript to record the outcome, and the Saperly key is injected at call time rather than handed to the agent.

Example prompt: POST /calls with fromNumberId num_123, to +14155550123, and instructions 'Confirm the 3pm appointment tomorrow', then GET `/calls/{id}/transcript` once the call ends

### Giving an assistant its own phone line

A team that wants an AI receptionist provisions a number with the country, numberType, and areaCode they need, creates a hosted connection whose instructions describe the assistant's behaviour, and binds the connection to the number. Inbound calls and messages on that line are then answered by the connection, and a manual connection hands each turn to your own LLM instead.

Example prompt: GET `/pricing/quote` with country US and numberType local, POST /numbers with country US and areaCode 415, POST /connections with name 'Front desk' and mode hosted, then POST `/numbers/{id}/connection` with the new connectionId

### Consent-aware SMS outreach

Texting a contact responsibly starts with knowing they agreed to it. The consent check operation takes numberId and peerNumber and reports whether active consent exists, consent records store consentType and a source note for the audit trail, and SMS sends are checked against the recipient's STOP status before leaving the network.

Example prompt: GET `/consent/check` with numberId num_123 and peerNumber +14155550123, and only if consent is active POST /messages with fromNumberId num_123, to +14155550123, and body 'Your order has shipped.'

### Delivery debugging for webhooks

Saperly POSTs subscribed events such as call.completed and message.received to workspace webhook endpoints, each signed in the x-saperly-signature header. When events stop arriving, the deliveries operation lists recent attempts with outcome, responseStatus, and attempt number so the failing receiver is easy to spot.

Example prompt: GET `/workspaces/{slug}/webhooks/{webhookId}/deliveries` for workspace acme and report any failed attempts with their responseStatus

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/numbers` | Provision a phone number |
| POST | `/connections` | Create a hosted or manual connection |
| POST | `/numbers/{id}/connection` | Bind a connection to a number |
| POST | `/calls` | Place an outbound call |
| GET | `/calls/{id}/transcript` | Get a call transcript |
| POST | `/messages` | Send an SMS message |
| GET | `/consent/check` | Check a contact's consent |
| POST | `/api-tokens` | Mint a scoped API key |

## Key resources

- **Numbers** — Phone numbers with caller ID name, SMS sender id, and a bound connection
- **Connections** — The hosted or manual brain that answers a line
- **Calls** — Outbound and inbound calls with recordings and transcripts
- **Messages** — SMS sent from or received on your numbers
- **Consent records** — Per-contact consent scoped to one of your numbers
- **API keys** — Scoped keys with numberScope allow-lists and spend limits

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 87 / 100
- **Maturity:** AI-Ready
- **Dimensions:**
  - Foundational Compliance: 73 / 100
  - Developer Experience & Jentic Compatibility: 100 / 100
  - AI-Readiness & Agent Experience: 100 / 100
  - Agent Usability: 94 / 100
  - Security: 100 / 100
  - AI Discoverability: 58 / 100
- **View full report:** https://jentic.com/apis/saperly.com/saperly/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Saperly by hand means working out how to present an sk_ key that the spec never declares, chaining number quotes, provisioning, and connection binding, and verifying HMAC-signed webhooks. Through Jentic you install once, import Saperly from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Saperly carries the sending number inside the request body (fromNumberId on calls and messages), so a Jentic rule bounds which operations your agent may call, such as placing calls and reading transcripts, not which number it uses; pair it with a Saperly child key whose numberScope limits the numbers. You choose the operations it may call, so destructive ones like number release or connection deletion are not included unless you add them.
- **Credential handling:** Your Saperly key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'place a phone call' or 'send an SMS', and Jentic returns the matching Saperly operation, such as voice.place or messaging.send, with its input schema.

## Related APIs

- **Bland AI API** — AI phone agents for outbound and inbound calls
- **Retell AI API** — Voice AI agents for phone calls
- **Twilio API** — General-purpose programmable voice and messaging
- **Deepgram API** — Speech-to-text and audio intelligence

## FAQ

### What authentication does the Saperly API use?

The Saperly OpenAPI spec does not declare a security scheme. Its description says the agent data plane resolves your organization from an sk_ API key, and that a key with keys:admin can mint child keys bounded by its own ceiling. Check the Saperly docs at https://saperly.com for how to send the key. Through Jentic the key is stored by your own instance and attached at call time.

### Can I limit what a Saperly API key can do?

Yes, on Saperly's side. The mint key operation accepts scopes of read, write, or admin, a numberScope allow-list of phone numbers, and a spendLimitCents cap with an optional monthly reset, each within the minting key's own ceiling. The plaintext key is returned once, in the response to that call.

### What is the difference between hosted and manual connections?

In hosted mode an in-network voice assistant answers the line using the connection's instructions. In manual mode your own LLM is the brain: Saperly forwards text turns and executes the directives you return. Audio stays in Saperly's network in both modes.

### What are the rate limits for the Saperly API?

The OpenAPI spec does not specify rate limits. Check the Saperly documentation at https://saperly.com for current limits.

### Is there a Saperly MCP server?

Yes. The Saperly spec describes a separate JSON-RPC MCP surface at /mcp. You can also connect the API directly through Jentic: your agent gets the full 48-endpoint surface from the spec without loading another server's tool definitions into its context, your key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### How do I place a call with Saperly through Jentic?

Search Jentic for 'place a phone call', load the voice.place operation, and execute POST /calls with fromNumberId and a to number in E.164 format, adding instructions to steer that call. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Saperly API?

Yes. Allow POST /calls, GET `/calls/{id}/transcript`, and GET `/consent/check`, and the agent can phone customers and read the results, while number release, connection deletion, and key minting stay off its list. Every call it makes is logged.
