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

# Record a conversion

> Records a conversion from your own backend.

Use this for anything the browser pixel cannot observe: a hosted checkout that does not run your page scripts, a payment captured minutes after the visitor closed the tab, a phone sale, or a deal marked won in your CRM.

The conversion is matched to a contact by the strongest identifier you send — click id, visitor id, external id, phone, then email. If none match a known contact the call is rejected rather than recorded against nobody, because an unattached conversion cannot be attributed and a guessed one would credit the wrong person.

Idempotent on `txn`. Send the same one on a retry.



## OpenAPI

````yaml /openapi.json post /v1/conversion
openapi: 3.1.0
info:
  title: Verbose API
  version: 1.0.0
  description: >-
    Programmatic access to the Verbose platform — contacts, lists, segments, SMS
    & voice campaigns, AI agents, messages and calls, numbers, registration,
    flows, analytics, and webhooks. All endpoints live under `/v1` and
    authenticate with a workspace API key.
servers:
  - url: https://api.verbose.cx
    description: Production
security:
  - bearerAuth: []
tags:
  - name: General
    description: Key + workspace.
  - name: Contacts
    description: The people you reach.
  - name: Lists
    description: Static groups of contacts.
  - name: Segments
    description: Live, rule-based audiences.
  - name: Suppression
    description: Numbers to keep off your sends.
  - name: Campaigns
    description: SMS & voice campaigns.
  - name: Messages
    description: One-off SMS.
  - name: Calls
    description: One-off outbound voice calls.
  - name: Agents
    description: AI SMS & voice agents.
  - name: Conversations
    description: Inbox threads.
  - name: Numbers
    description: Phone numbers & pools.
  - name: Offers
    description: Destinations + conversion attribution.
  - name: Analytics
    description: Metrics & custom reports.
  - name: 10DLC
    description: US A2P brand + campaign registration.
  - name: Shortcode
    description: Short-code requests.
  - name: Flows
    description: Multi-step automations.
  - name: Webhooks
    description: Event subscriptions.
  - name: Conversions
    description: >-
      Server-side conversions. Browser activity is tracked by the pixel script;
      this is for the events your own systems confirm.
paths:
  /v1/conversion:
    post:
      tags:
        - Conversions
      summary: Record a conversion
      description: >-
        Records a conversion from your own backend.


        Use this for anything the browser pixel cannot observe: a hosted
        checkout that does not run your page scripts, a payment captured minutes
        after the visitor closed the tab, a phone sale, or a deal marked won in
        your CRM.


        The conversion is matched to a contact by the strongest identifier you
        send — click id, visitor id, external id, phone, then email. If none
        match a known contact the call is rejected rather than recorded against
        nobody, because an unattached conversion cannot be attributed and a
        guessed one would credit the wrong person.


        Idempotent on `txn`. Send the same one on a retry.
      operationId: recordConversion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionRequest'
      responses:
        '200':
          description: Recorded, or already recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionResponse'
        '401':
          description: Key missing or not recognized.
        '403':
          description: Key lacks the write scope, or the pixel is disabled.
        '422':
          description: No txn, or no identifier matched a contact.
      security:
        - bearerAuth: []
components:
  schemas:
    ConversionRequest:
      type: object
      required:
        - txn
      description: >-
        A conversion that happened where the browser pixel cannot see it — a
        hosted checkout, a payment captured after the visitor left, a phone
        sale, or a CRM deal. Send at least one identifier; the strongest one
        wins.
      properties:
        txn:
          type: string
          description: >-
            Your unique id for this conversion. Required: a retried webhook with
            the same txn is recorded once, never twice.
          example: order_10482
        value:
          type: number
          format: double
          description: Revenue. Omit for a non-sale event.
          example: 49.99
        currency:
          type: string
          default: USD
          example: USD
        event:
          type: string
          default: purchase
          description: >-
            purchase exits the contact from flows that opted in. Use action or
            lead for a trackable non-sale.
          example: purchase
        email:
          type: string
          format: email
          description: Identifier. Matched case-insensitively.
        phone:
          type: string
          description: >-
            Identifier. E.164 preferred; 10- and 11-digit US numbers are
            normalized.
          example: '+14155550123'
        external_id:
          type: string
          description: >-
            Identifier. Your own id for the person, if you have stored one on
            the contact.
        vid:
          type: string
          description: Identifier. The pixel's visitor id, if your page captured it.
        vcx:
          type: string
          description: Identifier. The click id from a tracked link.
    ConversionResponse:
      type: object
      properties:
        conversion:
          type: object
          properties:
            recorded:
              type: boolean
            duplicate:
              type: boolean
              description: >-
                True when this txn was already recorded. The call succeeded and
                nothing was written twice.
            contact_id:
              type:
                - string
                - 'null'
              format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key (`as_live_…`), created under Settings → API keys.

````