Verify a caller id for outbound calls

Voicecaller ID verification

Three REST requests register a number you own elsewhere as a verified caller ID. You submit the code you heard, and redial the verification call if you missed it.

identity

The claim

You send three requests. POST /api/relay/rest/verified_caller_ids carries the number and a display name; the vendored REST spec titles it “Create verified caller ID”. PUT /api/relay/rest/verified_caller_ids/{id}/verification carries verification_code, titled “Validate verification code”. POST to that same path is “Redial verification call”. The SDK wraps the three as create, submit_verification and redial_verification on client.verified_callers.

Why it holds

The verifier checks the three requests against that spec. It marks number as the one required field on create and verification_code as required on the PUT. The spec’s response schema carries id, number, name, verified, verified_at and status.

How it works

client = RestClient()

def start(number, name):
    return client.verified_callers.create(number=number, name=name)

def confirm(caller_id, code):
    return client.verified_callers.submit_verification(caller_id, verification_code=code)

def resend(caller_id):
    return client.verified_callers.redial_verification(caller_id)

What the platform receives, in order:

POST /api/relay/rest/verified_caller_ids
{"number": "+15557654321", "name": "Shop mobile"}

PUT  /api/relay/rest/verified_caller_ids/<id>/verification
{"verification_code": "482913"}

POST /api/relay/rest/verified_caller_ids/<id>/verification

The id in the second and third paths is the id the first response returned, per the spec’s response schema. verified and status in that schema are how you read the outcome.

Limitations

The verifier proves the three requests. Whether the phone rings, what the code is, and when verified flips are the platform’s side of a live run.

What to change first

Remove name=name from start and run the verifier. The exact-body assertion fails, though the spec would still accept the request: name is optional and number is the only required field.

Where this sits

Place an outbound call

python/app.py

"""Verify a caller ID for outbound calls.

A number you own elsewhere becomes a permitted outbound caller ID in three
REST calls. `create` registers the number and starts a verification call to
it; the person who answers hears a code. `submit_verification` sends that code
back. `redial_verification` places the call again if the code was missed.

Written against signalwire-sdk 3.0.1 (RestClient.verified_callers).
"""
from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# RestClient() reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN /
# SIGNALWIRE_SPACE from the environment (signalwire/rest/client.py).
client = RestClient()


def start(number, name):
    """Register the number; the platform calls it and reads out a code."""
    return client.verified_callers.create(number=number, name=name)


def confirm(caller_id, code):
    """Send back the code the person who answered heard."""
    return client.verified_callers.submit_verification(caller_id,
                                                       verification_code=code)


def resend(caller_id):
    """Place the verification call again."""
    return client.verified_callers.redial_verification(caller_id)


if __name__ == "__main__":
    import sys

    if len(sys.argv) < 2:
        raise SystemExit("usage: python app.py start +1XXXXXXXXXX 'Shop mobile'\n"
                         "       python app.py confirm <id> <code>\n"
                         "       python app.py resend <id>")
    verb, args = sys.argv[1], sys.argv[2:]
    print({"start": start, "confirm": confirm, "resend": resend}[verb](*args))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: your project id, API token and space
python app.py start +1XXXXXXXXXX "Shop mobile"     # the phone rings and reads a code
python app.py confirm <id> <code>
python app.py resend <id>                          # if nobody caught the code

Use a number you can answer. There is no server to expose; each command speaks to the REST API and exits.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier swaps the SDK’s HTTP layer for a recorder, calls your three helpers, and asserts the following.

start makes one POST to the documented path with exactly number and name
confirm makes one PUT to the id’s verification path with exactly verification_code
resend makes one POST to that verification path with no body
every body field is documented and every required field is present, per the vendored spec
the spec’s required list for create is exactly number

Report an issue