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

# RevDesk v1 API

The RevDesk v1 API places outbound AI voice calls and human bridge calls, sends SMS, and manages the phone numbers, caller IDs, and caller reputation behind them for a sales or service team. It also covers AI agent configuration, contacts, call transcripts, outcome-driven tasks that RevDesk pursues across channels, webhook subscriptions for call and SMS events, number health testing, CNAM and Free Caller Registry registration, and usage. An organization-scoped API key authorises each operation against the permission it declares, such as calls:write or sms:read.

## For AI agents

Place outbound AI or bridged calls, send SMS, buy and configure phone numbers, check number spam reputation, read call transcripts, and hand RevDesk tasks to pursue across channels.

## Scope

Does not handle email campaigns, CRM deal pipelines, payments, or video meetings. Use for AI and bridged phone calls, SMS, and the phone numbers and caller reputation behind them only.

## Capabilities

- Place a single-leg outbound AI call to a phoneNumber with POST `/v1/calls`, optionally choosing the assistantId and script
- Bridge your from_number to a destination with POST `/v1/calls/dial`, with record and amd settings and an optional connect_number for the human leg
- Send an SMS from an owned number with POST `/v1/sms/send` using to, from, and message
- Search available numbers by country, area_code, and number_type, then purchase one with POST `/v1/phone-numbers`
- Enroll numbers in reputation monitoring and read Hiya-sourced spam risk scores for a number from `/v1/caller-trust/reputation/numbers/{phone}`
- Hand RevDesk an outcome with POST `/v1/tasks`, giving an objective, deadline, success_criteria, and guardrails such as quiet_hours and max_touches
- Read a finished call's transcript from `/v1/calls/{id}/transcript` and subscribe a webhook_url to events such as call_completed or sms_delivered

## Use cases

### Agent-placed outreach calls through Jentic

A sales agent connected through Jentic searches by intent for placing an AI phone call, gets POST `/v1/calls` with its schema, and dispatches a call to the lead's phoneNumber with a short script. When the call completes, the agent reads GET `/v1/calls/{id}/transcript` and writes the outcome into the CRM, so the next step is based on what was actually said.

Example prompt: POST `/v1/calls` with phoneNumber '+14155550123', name 'Jordan', and script 'Follow up on the pricing proposal', then GET `/v1/calls/{id}/transcript` once the call has ended

### Number reputation and spam-label remediation

Outbound numbers that carriers label as spam stop getting answered. An agent enrolls the team's numbers with POST `/v1/caller-trust/reputation/numbers`, reads each number's spam risk and component scores, and submits flagged numbers for remediation with POST `/v1/caller-trust/reputation/remediations.` Cached reads are free, while fresh=true forces a live billed carrier query.

Example prompt: POST `/v1/caller-trust/reputation/numbers` with phone_numbers ['+14155550123'], then GET `/v1/caller-trust/reputation/numbers`/+14155550123 with fresh false and submit it to `/v1/caller-trust/reputation/remediations` if the risk is high

### Outcome tasks with guardrails

Instead of scripting every touch, POST `/v1/tasks` hands RevDesk an objective, such as booking a meeting with a contact_id, plus a deadline, success_criteria outcome_kinds, and guardrails covering channels, quiet_hours, and max_touches. RevDesk works across calls and SMS until the criteria are met, the deadline passes, or a guardrail stops it, and GET `/v1/tasks/{taskId}` reports progress.

Example prompt: POST `/v1/tasks` with type 'outreach', objective 'Book a demo with this contact', contact_id 'c_123', and guardrails {channels: ['sms','call'], quiet_hours: {from: 20, to: 8, time_zone: 'America/Los_Angeles'}, max_touches: 3}

### Number provisioning and SMS auto-reply

An operations agent searches available numbers with GET `/v1/phone-numbers/search` by country, area_code, and number_type, buys one with POST `/v1/phone-numbers`, and then sets its CNAM display name, recording, and assigned agent_id with PATCH `/v1/phone-numbers/{id}.` A per-number SMS auto-reply override can be set with reply_delay_seconds and a default_prompt.

