> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/conversions.md).

# Conversions

Revenue attribution, read-only. A **conversion definition** (created in the dashboard) describes the outcome to count and which campaigns can earn credit. Gleantap periodically attributes matching activity to the last campaign or flow touch within the definition's window and records one **conversion** row per attribution. `attribution_channel` is `email`, `sms`, or `flow`; treat an empty value as unknown attribution.

## List conversion definitions.

> The conversion rules configured for the workroom — what counts as a conversion, what each is worth, and which campaign it attributes to. Use this to find a \`conversion\_id\` before filtering the report, or to explain why a conversion is or is not being recorded.\
> \
> An unparseable \`campaign\_id\` or an unrecognised \`event\_type\` is rejected rather than ignored, so a mistyped filter cannot come back as a full unfiltered list.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversions","description":"Revenue attribution. A Conversion is a rule the dashboard authors — a contact condition plus a \"Targeted By\" clause naming a campaign — and a periodic job walks recent activity, decides which campaign or flow touch earned the credit, and writes one row per attributed conversion. This resource reads both halves: the definitions, and the attributed rows.\n\nRead-only, and necessarily so: a definition created here would not retroactively produce rows, and a row written here would not correspond to anything that happened.\n\nAttribution is last-touch within each definition's window. `attribution_channel` is `email` or `sms` when a campaign touch won and `flow` when a flow step did; two of the writers instead copy the campaign's own `type`, which adds the legacy `push` and `snailmail` values on historic rows. It can also be empty, because about 1% of campaigns carry no type at all — treat an empty channel as unknown attribution, not as a missing record.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["campaigns:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"Conversion":{"type":"object","description":"A conversion definition — the rule that decides what counts as a conversion and what it is worth.","properties":{"object":{"type":"string","enum":["conversion"]},"id":{"$ref":"#/components/schemas/ConversionId"},"name":{"type":"string"},"value":{"type":"number","nullable":true,"description":"Money credited per conversion. Stored as a string by the dashboard; surfaced as a number because the report sums it."},"event_type":{"type":"string","description":"Which kind of activity the rule keys on. The vocabulary below is taken from the values actually present in the collection.\n","enum":["became_a_customer","contract_active","custom","had_a_visit","made_a_purchase","membership_active","message_received"]},"campaign_id":{"allOf":[{"$ref":"#/components/schemas/CampaignId"}],"nullable":true},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"criteria":{"type":"object","description":"The rule, in the same condition DSL segments use. The clause naming a campaign with \"Targeted By\" is what makes this attribution rather than a plain segment.\n"}}},"ConversionId":{"type":"string","pattern":"^cvn_[0-9a-f]{24}$","description":"Prefixed `cvn_`, not `cnv_` — that prefix already belongs to conversations.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/conversions":{"get":{"tags":["Conversions"],"operationId":"listConversions","summary":"List conversion definitions.","description":"The conversion rules configured for the workroom — what counts as a conversion, what each is worth, and which campaign it attributes to. Use this to find a `conversion_id` before filtering the report, or to explain why a conversion is or is not being recorded.\n\nAn unparseable `campaign_id` or an unrecognised `event_type` is rejected rather than ignored, so a mistyped filter cannot come back as a full unfiltered list.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"description":"Filterable fields: `campaign_id` (a `cam_` id), `event_type` (one of became_a_customer, contract_active, custom, had_a_visit, made_a_purchase, membership_active, message_received), and `name` (prefix match, case-insensitive). Anything else is rejected rather than ignored.\n","schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"Conversion definitions.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversion"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Attributed conversions and revenue.

> Which campaigns and flows earned conversions, and what they were worth. Reads the table a periodic job builds; it does not recompute attribution, so a conversion that happened minutes ago may not appear yet.\
> \
> Returns one row per attributed conversion, plus a \`summary\`. Pass \`group\_by\` to get a rollup instead of rows — \`channel\`, \`campaign\`, \`flow\`, \`location\`, \`event\_type\` or \`day\`. For \`campaign\` and \`flow\` the group key comes back as a prefixed id, so it can be passed straight back as a filter to drill in.\
> \
> Every filter combines with every other, and \`group\_by\` respects them, so "revenue by location for one flow since March" is one call. Filters are accepted either bare (\`?channel=email\`) or as \`filter\[channel]=email\`.\
> \
> \`total\_value\` sums a field the writer stores as a string; a row whose value cannot be read as a number contributes 0 rather than failing the report.\
> \
> Scoped to one workroom unless a workroom is named or \`workroom=all\` is passed.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversions","description":"Revenue attribution. A Conversion is a rule the dashboard authors — a contact condition plus a \"Targeted By\" clause naming a campaign — and a periodic job walks recent activity, decides which campaign or flow touch earned the credit, and writes one row per attributed conversion. This resource reads both halves: the definitions, and the attributed rows.\n\nRead-only, and necessarily so: a definition created here would not retroactively produce rows, and a row written here would not correspond to anything that happened.\n\nAttribution is last-touch within each definition's window. `attribution_channel` is `email` or `sms` when a campaign touch won and `flow` when a flow step did; two of the writers instead copy the campaign's own `type`, which adds the legacy `push` and `snailmail` values on historic rows. It can also be empty, because about 1% of campaigns carry no type at all — treat an empty channel as unknown attribution, not as a missing record.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["campaigns:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"FlowId":{"type":"string","pattern":"^flw_[0-9a-f]{24}$"},"ConversionId":{"type":"string","pattern":"^cvn_[0-9a-f]{24}$","description":"Prefixed `cvn_`, not `cnv_` — that prefix already belongs to conversations.\n"},"ConversionReport":{"type":"object","description":"Attributed conversions, one row per contact per conversion.","properties":{"object":{"type":"string","enum":["conversion_report"]},"summary":{"type":"object","properties":{"conversions":{"type":"integer","description":"Unique converted contacts — the dashboard's Conversions headline. A contact converting twice counts once."},"conversion_events":{"type":"integer","description":"Raw attributed conversion rows (a contact converting twice counts twice)."},"total_value":{"type":"number"},"contacts":{"type":"integer","description":"Same as `conversions` (kept for compatibility)."}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversionReportRow"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}},"ConversionReportRow":{"type":"object","description":"One attributed conversion — one contact, one earning touch.","properties":{"object":{"type":"string","enum":["conversion_report_row"]},"conversion_id":{"$ref":"#/components/schemas/ConversionId"},"contact_id":{"allOf":[{"$ref":"#/components/schemas/ContactId"}],"nullable":true},"value":{"type":"number","nullable":true},"event_type":{"type":"string"},"attribution_channel":{"type":"string","description":"`email` or `sms` when a campaign touch earned the credit, `flow` when a flow step did. `push` and `snailmail` are legacy campaign types that no longer send but still appear on historic rows. Empty means the writer could not determine a channel — unknown attribution, not a broken row.\n","enum":["","email","sms","push","snailmail","flow"]},"campaign_id":{"allOf":[{"$ref":"#/components/schemas/CampaignId"}],"nullable":true},"flow_id":{"allOf":[{"$ref":"#/components/schemas/FlowId"}],"nullable":true},"campaign_step":{"type":"string"},"location":{"type":"string","description":"Copied from the contact's `accountinfo.location`, falling back to `data.location`. Free text, and numeric for some accounts."},"converted_at":{"type":"string","format":"date-time"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"ConversionReportGrouped":{"type":"object","description":"The same report rolled up on one dimension. Returned instead of the row list whenever `group_by` is passed.","properties":{"object":{"type":"string","enum":["conversion_report_grouped"]},"group_by":{"type":"string"},"summary":{"type":"object","properties":{"conversions":{"type":"integer","description":"Unique converted contacts across all returned groups (not the sum of group counts — a contact can appear in several groups)."},"conversion_events":{"type":"integer","description":"Raw conversion rows across all returned groups."},"total_value":{"type":"number"}}},"groups":{"type":"array","description":"Ordered by unique converted contacts, except `group_by=day`, which is chronological. Capped at 500 groups. With `group_by=channel`, flow-won rows are folded into the channel (`sms`/`email`) their sending campaign went out on, as the dashboard does; `flow` remains only for rows whose sending campaign can't be resolved.","items":{"type":"object","properties":{"key":{"type":"string","description":"The dimension value. `(none)` when the row carries no value for it. For `campaign` and `flow` this is a prefixed id, so it can be passed straight back as the `campaign_id` / `flow_id` filter.\n"},"conversions":{"type":"integer","description":"Unique converted contacts in this group (dashboard breakdown count)."},"conversion_events":{"type":"integer","description":"Raw conversion rows in this group."},"total_value":{"type":"number"},"contacts":{"type":"integer","description":"Same as `conversions` (kept for compatibility)."}}}}}},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/conversions/report":{"get":{"tags":["Conversions"],"operationId":"getConversionReport","summary":"Attributed conversions and revenue.","description":"Which campaigns and flows earned conversions, and what they were worth. Reads the table a periodic job builds; it does not recompute attribution, so a conversion that happened minutes ago may not appear yet.\n\nReturns one row per attributed conversion, plus a `summary`. Pass `group_by` to get a rollup instead of rows — `channel`, `campaign`, `flow`, `location`, `event_type` or `day`. For `campaign` and `flow` the group key comes back as a prefixed id, so it can be passed straight back as a filter to drill in.\n\nEvery filter combines with every other, and `group_by` respects them, so \"revenue by location for one flow since March\" is one call. Filters are accepted either bare (`?channel=email`) or as `filter[channel]=email`.\n\n`total_value` sums a field the writer stores as a string; a row whose value cannot be read as a number contributes 0 rather than failing the report.\n\nScoped to one workroom unless a workroom is named or `workroom=all` is passed.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"group_by","in":"query","description":"Return a rollup on this dimension instead of individual rows.","schema":{"type":"string","enum":["channel","campaign","flow","location","event_type","day","campaign_type","message_channel"]}},{"name":"campaign_type","in":"query","description":"`campaign` for credit won by a campaign someone sent; `flow` for credit won by a flow step.","schema":{"type":"string","enum":["campaign","flow"]}},{"name":"message_channel","in":"query","description":"The channel the crediting message actually went out on, recovered from the sending campaign. Distinct from `channel`, which holds either a channel or `flow` and so loses email-vs-SMS on flow-attributed revenue. Combining the two gives a campaign-vs-flow by email-vs-SMS breakdown.\n","schema":{"type":"string","enum":["email","sms","push","snailmail"]}},{"name":"campaign_id","in":"query","schema":{"$ref":"#/components/schemas/CampaignId"}},{"name":"flow_id","in":"query","schema":{"$ref":"#/components/schemas/FlowId"}},{"name":"conversion_id","in":"query","schema":{"$ref":"#/components/schemas/ConversionId"}},{"name":"location","in":"query","description":"Exact match, case-insensitive. Matches numeric locations too.","schema":{"type":"string"}},{"name":"channel","in":"query","description":"`flow` is a peer of the message channels here, not a separate axis — it is what the writer stores when a flow step earned the credit. `sms` and `email` also include flow-won conversions whose sending campaign went out on that channel (the dashboard's per-channel definition); `flow` matches the stored value only. `push` and `snailmail` only appear on historic rows.\n","schema":{"type":"string","enum":["email","sms","push","snailmail","flow"]}},{"name":"event_type","in":"query","schema":{"type":"string","enum":["became_a_customer","contract_active","custom","had_a_visit","made_a_purchase","membership_active","message_received"]}},{"name":"since","in":"query","description":"Inclusive lower bound on when the conversion was attributed. A date or offset-less time is read in the workroom's timezone, as the dashboard report does.","schema":{"type":"string"}},{"name":"until","in":"query","description":"Inclusive upper bound. A date-only value (`2026-10-31`) includes that whole day in the workroom's timezone.","schema":{"type":"string"}}],"responses":{"200":{"description":"The report — rows, or groups when `group_by` was passed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ConversionReport"},{"$ref":"#/components/schemas/ConversionReportGrouped"}]}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve a conversion definition.

> One conversion rule, including its full \`criteria\` in the segment condition DSL. Use it to see exactly what a conversion requires and which campaign it credits.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Conversions","description":"Revenue attribution. A Conversion is a rule the dashboard authors — a contact condition plus a \"Targeted By\" clause naming a campaign — and a periodic job walks recent activity, decides which campaign or flow touch earned the credit, and writes one row per attributed conversion. This resource reads both halves: the definitions, and the attributed rows.\n\nRead-only, and necessarily so: a definition created here would not retroactively produce rows, and a row written here would not correspond to anything that happened.\n\nAttribution is last-touch within each definition's window. `attribution_channel` is `email` or `sms` when a campaign touch won and `flow` when a flow step did; two of the writers instead copy the campaign's own `type`, which adds the legacy `push` and `snailmail` values on historic rows. It can also be empty, because about 1% of campaigns carry no type at all — treat an empty channel as unknown attribution, not as a missing record.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["campaigns:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Conversion":{"type":"object","description":"A conversion definition — the rule that decides what counts as a conversion and what it is worth.","properties":{"object":{"type":"string","enum":["conversion"]},"id":{"$ref":"#/components/schemas/ConversionId"},"name":{"type":"string"},"value":{"type":"number","nullable":true,"description":"Money credited per conversion. Stored as a string by the dashboard; surfaced as a number because the report sums it."},"event_type":{"type":"string","description":"Which kind of activity the rule keys on. The vocabulary below is taken from the values actually present in the collection.\n","enum":["became_a_customer","contract_active","custom","had_a_visit","made_a_purchase","membership_active","message_received"]},"campaign_id":{"allOf":[{"$ref":"#/components/schemas/CampaignId"}],"nullable":true},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"criteria":{"type":"object","description":"The rule, in the same condition DSL segments use. The clause naming a campaign with \"Targeted By\" is what makes this attribution rather than a plain segment.\n"}}},"ConversionId":{"type":"string","pattern":"^cvn_[0-9a-f]{24}$","description":"Prefixed `cvn_`, not `cnv_` — that prefix already belongs to conversations.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/conversions/{id}":{"get":{"tags":["Conversions"],"operationId":"retrieveConversion","summary":"Retrieve a conversion definition.","description":"One conversion rule, including its full `criteria` in the segment condition DSL. Use it to see exactly what a conversion requires and which campaign it credits.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"The conversion definition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversion"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
