Skip to navigation

Place a rep call

Rings to from a pool number (or from) with the rep in the call and the AI listening. The same rules as an expert’s calls: a US number, never one on your do-not-call list, inside calling hours where the person is, with credits. Hand join to the rep’s browser. Send an Idempotency-Key header so a retry never rings twice.

Needs the calls:write scope. A key without it gets 403 insufficient_scope. Routes not in this reference cannot be called with a key at all (403 not_available_to_api_keys).

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

Idempotency-KeystringOptional

Any unique string; a retry with the same key returns the first result instead of acting twice.

Request

This endpoint expects an object.
repstring or objectRequired

The rep: their externalId, or { id, name, mobileNumber? } to create them (or update a changed name or mobile) with the call, so there is no separate step.

tostringRequired

Who to call: E.164 or a US number in any common format.

fromstringOptional

A phone number id or E.164 of yours, or pool:<id>. Default: one of your numbers for sales calls (Rydhm → Sales calls → Numbers), taking turns and under each number’s daily limit.

contextmap from strings to anyOptional

The context packet, up to 16 KB of JSON: prospect, company, goal, notes, playbook (your sales playbook for this call, as text), seller.company (the company your rep calls for; default your workspace’s name) and language are read by name; any other key is read as notes. The suggestions and the AI voicemail come from it; the summary reads only who the call is with and what it is for (prospect name, title and company, company.name, goal, seller.company).

externalRefstringOptional<=200 characters
Your id for the call, echoed in every event and webhook.
suggestionsbooleanOptional
Suggest the next question after each prospect turn. Default false.
recordbooleanOptional

Record the call. Whether it is recorded follows your workspace’s recording policy and the prospect’s number; the response’s recording says (pending, or skipped with the reason). Default false.

callingHoursExceptionobjectOptional

Call outside 8 am–9 pm the prospect’s time. The federal hours cover telephone solicitations to residential subscribers; a call the person asked for (prospect_asked), one to an existing customer (existing_customer) or to a business line (business_line) is outside them. Skips the calling-hours check only: do-not-call, credits and every other rule still apply. Used, kept on the call (callingHoursException) and audit-logged only when the call is outside those hours. 403 hours_exception_not_allowed when the workspace turned exceptions off.

waitForRepbooleanOptional

Dial the prospect only once the rep’s softphone has joined the call (20 s at most; nobody by then: the call ends canceled, endReason rep_not_joined, and their phone never rings). Default false: dial at once.

Response

OK
idstring
A UUID.
statusenum
endReasonstring or null
recordingobject

The call’s recording. Whether a call is recorded follows the workspace’s repCallRecordings policy and the prospect’s number (by area code: a state where everyone must agree is skipped under one_party_states, or announced under all_with_notice). MP3, stereo: left the rep (and Rydhm’s own voice), right the prospect.

joinobject

For the rep’s browser: join the call’s room with it and publish the microphone (15 minutes to join).

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
503
Service Unavailable Error