call4me Scheduled Calls API
The Scheduled Calls API from call4me — 2 operation(s) for scheduled calls.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/call4-me:call4-me-scheduled-calls-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: call4me Scheduled Calls API
version: 1.3.0
description: 'Phone calls an AI agent places for its user: call a business, follow the call to its outcome, answer the caller''s questions mid-call, and patch the user in. Also the prepaid balance, the caller profile, scheduled calls, the account''s phone numbers and call recordings. The same operations as the MCP server at /mcp. Calls are billed per minute from pickup (phone menus and conversation; hold time at half price) from the prepaid balance; unanswered calls are free. Refusals name MCP tools (call4me_place_call is POST /api/calls, call4me_save_profile is PATCH /api/profile).'
x-guidance: 'With a wallet and no account: POST /api/x402/calls with the call (to, business, goal, category, details, on_behalf_of, max_minutes) and pay the 402 in USDC on Base. A refusal (422 "Not calling yet") lists what to ask the user and takes no payment. The paid response returns the call id and an api_key; follow the call with GET /api/calls/{call_id}?wait_seconds=30 and Authorization: Bearer <api_key> until finished, answering open questions with POST /api/calls/{call_id}/answer. With an account: the bearer routes below, and GET /api to buy credits in USDC.'
contact:
name: call4me
email: me@call4.me
url: https://call4.me
servers:
- url: https://call4.me
tags:
- name: Scheduled Calls
paths:
/api/scheduled-calls:
post:
operationId: scheduleCall
description: Place a call later, when the user wants it at a set time (calls can go out at any hour, so a closed business is no reason to wait). Takes everything POST /api/calls takes, plus call_at, and checks it now. Nobody may be following the call when it runs, so give every fact and all the flexibility it needs up front. Credits are held when it dials.
security:
- bearerAuth: []
parameters:
- name: Idempotency-Key
in: header
required: false
description: 'A unique value per request (a UUID), kept on retries of it. A retry with the same key and body returns the scheduled call the first request made (200, with Idempotent-Replayed: true) instead of placing another; the same key with a different body is refused (422). Keys belong to the account and never expire. A request refused before anything was placed (422 "Not calling yet", 402) does not use up its key.'
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
minLength: 1
maxLength: 255
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
to:
type: string
minLength: 3
maxLength: 40
description: the number to call, e.g. "+14155550123", "(415) 555-0123", or abroad with its country code, e.g. "+31 20 123 4567"
business:
type: string
minLength: 1
maxLength: 120
description: 'who you are calling, as a person would say it: "Nopa", "Dr. Chen''s office", "Toyota of Berkeley service"'
goal:
type: string
minLength: 5
maxLength: 1500
description: 'what the call should achieve, in plain words: "Book a table for 4 tomorrow (Sat Oct 3) around 7pm under Khami."'
category:
type: string
enum:
- medical
- dental
- restaurant
- veterinary
- auto_service
- auto_sales
- home_service
- personal_care
- internet_new_service
- internet_existing_account
- flight_change
- general
description: the kind of call; decides what must be known first (see call4me_get_requirements)
details:
description: answers to the category's fields by key, e.g. {"reason":"annual physical","patient_status":"existing","availability":"weekday mornings next week"}. Profile fields (name, DOB, phone, insurance...) are filled from the saved profile only when the call is for the profile's owner; for anyone else (on_behalf_of is another name) pass all of their details here, since the owner's are never used.
type: object
propertyNames:
type: string
additionalProperties:
type: string
maxLength: 1000
on_behalf_of:
description: 'who the call is for, as the caller should say it (default: the profile''s full_name). The caller calls FOR this person; it never claims to be them.'
type: string
minLength: 1
maxLength: 80
facts:
description: anything else the caller may share beyond the category's fields, one per line
type: string
maxLength: 3000
flexibility:
description: 'what the caller may accept without asking: "any time 6:30-8pm", "a different day this week is fine", "up to $300". Anything outside this becomes a question to you.'
type: string
maxLength: 1500
timezone:
description: IANA time zone of the business, e.g. "America/Los_Angeles", so "tomorrow" is unambiguous
type: string
maxLength: 60
connect_when:
description: 'when to ring the user and patch them into the call without being asked, e.g. "as soon as a person picks up" (skip the hold) or "if they need to speak to me". Rings their own phone: details.phone when given, else the one in their profile; a call with neither is refused. They hand the call back to the caller by pressing * or hanging up.'
type: string
maxLength: 300
listen_in:
description: 'ring the user as soon as the business answers so they can listen in: nobody on the call hears them and the caller keeps working. They press 1 anytime to take over, or hang up to stop listening. Rings their own phone: details.phone when given, else the one in their profile; a call with neither is refused.'
type: boolean
max_minutes:
description: 'optional cap on the answered call, including phone menus. Defaults to 30 minutes, or less if the available balance cannot cover it. Only credits for that cap are held. A call still on hold when it reaches the cap keeps waiting: call4me holds 15 more minutes of credits at a time while the balance covers them, up to 4 hours. One still mid-conversation at the cap gets 2 more minutes at a time to finish instead of hanging up. Set a shorter cap to leave more credits free for other calls'
type: integer
minimum: 1
maximum: 240
voice:
description: caller voice (default marin); hear each at https://call4.me/voices
type: string
enum:
- marin
- cedar
- gleam
- meridian
- vesper
- willow
accent:
description: 'an accent or dialect the caller speaks with for this call only, e.g. "Austrian German" for a call in Vienna (default: the profile''s accent, else its voice''s own)'
type: string
maxLength: 40
caller_name:
description: 'a first name the caller introduces itself with, e.g. "Jordan", for this call only (default: the profile''s assistant_name, else none: just "<user>''s assistant"). Put the caller''s name and company here, never in the goal: the caller''s identity comes only from these fields.'
type: string
maxLength: 30
calling_as:
description: 'a company the caller calls from, e.g. "Acme": it introduces itself as "Jordan from Acme" (or "calling from Acme" without caller_name) instead of "<user>''s assistant", and callbacks to the number it called from answer as that company. Calling for several companies: pass the company on every call and give each one its own number (from), so callbacks reach the right identity.'
type: string
minLength: 1
maxLength: 80
callback_number:
description: 'the number the caller gives for call-backs and on voicemail, when the user wants callbacks to ring a phone of theirs (e.g. "(415) 555-0123"). Default: the number the call comes from, so a call4me number answers the callback and finishes the task. A callback to callback_number goes straight to that phone instead, and call4me never hears it. Phone numbers in details or facts are only for finding or verifying an account, never given as the callback.'
type: string
maxLength: 40
from:
description: 'which of the account''s numbers to call from (default: a call4me number in the callee''s country). May be one of the user''s own verified numbers (call4me_verify_number), for businesses in its country: they see it and call back the user directly'
type: string
maxLength: 40
call_at:
type: string
minLength: 10
maxLength: 40
description: 'when to dial: the business''s local time like "2026-10-05T09:15" together with timezone, or an ISO time with its offset like "2026-10-05T09:15:00-07:00". The time the user asked for. Up to 60 days ahead; dials within a minute of it.'
required:
- to
- business
- goal
- category
- call_at
additionalProperties: false
responses:
'200':
description: 'A retry under the same Idempotency-Key: the call the first request scheduled'
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
id:
type: string
status:
type: string
enum:
- pending
- dialing
- placed
- failed
- canceled
business:
type: string
number:
type: string
call_at:
type: string
call_id:
description: the call it became, once dialed
type:
- string
- 'null'
required:
- id
- status
- business
- number
- call_at
- call_id
additionalProperties: {}
'201':
description: The scheduled call
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
id:
type: string
status:
type: string
enum:
- pending
- dialing
- placed
- failed
- canceled
business:
type: string
number:
type: string
call_at:
type: string
call_id:
description: the call it became, once dialed
type:
- string
- 'null'
required:
- id
- status
- business
- number
- call_at
- call_id
additionalProperties: {}
'400':
description: Request failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'401':
description: Request failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'422':
description: Request failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
tags:
- Scheduled Calls
summary: Schedule call
x-summary-source: derived
/api/scheduled-calls/{scheduled_id}:
delete:
operationId: cancelScheduledCall
description: Cancel a scheduled call before it dials.
security:
- bearerAuth: []
parameters:
- name: scheduled_id
in: path
required: true
description: the id from POST /api/scheduled-calls ("sched_...")
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
responses:
'200':
description: The canceled schedule
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
id:
type: string
status:
type: string
enum:
- pending
- dialing
- placed
- failed
- canceled
business:
type: string
number:
type: string
call_at:
type: string
call_id:
description: the call it became, once dialed
type:
- string
- 'null'
required:
- id
- status
- business
- number
- call_at
- call_id
additionalProperties: {}
'400':
description: Request failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'401':
description: Request failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'404':
description: Request failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
tags:
- Scheduled Calls
summary: Cancel scheduled call
x-summary-source: derived
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: A call4me API key or OAuth access token for the site or MCP resource.