Calling

Overview

Calling is on when a person has a number to call from: their own mobile, verified once, or a Fondaro number. There is no separate switch-on step for the customer. The endpoints keep their historical /twilio/... paths.

The endpoints on this page use the dashboard's Clerk bearer token and resolve the organization from the request. Every member verifies and reads their own number. The country requirements flow (/twilio/regulatory/...) is limited to organization admins.

Endpoints

Method & path	Who	Purpose
`GET /twilio/phone-numbers/my-caller-id`	Any member	Your own verified number, or `{ "verified": false }`
`POST /twilio/phone-numbers/verify-caller-id`	Any member	Start verifying your own number: Fondaro calls it
`GET /twilio/phone-numbers/caller-id-verifications/current`	Any member	Your latest verification attempt
`GET /twilio/phone-numbers/caller-id-verifications/:attemptId`	Any member	One attempt, for polling
`DELETE /twilio/phone-numbers/caller-id-verifications/:attemptId`	Any member	Cancel a pending attempt
`GET /twilio/phone-numbers`	Any member	The numbers you may call from
`GET /twilio/pricing`	Any member	The price of a Fondaro number and per-minute calls
`POST /twilio/regulatory/bundles/:id/submit`	Admin	Send a country's details and documents for review

Verify your own number

curl -X POST https://api.fondaro.com/twilio/phone-numbers/verify-caller-id \
  -H "Authorization: Bearer <clerk session token>" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+34612345678" }'

{
  "id": "5b0c...",
  "phoneNumber": "+34612345678",
  "status": "pending",
  "validationCode": "482913",
  "expiresAt": "2026-09-26T10:24:03.000Z",
  "createdAt": "2026-09-26T10:14:03.000Z",
  "updatedAt": "2026-09-26T10:14:03.000Z"
}

Fondaro calls the number; the person types validationCode on their phone. Poll GET .../caller-id-verifications/:attemptId until status is succeeded, failed, expired or cancelled. failureReason is verification_failed, provider_unavailable or conflict.

What changed in 2026-09:

The phone account is created on demand. A member verifying before their organization's phone account exists no longer waits for an admin; the account is created for an entitled organization. A sandbox organization is still refused.
Verifying sets calling up. When the first own number in an organization succeeds and the organization owns no purchased number, Fondaro runs the setup that used to be an admin wizard: it buys the routing number the calls travel through and switches calling on. Nothing is bought when a purchased number already exists, so an organization that switched calling off is never switched back on. A failed setup leaves the verification in place and is retried on the next GET /twilio/token or GET /twilio/phone-numbers (at most once a minute).
A country Fondaro cannot call is refused with 422 and code: "CALLER_ID_COUNTRY_NOT_SUPPORTED" ("We can't call numbers in this country yet.").

Other refusals: 409 the number is already used in the organization, 403 calling is not available for the organization (for example a sandbox), 503 try again.

Why a person cannot call

GET /twilio/token answers 400 with a stable code when a person cannot call; GET /twilio/phone-numbers carries the same value as callingBlockedCode. The codes did not change; the message text did, and shipped apps show it as is:

`code`	`message`
`CALLING_DISABLED`	Calling is switched off for your agency.
`CALLING_PAUSED_BY_FONDARO`	Calling is paused while we check unusual activity. It comes back on its own.
`NO_ROUTING_NUMBER`	Calling isn't ready yet.
`NO_CALLER_ID`	Add your phone number to start calling.

Prices

curl "https://api.fondaro.com/twilio/pricing?numberType=local" \
  -H "Authorization: Bearer <clerk session token>"

{
  "numberRentalBasePrice": 1.0,
  "numberRentalCustomerPrice": 1.5,
  "numberRentalMarkupPct": 50,
  "perMinuteBasePrice": 0.013,
  "perMinuteCustomerPrice": 0.0195,
  "perMinuteMarkupPct": 50,
  "country": "ES",
  "currency": "EUR"
}

country (ISO 3166-1 alpha-2) and numberType (local by default) are optional. Changed: with no country, the price is for the organization's own country; the US is used only when the organization has none. Prices are in the organization's billing currency; numberRentalBasePrice and numberRentalCustomerPrice are null where numbers cannot be rented.

Send a country's details for review

curl -X POST https://api.fondaro.com/twilio/regulatory/bundles/<id>/submit \
  -H "Authorization: Bearer <clerk session token>"

Changed:

A request that was rejected can be fixed and sent again; before, only a draft could be sent. Anything else answers 400 "This has already been sent."
When the details do not pass the check before sending, the 400 names each field so a form can mark it inline:

{
  "statusCode": 400,
  "code": "DOCUMENTS_NOT_COMPLIANT",
  "message": "Some details need a fix: The business address is missing",
  "fields": [
    { "field": "business_address", "requirement": "Business address", "reason": "The business address is missing" }
  ]
}

message stays readable on its own for older clients. Each entry in fields has field, requirement and reason, any of which may be null.

Once a request is approved, Fondaro buys the number with the approved details and emails the admin; nobody has to come back to press anything (the calling:sync-regulatory-bundles job, every 30 minutes).