> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringup.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Recognize a caller

> Look a caller up by phone number. Returns who they are, never what they can pay with: cards depend on a merchant this endpoint never sees.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/identify
openapi: 3.1.0
info:
  title: Ringup API
  version: v1
  description: >-
    Take a card payment on a phone call. Every endpoint is authenticated with a
    Bearer API key; the key prefix (`rk_test_` / `rk_live_`) selects the
    environment.
servers:
  - url: https://api.ringup.dev
security: []
paths:
  /v1/identify:
    post:
      summary: Recognize a caller
      description: >-
        Look a caller up by phone number. Returns who they are, never what they
        can pay with: cards depend on a merchant this endpoint never sees.
      operationId: identify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyRequest'
            example:
              caller_phone: '+14155550142'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifyResponse'
              example:
                known: true
                consumer:
                  id: con_c0325fbd
                  first_name: Dana
                  last_name: Whitfield
                  email: dana@example.com
        '400':
          description: |-
            `invalid_json` The request body is not valid JSON.

            `missing_required_fields` A required parameter is missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
              examples:
                invalid_json:
                  summary: The request body is not valid JSON.
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_json
                      audience: developer
                      message: The request body is not valid JSON.
                      advice_code: do_not_try_again
                      agent_message: null
                      display_message: null
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#invalid_json
                      request_id: req_8f3c1d2ab4e9
                missing_required_fields:
                  summary: A required parameter is missing.
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_required_fields
                      audience: developer
                      message: A required parameter is missing.
                      param: caller_phone
                      advice_code: do_not_try_again
                      agent_message: null
                      display_message: null
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#missing_required_fields
                      request_id: req_8f3c1d2ab4e9
        '401':
          description: >-
            `invalid_key` The API key is missing, malformed, revoked, or does
            not match the mode of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
              examples:
                invalid_key:
                  summary: >-
                    The API key is missing, malformed, revoked, or does not
                    match the mode of the resource.
                  value:
                    error:
                      type: authentication_error
                      code: invalid_key
                      audience: developer
                      message: >-
                        The API key is missing, malformed, revoked, or does not
                        match the mode of the resource.
                      advice_code: do_not_try_again
                      agent_message: null
                      display_message: null
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#invalid_key
                      request_id: req_8f3c1d2ab4e9
      security:
        - bearerAuth: []
components:
  schemas:
    IdentifyRequest:
      additionalProperties: false
      description: >-
        The wire contracts.


        One name per concept. One card shape everywhere. Every response echoes
        your own identifiers, so reconciling a payment never needs a second
        call.
      properties:
        caller_phone:
          description: >-
            E.164. The body is the ONLY place this lives: a header carried no
            cryptographic guarantee (it is unsigned, so it is safer only against
            the model, not against a caller), and one value in two places is an
            ambiguity every consumer has to reason about.
          type: string
      required:
        - caller_phone
      type: object
    IdentifyResponse:
      additionalProperties: false
      properties:
        consumer:
          anyOf:
            - $ref: '#/components/schemas/IdentifiedConsumer'
            - type: 'null'
        known:
          type: boolean
      type: object
    ApiErrorBody:
      additionalProperties: false
      description: >-
        THE error object. Identical on every endpoint: provisioning, identify,
        checkout, cards, charge. A failed charge (which arrives as a 200 with
        `status: "failed"`) carries the SAME fields under `failure`, so a
        developer writes one parser and it works everywhere.
      properties:
        error:
          additionalProperties: false
          properties:
            advice_code:
              $ref: '#/components/schemas/AdviceCode'
              description: try_again_later | confirm_card_data | do_not_try_again
            agent_action:
              anyOf:
                - $ref: '#/components/schemas/AgentAction'
                - type: 'null'
              description: 'Null on every `developer`-audience error: see agent_message.'
            agent_message:
              description: >-
                Speak verbatim WHEN NON-NULL. Null on every `developer`-audience
                error.
              type:
                - string
                - 'null'
            audience:
              $ref: '#/components/schemas/Audience'
              description: >-
                Who this error is for. Drives whether there is anything to speak
                at all.
            charge:
              description: Present when the error concerns a specific charge.
              type: string
            code:
              $ref: '#/components/schemas/ErrorCode'
            decline_code:
              type: string
            display_message:
              description: >-
                The same fact written for a screen. Null on `developer`-audience
                errors.
              type:
                - string
                - 'null'
            doc_url:
              type: string
            message:
              type: string
            param:
              type: string
            processor_code:
              type: string
            request_id:
              type: string
            request_log_url:
              description: >-
                Deep link to this request in the dashboard. Present once the
                dashboard log view exists.
              type: string
            type:
              $ref: '#/components/schemas/ErrorType'
          type: object
      type: object
    IdentifiedConsumer:
      additionalProperties: false
      properties:
        email:
          description: >-
            For the merchant's own workflows (receipts, follow-ups). Not for the
            agent to say aloud.
          type:
            - string
            - 'null'
        first_name:
          description: Stored as parts because the pay page collects them as parts.
          type:
            - string
            - 'null'
        id:
          type: string
        last_name:
          type:
            - string
            - 'null'
      type: object
    AdviceCode:
      description: >-
        `advice_code` is our guidance to the developer on what to do with this
        decline programmatically. It is distinct from `agent_action`, which
        drives the conversation. A decline can be "do not retry this card"
        (advice) while still being "offer a different card" (agent action).
      enum:
        - try_again_later
        - do_not_try_again
        - confirm_card_data
      type: string
    AgentAction:
      description: >-
        What the agent should DO next. Keeps conversational branching
        deterministic too.
      enum:
        - retry_card
        - offer_different_card
        - send_link
        - end_call
        - escalate
      type: string
    Audience:
      description: >-
        Who an error is for.


        `caller` errors are things the person on the phone is living through, so
        they carry copy your agent can speak. `developer` errors are your
        integration's own bugs, and carry NO speakable copy at all: the fields
        are null rather than a neutral filler, because a filler sentence invites
        an agent to raise payment when nothing about payment has failed.
      enum:
        - developer
        - caller
      type: string
    ErrorCode:
      enum:
        - invalid_json
        - missing_required_fields
        - invalid_value
        - invalid_key
        - vendor_not_provisioned
        - merchant_not_found
        - merchant_not_connected
        - invalid_processor
        - invalid_credentials
        - invalid_payment_policy
        - invalid_payment_policy_amount_cents
        - session_not_found
        - session_expired
        - session_create_failed
        - session_missing_consumer
        - missing_checkout_session_id
        - order_lookup_failed
        - order_lookup_unsupported
        - instrument_not_found
        - instrument_not_authorized
        - missing_instrument_fields
        - processor_mismatch
        - needs_enrollment
        - charge_details_mismatch
        - card_save_failed
        - card_declined
        - processor_unavailable
        - merchant_credentials_invalid
        - invalid_vault
        - key_not_found
        - invalid_environment
        - invalid_url
        - invalid_events
        - invalid_ttl
        - invalid_state_key
        - not_found
        - not_configured
        - rate_limit
        - internal_error
      type: string
    ErrorType:
      enum:
        - invalid_request_error
        - authentication_error
        - permission_error
        - card_error
        - processor_error
        - idempotency_error
        - rate_limit_error
        - api_error
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rk_live_…

````