Skip to main content
The Caller is who is paying, recognized by the phone number they are calling from. identify answers one question: who is this person. It never answers what they can pay with. Which business they reached is a separate identity, see Merchant Identity.

​
Recognize a caller

Pass the caller’s number in the body as caller_phone, in E.164:
Response (recognized caller)
known says whether Ringup has seen this person before. consumer carries the record when it has, and is null when it has not. Use first_name to greet the caller and skip questions you already have answers to. email serves the merchant’s receipts and follow-ups; the agent never reads it aloud.

​
An unknown caller is not an error

A first-time caller comes back as 200 with known: false and consumer: null. Most callers start this way; it is not a failure. Branch on known, greet a stranger as a stranger, and take the order the same way. The caller becomes recognized the first time they pay through a texted link.
Response (first-time caller)

​
Why cards do not come back here

Whether a saved card can be charged depends on which processor the merchant runs, and identify has no merchant: it takes a phone number and nothing else. Any card list here would be right for some merchants and wrong for others, and the wrong ones surface only at the charge, after the caller has already agreed to a card. So cards come from create_checkout, which knows the merchant and returns exactly the cards chargeable there. identify is the surface that grows with the person: name and email today, preferences and consent history later.

​
Recognize at the start of the call

The caller’s phone number arrives the instant the call connects, before the caller has said a word, so call identify at the start of the call, not at the payment moment. A returning caller’s name is then on your screen from the first line: greet them by name, and never ask “what name should I put this under?” Calling early also hides the lookup in the greeting, where a pause is less noticeable than at the payment moment. Some integrations wire recognition for you, with no tool call in your agent. On the others, invoke identify yourself at the greeting.

​
Why the number comes from the call, not the model

Fill caller_phone from the platform’s caller-ID variable, the value the telephony layer resolved when the call connected. A number the model composes can be mistyped, misheard, or prompt-injected by a hostile caller, and the number is the whole identity: whoever owns it is offered that person’s saved cards.
Dashboard and web test calls carry no real caller ID, so the platform’s caller-ID template resolves to nothing. For those, pin a test caller explicitly. Real inbound phone calls resolve the caller natively.

​
Next steps

Merchant Identity

The other half of every call: which business the caller reached.

Checkout Session

The object every payment turns on, and where the caller’s chargeable cards come from.