Speko Docs
Build

Call from your own number

Verify a mobile or office number you already have and use it as the caller ID on outbound calls.

A verified caller ID is a phone number you already have, such as your mobile or your office line. You prove you control it by entering a code sent to it. After that, your outbound calls can show that number as the caller ID.

The number stays with your current phone company. Speko does not receive its calls or texts. When someone calls the number back, your own phone rings.

Requirements and limits

NumbersUS and Canadian local numbers. Toll-free, premium-rate and non-geographic numbers cannot be verified.
Who can verifyA signed-in workspace owner or admin. Other members and API keys can read the list.
PaymentThe workspace must have topped up at least once, any amount. Free credit does not count.
How manyUp to 5 per workspace.
How longOne year from the day the code was accepted. Then verify the number again.
CodesA code works for 10 minutes and allows 5 tries. A workspace can request 5 codes in 24 hours, and one number can be sent 3.
UseOutbound calls only. A verified caller ID cannot receive calls, send or receive texts, or be assigned to an agent.

Verifying a number is free. A call placed from it is billed like any other outbound call.

A number you bought from Speko or imported from your own carrier is already yours to call from. Pass it as from without verifying it.

Verify a number

You need the phone in hand. The code arrives by text, or by an automated voice call for a landline.

In the dashboard

  1. Open Phone Numbers and find Verified caller IDs.
  2. Select Add caller ID and enter your number.
  3. Choose Text or Voice call, then select Send code.
  4. Enter the code and select Verify.

If you close the dialog first, the number stays in the list as Pending. Select Enter code to finish. Send new code sends a fresh code.

With the API

Starting, confirming and releasing need a signed-in owner or admin. An API key gets 403 on these calls. The examples below use the Speko CLI, which signs in as you with speko-cli login.

Start the verification with POST /v1/phone-numbers/verified-caller-ids. method is sms (the default) or call:

speko-cli telephony start-verified-caller-id \
  --data '{ "phoneNumber": "+14155550123", "method": "sms" }'
{
  "verifiedCallerId": {
    "id": "6b0f3a52-7c1e-4d55-9a45-2f6f1f1f0a01",
    "phoneNumber": "+14155550123",
    "status": "pending",
    "method": "sms",
    "verifiedAt": null,
    "expiresAt": null,
    "codeExpiresAt": "2026-11-11T12:10:00.000Z",
    "createdAt": "2026-11-11T12:00:00.000Z"
  },
  "codeSent": true
}

Then send the code with POST /v1/phone-numbers/verified-caller-ids/{id}/confirm:

speko-cli telephony confirm-verified-caller-id 6b0f3a52-7c1e-4d55-9a45-2f6f1f1f0a01 \
  --data '{ "code": "482913" }'

The response has status: "verified" and an expiresAt one year ahead.

Any member or API key can list the workspace's verified caller IDs:

curl https://api.speko.dev/v1/phone-numbers/verified-caller-ids \
  -H "Authorization: Bearer $SPEKO_API_KEY"
statusMeaning
pendingA code was sent. Confirm it before codeExpiresAt.
verifiedReady to use as from until expiresAt.
expiredThe year ran out. Start again.
failedThe code ran out, was wrong too many times, or could not be sent. Start again. A removal that did not finish also shows as failed; remove it again to finish.

If a start or confirm is refused, the response code says why. The common ones:

CodeWhat to do
VERIFIED_CALLER_ID_PAYMENT_REQUIREDTop up once, any amount. The response carries a topUpUrl when one is available.
VERIFIED_CALLER_ID_NUMBER_UNSUPPORTEDUse a US or Canadian local number.
VERIFIED_CALLER_ID_NUMBER_IN_USEThe number is already a Speko phone number. On a start, if it is one of yours, pass it as from directly. On a confirm, it became a Speko number after the code window closed; remove this verified caller ID.
VERIFIED_CALLER_ID_CLAIMEDAnother workspace is using this number.
VERIFIED_CALLER_ID_LIMIT_REACHEDRelease one of your 5 first.
VERIFIED_CALLER_ID_REQUEST_REFUSEDCheck the number, or try the other method.
VERIFIED_CALLER_ID_CODE_INVALIDEnter the code again. The message says how many tries are left.
VERIFIED_CALLER_ID_CODE_EXPIRED, VERIFIED_CALLER_ID_TOO_MANY_ATTEMPTSStart again for a new code.
VERIFIED_CALLER_ID_SETUP_FAILEDThe code was accepted. Confirm again with the same code.

Every code is listed in Error codes.

With MCP

On mcp.speko.ai, signed in as an owner or admin, ask your assistant to verify your number. It uses these tools:

ToolWhat it does
phone_numbers.verified_caller_ids.listLists verified caller IDs and their status.
phone_numbers.verified_caller_ids.startSends a code to your number by text or voice call.
phone_numbers.verified_caller_ids.confirmSubmits the code you read back.
phone_numbers.verified_caller_ids.releaseStops using a number as a caller ID.

The assistant asks you for the code. It cannot read it for you.

Place a call

Pass the verified number as from:

const call = await speko.voice.dial({
  to: '+12015551234',
  from: '+14155550123',
  agentId: 'agent_123',
});

A verified caller ID is used only when from names it. Speko never picks it by default.

Call lists accept it as from too. If the verification expires or is released while a list is running, the list pauses.

Speko does not swap in another number when a verified caller ID cannot be used:

CodeMeaning
VERIFIED_CALLER_ID_NOT_ACTIVEThe number was released, or its verification was never finished.
VERIFIED_CALLER_ID_EXPIREDThe year ran out. Verify the number again.
VERIFIED_CALLER_ID_UNSUPPORTEDThis kind of call cannot present a verified caller ID. Demo calls, Pipecat calls and calls on your own SIP trunk cannot.

Transfers

A call placed from a verified caller ID has two transfer rules:

  • Blind transfers are refused with TRANSFER_BLIND_VERIFIED_CALLER_ID. Use a warm transfer.
  • Warm transfers call out from one of the workspace's phone numbers, not from the verified number. Leave from out, or pass one of your Speko numbers. Passing the verified number is refused with TRANSFER_FROM_VERIFIED_CALLER_ID.

The verification covers calls your workspace places. It does not cover calls it forwards to someone else.

Expiry and removal

A verification lasts one year. The dashboard shows the expiry date and the API returns it as expiresAt. After that date the number reads as expired, and calls from it are refused until you verify it again with a new code.

To stop using a number, select Remove in the dashboard, call DELETE /v1/phone-numbers/verified-caller-ids/{id}, or use phone_numbers.verified_caller_ids.release. Calls that name it as from are refused from then on. If the removal does not finish, the response is VERIFIED_CALLER_ID_RELEASE_FAILED and the number lists as failed; calls already refuse it, and removing it again finishes. You can verify it again at any time.

On this page