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

# Report a conversion against one of the workspace's links

> Requires a token with the `conversions:write` permission.



## OpenAPI

````yaml /openapi.json post /api/v1/conversions
openapi: 3.0.0
info:
  description: >-
    Every request carries `Authorization: Bearer utmk_…`. The token fixes the
    workspace; no request names one. Every operation declares `x-permission`,
    the token permission it requires.
  title: UTM Builder API
  version: '1'
servers:
  - url: https://app.utmkit.co
    variables: {}
security:
  - bearer: []
tags: []
paths:
  /api/v1/conversions:
    post:
      tags:
        - conversions
      summary: Report a conversion against one of the workspace's links
      description: Requires a token with the `conversions:write` permission.
      operationId: UtmBuilderWeb.API.V1.ConversionController.create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionInput'
        description: Conversion input
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversion'
          description: Conversion (a retry, already recorded)
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversion'
          description: Conversion
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error
      callbacks: {}
components:
  schemas:
    ConversionInput:
      description: >-
        One result the customer's server reports (spec 046). `link` is the
        `_link` value the landing URL carried and is required on a customer's
        first conversion; afterwards the binding answers.
      properties:
        currency:
          description: Three letters, shape only; kept as given, never converted
          nullable: true
          type: string
        customer_id:
          description: The customer's identifier in the caller's own system
          maxLength: 128
          minLength: 1
          type: string
        event_id:
          description: The caller's identifier for this event; a repeat is a retry
          maxLength: 128
          minLength: 1
          type: string
        kind:
          description: purchase, signup, lead, or a word of the customer's own
          maxLength: 32
          nullable: true
          type: string
        link:
          description: >-
            `<host>/<short_code>`, exactly the `_link` value the landing URL
            carried
          nullable: true
          type: string
        occurred_at:
          description: When it happened. Defaults to now; refused far in the future or past
          format: date-time
          nullable: true
          type: string
        value:
          description: Decimal string, >= 0. Requires currency
          nullable: true
          pattern: ^\d+(\.\d+)?$
          type: string
      required:
        - customer_id
        - event_id
      title: ConversionInput
      type: object
    Conversion:
      description: >-
        A recorded conversion. `attributed_by` says how the link was found on a
        201; `duplicate: true` marks the 200 a retry gets.
      properties:
        attributed_by:
          enum:
            - reference
            - binding
          nullable: true
          type: string
        currency:
          nullable: true
          type: string
        customer_id:
          type: string
        duplicate:
          nullable: true
          type: boolean
        event_id:
          type: string
        id:
          type: integer
        kind:
          type: string
        link:
          nullable: true
          type: string
        occurred_at:
          format: date-time
          type: string
        value:
          nullable: true
          type: string
      title: Conversion
      type: object
    Error:
      description: Every refusal. `code` is the closed set of FR-019.
      properties:
        error:
          properties:
            code:
              enum:
                - unauthenticated
                - subscription_required
                - subscription_ended
                - missing_permission
                - role_forbids
                - plan_forbids
                - rate_limited
                - governance_refused
                - scanner_refused
                - limit_reached
                - duplicate_link
                - not_found
                - invalid_input
              type: string
            details:
              additionalProperties: true
              description: field → messages, on invalid_input
              nullable: true
              type: object
            message:
              type: string
            permission:
              nullable: true
              type: string
            retry_after_seconds:
              nullable: true
              type: integer
          required:
            - code
            - message
          type: object
      required:
        - error
      title: Error
      type: object
  securitySchemes:
    bearer:
      description: utmk_<lookup><secret>, minted on /tokens
      scheme: bearer
      type: http

````