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

# List conversions

> The workspace's conversions, most recently recorded first — those this API recorded and those Sailer recorded itself (a deal won, a Meta instant form). Retracted ones are left out unless `include_retracted=true`.

`occurred_from` is inclusive and `occurred_to` exclusive, both on `occurred_at` — when the conversion happened, which differs from `created_at` for anything reported late.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/conversions
openapi: 3.1.0
info:
  description: >-
    The Sailer REST API for CRM, conversations, and campaigns.


    **Authentication.** Send a token as `Authorization: Bearer <token>`. A
    workspace

    token (`sk_live_...`) is created by a workspace administrator and its secret
    is

    shown once. An OAuth access token (`oat_live_...`) acts on behalf of the
    person

    who authorized it and sees only what they can see. Either way the workspace
    is

    implied by the token, so no tenant header is needed. Each token carries
    scopes;

    `GET /v1/me` lists them.


    **Pagination.** Collections return `{data, meta, links}`. Pass `links.next`
    back

    as `cursor` until it is `null`. Cursors are opaque and only valid for the
    query

    that produced them.


    **Errors.** Every non-2xx response is `{"error": {...}}` with a coarse
    `type`, a

    stable `code` and the offending `param`. Quote `error.request_id` (also the

    `X-Request-ID` header) when contacting support.


    **Retries.** Send an `Idempotency-Key` header on any write to make retrying
    it

    safe for 24 hours.


    **Rate limits.** Limits are per token. Every response carries

    `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; a
    `429`

    also carries `Retry-After`.


    **Custom fields.** Workspace-defined fields appear under `custom_fields`,
    keyed

    by field key. `GET /v1/fields` lists every field on a resource, built-in and

    custom.
  title: Sailer API
  version: 1.0.0
servers:
  - url: https://api.chatsailer.com
security:
  - SailerApiToken: []
tags:
  - description: Token introspection and workspace capabilities.
    name: Meta
  - description: >-
      People you talk to. Called *leads* in older Sailer surfaces; `contact` is
      the current name.
    name: Contacts
  - description: Companies that contacts belong to (B2B accounts).
    name: Organizations
  - description: Opportunities moving through a pipeline.
    name: Deals
  - description: Pipelines and their stages.
    name: Pipelines
  - description: Field definitions, including custom fields.
    name: Fields
  - description: Free-text annotations on CRM records.
    name: Notes
  - description: Scheduled and logged CRM activities.
    name: Activities
  - description: Per-entity label catalogs.
    name: Tags
  - description: Members of the workspace, for assigning records.
    name: Users
  - description: Message threads with contacts, across every channel.
    name: Conversations
  - description: Outbound campaigns and their participants.
    name: Campaigns
  - description: Named contact lists campaigns draw from.
    name: Audiences
  - description: The connections you talk to contacts through.
    name: Channels
  - description: Pre-approved WhatsApp message templates.
    name: Templates
  - description: >-
      Aggregated numbers for your own BI, computed by the same code as the
      Sailer app's reports.
    name: Reports
  - description: >-
      Keeping another system in step with a workspace: the deletion feed.
      Changes are read from each resource's list with `updated_since`.
    name: Sync
  - description: >-
      Business outcomes your systems report — a sale closed, a meeting held.
      Reports count them, a contract that prices one bills it, and Meta learns
      from the ones sent there. Never edited: a refund retracts the conversion.
      Needs the `conversions:read` / `conversions:write` scopes.
    name: Conversions
paths:
  /v1/conversions:
    get:
      tags:
        - Conversions
      summary: List conversions
      description: >-
        The workspace's conversions, most recently recorded first — those this
        API recorded and those Sailer recorded itself (a deal won, a Meta
        instant form). Retracted ones are left out unless
        `include_retracted=true`.


        `occurred_from` is inclusive and `occurred_to` exclusive, both on
        `occurred_at` — when the conversion happened, which differs from
        `created_at` for anything reported late.
      operationId: list_conversions
      parameters:
        - description: Only conversions of this type key.
          in: query
          name: conversion_key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Only conversions of this type key.
            title: Conversion Key
        - description: Only conversions of this contact.
          in: query
          name: contact_id
          required: false
          schema:
            anyOf:
              - description: Unique identifier for a contact.
                examples:
                  - con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4
                pattern: ^con_[0-9a-f]{32}$
                type: string
              - type: 'null'
            description: Only conversions of this contact.
            title: Contact Id
        - description: Only conversions that occurred at or after this instant.
          in: query
          name: occurred_from
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Only conversions that occurred at or after this instant.
            title: Occurred From
        - description: Only conversions that occurred before this instant.
          in: query
          name: occurred_to
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            description: Only conversions that occurred before this instant.
            title: Occurred To
        - description: Also return retracted conversions.
          in: query
          name: include_retracted
          required: false
          schema:
            default: false
            description: Also return retracted conversions.
            title: Include Retracted
            type: boolean
        - description: Items per page (max 200).
          in: query
          name: limit
          required: false
          schema:
            default: 50
            description: Items per page (max 200).
            maximum: 200
            minimum: 1
            title: Limit
            type: integer
        - description: Opaque cursor from a previous response's `links.next`.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Opaque cursor from a previous response's `links.next`.
            title: Cursor
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionList'
          description: Successful Response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - SailerApiToken: []
components:
  schemas:
    ConversionList:
      description: A page of conversions.
      properties:
        data:
          items:
            $ref: '#/components/schemas/Conversion'
          title: Data
          type: array
        links:
          $ref: '#/components/schemas/PageLinks'
        meta:
          $ref: '#/components/schemas/PageMeta'
      required:
        - data
        - meta
        - links
      title: ConversionList
      type: object
    Conversion:
      description: One conversion.
      properties:
        contact_id:
          anyOf:
            - description: Unique identifier for a contact.
              examples:
                - con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4
              pattern: ^con_[0-9a-f]{32}$
              type: string
            - type: 'null'
          title: Contact Id
        conversation_id:
          anyOf:
            - description: Unique identifier for a conversation.
              examples:
                - conv_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4
              pattern: ^conv_[0-9a-f]{32}$
              type: string
            - type: 'null'
          title: Conversation Id
        conversion_key:
          title: Conversion Key
          type: string
        created_at:
          description: When Sailer recorded the conversion.
          format: date-time
          title: Created At
          type: string
        currency:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO-4217 code of `value`.
          examples:
            - BRL
          title: Currency
        deal_id:
          anyOf:
            - description: Unique identifier for a deal.
              examples:
                - deal_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4
              pattern: ^deal_[0-9a-f]{32}$
              type: string
            - type: 'null'
          title: Deal Id
        dedupe_key:
          title: Dedupe Key
          type: string
        id:
          description: Unique identifier for a conversion.
          examples:
            - cnv_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4
          pattern: ^cnv_[0-9a-f]{32}$
          title: Id
          type: string
        note:
          anyOf:
            - type: string
            - type: 'null'
          title: Note
        object:
          const: conversion
          default: conversion
          title: Object
          type: string
        occurred_at:
          format: date-time
          title: Occurred At
          type: string
        recorded_by:
          $ref: '#/components/schemas/ConversionRecordedBy'
          description: >-
            Who recorded it: `public_api` for this API; Sailer's own producers
            (`system` for a deal won, `meta_leadgen` for a Meta instant form, …)
            otherwise.
        retracted_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When it was retracted. A retracted conversion stays retracted.
          title: Retracted At
        retraction_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Retraction Reason
        value:
          anyOf:
            - type: string
            - type: 'null'
          description: Value in major units of `currency`, e.g. `1500.00`.
          title: Value
      required:
        - id
        - conversion_key
        - recorded_by
        - dedupe_key
        - occurred_at
        - created_at
      title: Conversion
      type: object
    PageLinks:
      properties:
        next:
          anyOf:
            - type: string
            - type: 'null'
          description: Opaque cursor for the following page; null on the last page.
          title: Next
      title: PageLinks
      type: object
    PageMeta:
      properties:
        has_more:
          description: True when a next page exists.
          title: Has More
          type: boolean
        limit:
          description: Maximum items requested for this page.
          title: Limit
          type: integer
      required:
        - limit
        - has_more
      title: PageMeta
      type: object
    ApiErrorResponse:
      description: Every non-2xx response on the public API has this body.
      properties:
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - error
      title: ApiErrorResponse
      type: object
    ConversionRecordedBy:
      description: >-
        Who recorded a conversion: `public_api` for this API, otherwise one of
        Sailer's own producers.
      enum:
        - meta_leadgen
        - entry_link
        - tracked_link
        - integration
        - ai_agent
        - user
        - automation
        - public_api
        - system
      title: ConversionRecordedBy
      type: string
    ApiError:
      properties:
        code:
          description: Stable, machine-readable identifier.
          title: Code
          type: string
        detail:
          anyOf:
            - items:
                $ref: '#/components/schemas/ErrorDetail'
              type: array
            - type: 'null'
          default: null
          description: Per-field errors for validation failures.
          title: Detail
        documentation_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Documentation Url
        message:
          description: Human-readable explanation.
          title: Message
          type: string
        param:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Request field the error refers to, if any.
          title: Param
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Echoes the X-Request-ID response header. Quote it in support
            requests.
          title: Request Id
        type:
          $ref: '#/components/schemas/ErrorType'
      required:
        - type
        - code
        - message
      title: ApiError
      type: object
    ErrorDetail:
      properties:
        code:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Code
        field:
          description: Dotted path to the offending field.
          title: Field
          type: string
        message:
          title: Message
          type: string
      required:
        - field
        - message
      title: ErrorDetail
      type: object
    ErrorType:
      description: Coarse class of failure. Stable; new codes may appear under a type.
      enum:
        - invalid_request_error
        - authentication_error
        - permission_error
        - not_found_error
        - conflict_error
        - rate_limit_error
        - api_error
      title: ErrorType
      type: string
  headers:
    X-RateLimit-Limit:
      description: Requests allowed in the current window on this token.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Seconds until the window resets and the allowance refills.
      schema:
        type: integer
    X-Request-ID:
      description: Unique id for this request. Quote it to support.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
      description: A query parameter, path segment or header is invalid.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
      description: The token is missing, unknown, revoked or expired.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
      description: >-
        The token lacks a required scope, or the workspace's CRM write policy
        does not allow this change.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
      description: Too many requests on this token. Retry after the delay.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
      description: Something went wrong on our side. Quote `error.request_id` to support.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
  securitySchemes:
    SailerApiToken:
      description: >-
        A workspace API token (`sk_live_...`) or an OAuth access token
        (`oat_live_...`). Create workspace tokens in Settings > API. Send either
        as `Authorization: Bearer <token>`.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.