canonical: https://jentic.com/apis/scheduletocall.me/scheduletocall

# Schedule to Call Me Integration API

The Schedule to Call Me Integration API books phone callbacks for a set time: at the scheduled moment the service rings your verified callback phone, optionally speaks a private announcement, and connects you to the destination number. Calls are created idempotently with a destination, a scheduled_for time, and a timezone, and can be listed, read, rescheduled, or cancelled while pending, with row_version and If-Match guarding against conflicting edits. Phone numbers in responses are always masked to their last four digits, and recording can be set to off, regular, or silent per call. The API is in preview at version 1.0.0-preview.

## For AI agents

Schedule a phone callback that rings your phone and connects you to a destination number at a set time, then list, reschedule, or cancel pending calls.

## Scope

Does not send SMS, record voicemail, or manage calendar events. Use for scheduling, rescheduling, and cancelling phone callbacks only.

## Capabilities

- Schedule a callback to a destination number at a scheduled_for time in a named timezone, with an Idempotency-Key for safe retries
- Add a private announcement_message of up to 1000 characters that is spoken only to your callback phone before connecting
- Choose recording_mode off, regular, or silent per call, or fall back to the saved default
- Reschedule a pending call to a new time, or cancel it, using If-Match with the current row_version
- List calls with a status filter and a limit of up to 50, or fetch one call by callId
- List your verified callback phones, masked to their last four digits, with caller-ID approval status

## Use cases

### AI agent booking a call for later

When a user tells their agent to call a supplier first thing tomorrow, the agent searches Jentic for 'schedule a phone callback', loads the createScheduledCall operation, and books the call with the destination, scheduled_for time, and the user's timezone. It can add an announcement_message reminding the user what the call is about, and the integration credential is injected at call time.

Example prompt: POST `/api/v1/integration/calls` with destination +14155550123, scheduled_for 2026-11-21T14:00:00Z, timezone America/New_York, and announcement_message 'Call about the late shipment', with an Idempotency-Key

### Rescheduling and cancelling safely

Plans change, and two edits at once should not silently overwrite each other. Each call carries a row_version, and the reschedule and cancel operations require it in an If-Match header along with an Idempotency-Key, so a stale or repeated request fails cleanly instead of moving the wrong booking. Only pending calls can be rescheduled or cancelled.

Example prompt: GET `/api/v1/integration/calls/{callId}` for call call_01HZX, then PATCH `/api/v1/integration/calls/{callId}` with If-Match set to its row_version, scheduled_for 2026-11-21T16:30:00Z, and timezone America/New_York

### Reviewing upcoming calls without exposing numbers

An assistant summarizing the day can list scheduled calls with a status filter and see each call's time, timezone, recording mode, and masked destination with its country. Because phone values are masked to the last four digits, the summary is useful without full numbers ever appearing in responses.

Example prompt: Call GET `/api/v1/integration/calls` with limit 50 and summarize each call's scheduled_for, timezone, and destination last4

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/integration/calls` | Create a scheduled callback |
| GET | `/api/v1/integration/calls` | List masked calls |
| GET | `/api/v1/integration/calls/{callId}` | Get one call |
| PATCH | `/api/v1/integration/calls/{callId}` | Reschedule a pending call |
| DELETE | `/api/v1/integration/calls/{callId}` | Cancel a pending call |
| GET | `/api/v1/integration/phones` | List verified callback phones |

## Key resources

- **Calls** — Scheduled callbacks with time, timezone, masked destination, recording mode, and row_version
- **Callback phones** — Your verified phones, masked, with caller-ID approval status

## 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:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 94 / 100
  - Security: 75 / 100
  - AI Discoverability: 58 / 100
- **View full report:** https://jentic.com/apis/scheduletocall.me/scheduletocall/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 Schedule to Call Me by hand means choosing between an stcm bearer key and a Clerk OAuth flow with scopes, generating an Idempotency-Key per write, and threading row_version into If-Match on every change. Through Jentic you install once, import it from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Schedule to Call Me puts the call id in the URL path (`/api/v1/integration/calls/{callId}`), so a rule can pin your agent to one booked call and the operations you pick. You choose the operations it may call, so changes like rescheduleCall or cancelCall are not included unless you add them.
- **Credential handling:** Your Schedule to Call Me credential 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 'schedule a phone callback' or 'reschedule a call', and Jentic returns the matching operation, such as createScheduledCall or rescheduleCall, with its input schema and required headers.

## Related APIs

- **Calendly API** — Scheduling links and booked meetings
- **Saperly API** — AI phone numbers, outbound calls, and SMS
- **Twilio API** — Programmable voice and messaging

## FAQ

### What authentication does the Schedule to Call Me Integration API use?

Per its OpenAPI spec, every operation accepts either a bearer integration credential, formatted as stcm_test_ or stcm_live_ keys, or OAuth 2.0 authorization code through Clerk with the scopes calls:read, calls:write, and phones:read. Reads need calls:read or phones:read and changes need calls:write. Through Jentic the credential is stored by your own instance and attached at call time.

### Why are phone numbers masked in Schedule to Call Me responses?

The API masks every phone value in responses: destinations show only last4 and country, and callback phones and caller IDs show only last4. The optional announcement_message is encrypted at rest and excluded from call responses and webhooks.

### How do I reschedule a call without conflicts?

Read the call to get its row_version, then send the reschedule with If-Match set to that value, an Idempotency-Key, and the new scheduled_for and timezone. Cancelling uses the same two headers. Both work only on pending calls.

### What are the rate limits for the Schedule to Call Me Integration API?

The OpenAPI spec does not specify rate limits. Check https://scheduletocall.me for current limits.

### Is there a Schedule to Call Me MCP server?

You don't need an MCP server to give your agent Schedule to Call Me. Jentic connects it directly from the API Directory: import it, store your integration credential once, and your agent calls the scheduling operations when it needs them.

### How do I schedule a callback through Jentic?

Search Jentic for 'schedule a phone callback', load the createScheduledCall operation, and execute POST `/api/v1/integration/calls` with destination, scheduled_for, and timezone, plus an Idempotency-Key header. 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 Schedule to Call Me Integration API?

Yes. Allow only GET `/api/v1/integration/calls` and GET `/api/v1/integration/phones`, and the agent can report on upcoming calls and verified phones but cannot book, move, or cancel anything. Every call it makes is logged.
