> ## 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. # Record a conversion > Reports a business outcome — a sale closed, a meeting held — that this workspace tracks as a conversion. Reports and the origin of the contact count it, a contract that prices the key bills it, and a type sent to Meta is sent there. `conversion_key` must be one of this workspace's active conversion types (`GET /v1/conversion-types`). Send `value` when the type's `value_basis` is `amount`. **Safe to retry.** `dedupe_key` is your idempotency key, typically your own order id. Resending the same `dedupe_key` answers `200` with the conversion already on file instead of recording it twice. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/conversions openapi: 3.1.0 info: description: >- The Sailer REST API for CRM, conversations, and campaigns. **Authentication.** Send a token as `Authorization: Bearer `. 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: post: tags: - Conversions summary: Record a conversion description: >- Reports a business outcome — a sale closed, a meeting held — that this workspace tracks as a conversion. Reports and the origin of the contact count it, a contract that prices the key bills it, and a type sent to Meta is sent there. `conversion_key` must be one of this workspace's active conversion types (`GET /v1/conversion-types`). Send `value` when the type's `value_basis` is `amount`. **Safe to retry.** `dedupe_key` is your idempotency key, typically your own order id. Resending the same `dedupe_key` answers `200` with the conversion already on file instead of recording it twice. operationId: record_conversion parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/ConversionCreate' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Conversion' description: >- Replayed: a conversion with this `dedupe_key` was already on file and is returned unchanged. Nothing new was recorded. headers: Idempotent-Replay: $ref: '#/components/headers/Idempotent-Replay' 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' '201': content: application/json: schema: $ref: '#/components/schemas/Conversion' description: Successful Response headers: Idempotent-Replay: $ref: '#/components/headers/Idempotent-Replay' 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' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableContent' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - SailerApiToken: [] components: parameters: IdempotencyKey: description: >- A unique value (a UUID works) that makes retrying this request safe. A repeat with the same key and body within 24 hours returns the original response instead of acting twice; the same key with a different body is a `409 idempotency_key_reused`. in: header name: Idempotency-Key required: false schema: maxLength: 255 type: string schemas: ConversionCreate: additionalProperties: false description: Body for `POST /v1/conversions`. properties: contact_id: anyOf: - description: Unique identifier for a contact. examples: - con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^con_[0-9a-f]{32}$ type: string - type: 'null' description: The contact who converted, if known. 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' description: The conversation that led to it, if known. title: Conversation Id conversion_key: description: >- Which conversion this is — the `key` of one of this workspace's active conversion types. List them with `GET /v1/conversion-types`. examples: - sale_closed maxLength: 128 minLength: 1 title: Conversion Key type: string deal_id: anyOf: - description: Unique identifier for a deal. examples: - deal_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^deal_[0-9a-f]{32}$ type: string - type: 'null' description: The deal it closes or advances, if known. title: Deal Id dedupe_key: description: >- Your idempotency key for this fact, e.g. your order id. Unique within the workspace: sending the same key again returns the conversion already on file (`200`) instead of recording a second one — even if the rest of the body differs, so never reuse a key for a different fact. examples: - order-1001 maxLength: 255 minLength: 1 title: Dedupe Key type: string note: anyOf: - maxLength: 2000 type: string - type: 'null' description: Free text kept for audit, e.g. the checkout it came from. title: Note occurred_at: description: >- When the conversion actually happened, with a timezone offset. May be in the past: a conversion reported late is still dated when it happened. examples: - '2026-09-01T12:00:00-03:00' format: date-time title: Occurred At type: string value: anyOf: - minimum: 0 type: number - type: string - type: 'null' description: >- The conversion's value in major units of the workspace currency, e.g. `1500.00` for a R$ 1.500,00 sale. Required when the type's `value_basis` is `amount`; optional when it is `none`. examples: - '1500.00' title: Value required: - conversion_key - dedupe_key - occurred_at title: ConversionCreate 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 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 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 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: Idempotent-Replay: description: >- `true` when this response is a stored replay of an earlier request with the same `Idempotency-Key`. schema: enum: - 'true' type: string 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: 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' Conflict: content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' description: >- The request conflicts with current state, or its `Idempotency-Key` was reused with a different body or is still being processed. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' UnprocessableContent: content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' description: The request body failed validation. 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 `. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.