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 back to SiteCall; it stays reclaimable for `graceDays` (at most 15), then ages out and joins SiteCall's pool. SiteCall never releases it to the carrier.
`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_default_number`	`number`	The workspace's default number. SiteCall keeps one on its own: the first number in service, then the oldest one when the default leaves.
`set_caller_name`	`number`	The caller name (CNAM) recipients see, up to 15 characters.
`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", … } }

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.

Imported numbers

import_number records a number exactly as the carrier has it. acquire_number for a number the workspace already holds points it at SiteCall: its calls on SiteCall's voice engine, where routing plans decide who rings, and its texts on the workspace's own messaging profile (SiteCall receives them as message.* events; you send through /v1/messages). Opt-outs move with it. Re-applying it changes nothing.

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