Numbers

Numbers for every workspace you manage.

SiteCall is the system of record for phone numbers. Your application orders, moves and releases them for its workspaces with one command endpoint, POST /api/v1/applications/telephony, and hears about every change as number.updated.

Authentication

An application key with scope numbers:*. (Applications registered before keys existed may still send their bearer secret with an x-sitecall-application header.) Workspaces are named inside each command by your own id, so no workspace header is sent.

Commands

One JSON command per request, named by type. The answer is the result its type names.

Command	Answers	What it does
`ensure_workspace`	`workspace`	Create or find the workspace for your own id (`externalWorkspaceId`, `name`).
`search_numbers`	`search`	Available numbers by `areaCode` (`country` default US, `limit` 1–50, default 10).
`acquire_number`	`number`	Order one exact number for a workspace. Carries its own `idempotencyKey`.
`release_number`	`number`	Release a number; it stays reclaimable for `graceDays` (0–90, default 30).
`reclaim_number`	`number`	Take a released number back while its grace lasts.
`transfer_number`	`number`	Move a number between two of your workspaces. Carries its own `idempotencyKey`.
`list_numbers`	`numbers`	Every number of a workspace.
`get_number`	`number`	One number by E.164.
`set_caller_name`	`number`	The caller name (CNAM) recipients see, up to 15 characters.
`set_emergency_address`	`number`	The number's registered E911 address.
`set_voice_lane`	`number`	Move the number's calls to SiteCall's voice engine (`sitecall`) or back.
`set_messaging_lane`	`number`	Move the number's texting to SiteCall's messaging (`sitecall`) or back.
`submit_business_identity`	`business_identity`	The company facts texting registration needs.
`get_business_registration`	`business_registration`	Where texting registration stands.

POST /api/v1/applications/telephony

curl https://sitecall.ai/api/v1/applications/telephony \
  -H "authorization: Bearer $SITECALL_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "type": "acquire_number",
        "externalWorkspaceId": "acme-42",
        "phoneNumber": "+15125550123",
        "idempotencyKey": "acme-42-line-1",
        "externalNumberId": "line-1" }'

{ "type": "number",
  "number": { "sitecallNumberId": "…", "phoneNumber": "+15125550123", "status": "active",
              "externalWorkspaceId": "acme-42", "voiceLane": "sitecall", … } }

with @sitecall/cli

const [first] = await sitecall.numbers.search({ externalWorkspaceId: "acme-42", areaCode: "512" });
const number = await sitecall.numbers.acquire({
  externalWorkspaceId: "acme-42",
  phoneNumber: first.phoneNumber,
  idempotencyKey: "acme-42-line-1",
});
await sitecall.numbers.setCallerName({
  externalWorkspaceId: "acme-42",
  phoneNumber: number.phoneNumber,
  displayName: "ACME ROOFING",
});

Retries and errors

Refusals on this endpoint are { "error": "<message>", "code": "<code>" }:

Code	Meaning
`unauthorized`	The key or secret is not valid for this application.
`invalid_command`	The command does not match its schema.
`workspace_not_found`	No workspace of yours has that id; ensure it first.
`number_unavailable`	The carrier no longer offers it; pick another.
`number_not_owned`	The number is not in that workspace.
`carrier_failed`	The carrier refused the change.
`carrier_ambiguous`	An earlier change's outcome is still being confirmed: retry the same command after a minute.
`unavailable`	Try the same command again.

acquire_number and transfer_number name one change by their idempotencyKey: after a lost answer, send the same command again and SiteCall answers that change's number, never a second order.
A refusal with delivered: true is not a failure: that key's order completed earlier and the number has since left the workspace. Do not refund it.
The typed client never retries this endpoint on its own: a person or your own job decides.

Voice lanes

set_voice_lane with sitecall puts a number's calls on SiteCall's voice engine, where routing plans decide who rings. Texting stays on the number's messaging lane. The command is journaled and replay-safe; rolling back is the same command with the previous lane.

set_messaging_lane with sitecall moves the number's texting onto its SiteCall workspace's own messaging profile: SiteCall receives its texts and sends them as message.* events, and you send through /v1/messages. Opt-outs move with it. Calls stay on the voice lane. Re-applying it changes nothing; rolling back is the same command with the previous lane.

SiteCall's own customers provision numbers themselves through provisioning, with their owner or admin login and an explicit quote they approve.