Example prompt: GET `/v1/phone-numbers/search` with country 'US', area_code '415', number_type 'local', limit 5, then POST `/v1/phone-numbers` with the chosen phone_number and name 'SF sales line'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/calls` | Place an outbound AI call |
| POST | `/v1/calls/dial` | Bridge two phone numbers |
| POST | `/v1/sms/send` | Send an SMS message |
| GET | `/v1/calls/{id}/transcript` | Retrieve a call transcript |
| GET | `/v1/phone-numbers/search` | Search available phone numbers |
| GET | `/v1/caller-trust/reputation/numbers/{phone}` | Get reputation scores for a number |
| POST | `/v1/tasks` | Create an outcome task |
| POST | `/v1/webhook_subscriptions` | Create a webhook subscription |

## Key resources

- **Calls** — Outbound AI calls, bridged dial calls, call records, and transcripts
- **Phone numbers** — Owned numbers with CNAM, recording, transcription, assigned agent, and SMS settings
- **Caller trust** — Caller IDs, brand and enterprise registration, LOA documents, and number reputation
- **Agents** — AI voice agents with greeting, system_prompt, voice_id, and language
- **Tasks** — Outcome-driven objectives with deadlines, success criteria, and guardrails
- **Webhook subscriptions** — HTTPS callbacks for call, SMS, number, and registration events

## 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:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 80 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 50 / 100
  - Agent Usability: 79 / 100
  - Security: 60 / 100
  - AI Discoverability: 88 / 100
- **View full report:** https://jentic.com/apis/revdesk.com/revdesk/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 RevDesk by hand means managing an organization-scoped bearer key with the right x-required-scopes for each area, sending Idempotency-Key headers on writes, and keeping legacy deprecated paths apart from their replacements. Through Jentic you install once, import the RevDesk v1 API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** RevDesk puts phone number, agent, and call ids in the URL path (`/v1/phone-numbers/{id}`, `/v1/agents/{id}`, `/v1/calls/{id}`), so a rule can pin your agent to one phone number's settings or one AI agent's configuration. You choose the operations it may call, so actions like releasing a number with DELETE `/v1/phone-numbers/{id}` or placing calls are not included unless you add them.
- **Credential handling:** Your RevDesk API 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 an AI phone call' or 'check if my number is flagged as spam', and Jentic returns the matching RevDesk operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Bland AI API** — AI phone calls with programmable voice agents
- **Retell AI API** — Voice AI agents for inbound and outbound calls
- **Telnyx API** — Programmable voice, messaging, and number provisioning
- **Aircall API** — Cloud phone system for sales and support teams

## FAQ

### What authentication does the RevDesk v1 API use?

Per its OpenAPI spec, the API takes an organization-scoped RevDesk API key as a bearer token in the Authorization header, and each operation declares the permission it needs in x-required-scopes, such as calls:write, sms:write, or caller_trust:read. The sandbox endpoints at `/v1/sandbox` need no auth and never read tenant data. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### What is the difference between POST `/v1/calls` and POST `/v1/calls/dial`?

POST `/v1/calls` dispatches a single-leg outbound AI call: an AI agent, chosen by assistantId or your most recently created agent, joins and speaks, using one channel. POST `/v1/calls/dial` bridges your from_number to a destination for a human call, using two concurrent channels, and requires to_number, record, and amd.

### Which SMS endpoint should I use with the RevDesk v1 API?

Use POST `/v1/sms/send` with to, from, and message, where from must be an active number your organization owns. The older POST `/v1/messages` is marked deprecated in the spec, as are the legacy `/v1/jobs` paths, which `/v1/tasks` replaces.

### What are the rate limits for the RevDesk v1 API?

The OpenAPI spec does not give a general rate limit. It does state that a fresh reputation read on GET `/v1/caller-trust/reputation/numbers/{phone}` is a billed live carrier query limited to one per day per number, while cached reads are free. Check https://docs.revdesk.com for current limits.

### Is there a RevDesk MCP server?

You don't need an MCP server to give your agent the RevDesk v1 API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. Operations are found by intent when needed, so no extra tool definitions sit in your agent's context.

### How do I place an AI phone call through Jentic?

Install Jentic One, add the RevDesk v1 API from the directory, and store an API key with the calls:write permission. Your agent searches for 'place an outbound AI phone call', gets POST `/v1/calls` with its schema, and calls it with the phoneNumber and an optional script. 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 RevDesk v1 API?

Yes. Write a rule that allows only GET `/v1/calls`, GET `/v1/calls/{id}`, and GET `/v1/calls/{id}/transcript`, so the agent can review calls and read transcripts but cannot dial, send SMS, or buy numbers, and every call it makes is logged.
