Create an outbound call

POST

calls

curl --request POST \
  --url https://api.sempera.org/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "agent_id": "<string>",
  "to": "<string>",
  "consent_basis": "<string>",
  "phone_number": "<string>"
}
'

import requests

url = "https://api.sempera.org/v1/calls"

payload = {
    "agent_id": "<string>",
    "to": "<string>",
    "consent_basis": "<string>",
    "phone_number": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: '<string>',
    to: '<string>',
    consent_basis: '<string>',
    phone_number: '<string>'
  })
};

fetch('https://api.sempera.org/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "object": "call",
  "agent_id": "<string>",
  "channel": "web_voice",
  "status": "<string>",
  "started_at": "<unknown>",
  "ended_at": "<unknown>",
  "duration_s": "<unknown>",
  "outcome": "<unknown>",
  "language": "<unknown>",
  "agent_version_id": "<unknown>",
  "caller": "<unknown>",
  "summary": "<unknown>",
  "turns": "<array>",
  "recording": "<unknown>",
  "provider": "<unknown>",
  "call_id": "<unknown>",
  "runtime_identity": {
    "schema": "<unknown>",
    "traffic": {},
    "legs": {},
    "fallbacks": {},
    "worker": {},
    "latency": {},
    "verified": true
  },
  "mode": "agent"
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A workspace API key, sent as Authorization: Bearer sempera_sk_... Each operation names the one scope it needs. Scopes, key kinds and roles are in the Authentication guide.

Headers

Idempotency-Key

string

required

Replays the stored answer for a retry of the same request; 409 for a different request under the same key.

Maximum string length: 255

Body

application/json

Option 1
Option 2

agent_id

string

required

The line this call goes out on: its number, consent, do-not-contact list, calling hours, caps and billing. With mode prompt it is not the conversation.

string

required

Destination phone number, E.164 or national digits.

Sentence recording why this person opted in.

mode

enum<string>

default:agent

agent (default): the published agent runs, and task supplements its rules. prompt: the conversation is only the prompt (task or settings.prompt), which is required. The named agent_id remains the line. agent_version, production and environment are refused. prompt_only is not a field; sending it is refused and skips nothing.

Available options:

agent,

prompt

phone_number

string

Alias for to. Send only one name for an option.

from

string

Optional owned caller id.

from_number

string

Alias for from.

dialing_pool_id

string<uuid>

Owned number pool for local caller ID. Mutually exclusive with from. Requires workspace entitlement and verified, unexpired A attestation evidence. Exhausted pools refuse without a default-line fallback.

name

string

Maximum string length: 80

agent_version

Installed published agent version id or number. A different version is refused, never substituted. Refused when mode is prompt.

agent_version_id

Alias for agent_version. Refused when mode is prompt.

production

boolean

Resolve the version pinned to the production environment. Refused with AGENT_ENV_UNPINNED when none is pinned. Refused when mode is prompt.

use_production

boolean

Alias for production. Refused when mode is prompt.

environment

enum<string>

Environment to resolve; production only. Refused when mode is prompt.

Available options:

production

message

string

Opening message after the required automated-call disclosure.

opening

string

Alias for message.

first_sentence

string

Alias for message; the automated-call disclosure is always retained.

metadata

object

Existing opening-template context, not a per-call webhook payload.

Show child attributes

timezone

string

default:America/Toronto

window

string

default:09:00-18:00

Recipient calling hours, HH:MM-HH:MM.

precall_dtmf

string

Keys pressed after connection, before the employee speaks.

precall_dtmf_sequence

string

Alias for precall_dtmf.

voicemail

object

Alias for settings.voicemail; unsupported actions are refused.

webhook

string<uri>

URL of an enabled signed endpoint already registered in this workspace.

webhook_events

any[]

Required array length: 1 element

voice

string

Alias for settings.voice_id.

language

string

Alias for settings.language.

task

string

Alias for settings.prompt. With mode prompt this is the whole conversation and is required. Otherwise it supplements the agent's published rules.

Maximum string length: 2000

request_data

object

Alias for settings.call_data. Named facts available throughout this call, separate from opening-template metadata.

Show child attributes

max_duration

integer

Alias for settings.max_call_minutes; platform safety ceilings still apply.

Required range: 2 <= x <= 60

keywords

string[]

Minimum array length: 1

background_track

enum<string>

Available options:

none,

off,

office,

coffee_shop,

restaurant

block_interruptions

boolean

True blocks interruptions; false allows them.

country

string

ISO country code for a to written without +; one of the countries the App's Send a call page lists.

settings

object

This call's own settings, checked as the App's Send a call page checks them: voice_id, language, max_call_minutes, interruptibility, acknowledgements, background_noise, voicemail, prompt, keywords, call_data, noise_cancellation and interruption_threshold. Unknown keys are refused.

Response

Created

string

required

object

any

required

agent_id

string

required

channel

enum<string>

required

Available options:

web_voice,

web_chat,

simulator,

phone,

test,

unknown

status

string

started_at

any

ended_at

any

duration_s

any

outcome

any

language

any

agent_version_id

any

caller

any

summary

any

turns

array | null

recording

any

provider

any

call_id

any

runtime_identity

object | null

What heard, thought and spoke on this session, as a workspace member reads it: legs (stt, llm, tts: each with engine, model, machine as a category, and for tts ended_on), fallbacks (whether a leg handed over), worker (runtime origin or hosted, transport), latency timings, traffic (class: customer, demo, test or unrecorded) and verified, false when the stored block no longer matches its own integrity checksum. Engines and models carry Sempera's sealed names (engine_...), never a supplier's. null for a session recorded before the block existed.

Show child attributes

mode

enum<string>

prompt when the conversation was only the prompt. The line agent is agent_id either way.

Available options:

agent,

prompt

⌘I

Create an outbound call

curl --request POST \
  --url https://api.sempera.org/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "agent_id": "<string>",
  "to": "<string>",
  "consent_basis": "<string>",
  "phone_number": "<string>"
}
'

import requests

url = "https://api.sempera.org/v1/calls"

payload = {
    "agent_id": "<string>",
    "to": "<string>",
    "consent_basis": "<string>",
    "phone_number": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: '<string>',
    to: '<string>',
    consent_basis: '<string>',
    phone_number: '<string>'
  })
};

fetch('https://api.sempera.org/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "object": "call",
  "agent_id": "<string>",
  "channel": "web_voice",
  "status": "<string>",
  "started_at": "<unknown>",
  "ended_at": "<unknown>",
  "duration_s": "<unknown>",
  "outcome": "<unknown>",
  "language": "<unknown>",
  "agent_version_id": "<unknown>",
  "caller": "<unknown>",
  "summary": "<unknown>",
  "turns": "<array>",
  "recording": "<unknown>",
  "provider": "<unknown>",
  "call_id": "<unknown>",
  "runtime_identity": {
    "schema": "<unknown>",
    "traffic": {},
    "legs": {},
    "fallbacks": {},
    "worker": {},
    "latency": {},
    "verified": true
  },
  "mode": "agent"
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "code": "AGENT_ENV_UNPINNED",
    "message": "<string>",
    "request_id": "<string>",
    "field": "<string>",
    "scope": "<string>",
    "reason": "<string>"
  }
}