---
title: "Report conversion events"
method: POST
path: "/api/v1/conversions/events"
tags: ["conversions"]
---

# Report conversion events

`POST /api/v1/conversions/events`

## Request

- Base URL: `https://api.growomat.com`
- URL: `https://api.growomat.com/api/v1/conversions/events`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

The general way to tell Growomat that something happened: a sign-up, a trial, a qualified lead, a payment or an upgrade. Send events from your own stack (one, an array, or `{ events }`), or pass a provider payload with `source` set to `stripe`, `hubspot`, `salesforce`, `ga4` or `webhook` and let the server normalise it.

A funnel `event` name creates its conversion action on first use; adjustment rows are routed to the adjustments path. Also accepted with the `campaigns:write` scope.

With a **website key** (`grow_pub_…`) the operation runs in a constrained form: the source is set by the server, `adjustments` are refused (`ADJUSTMENTS_NOT_ALLOWED`), a declared `source` is refused (`SOURCE_NOT_ALLOWED`), conversion actions are never created, and at most 10 events are accepted per request. Sales reported this way are stored as unverified claims and are neither uploaded to an ad platform nor counted in any report until a server-side source confirms the same `orderId`.

**Errors**

- `400 VALIDATION_ERROR`: the body failed validation; `details.issues[]` names each field.

## Headers

- `X-Space-Id` string

## Request body

- union: One event, an array of events, or an object with `events` and/or a provider payload.
  - ConversionEvent: One conversion event from your own stack. Provide a click id and/or an email so it can be matched to the click or the identity.
    - `email` string: The person's email. Hashed at rest.
    - `externalId` string: Your own id for the person.
    - `phone` string: Phone number in E.164 format. Hashed at rest.
    - `msclkid` string: Microsoft Advertising click id.
    - `gclid` string: Google Ads click id.
    - `gbraid` string: Google Ads click id for app campaigns on iOS.
    - `wbraid` string: Google Ads click id for web campaigns on iOS.
    - `rdt_cid` string: Reddit Ads click id.
    - `fbclid` string: Meta click id.
    - `oppref` string: ChatGPT Ads click id.
    - `li_fat_id` string: LinkedIn Ads click id.
    - `event` string: Funnel event name: `signup`, `trial_started`, `qualified_lead`, `paid` or `expansion`. Its conversion action is created on first use.
    - `conversionAction` string: An explicit conversion action name or id, as an alternative to `event`.
    - `value` number: Value of the event.
    - `currency` string: ISO 4217 currency of `value`.
    - `occurredAt` string, date-time: When the event happened (ISO 8601).
    - `orderId` string: Idempotency key, for example a Stripe object id or a CRM deal id.
    - `consent` ConsentSignal: Consent Mode signals for visitors in the EEA. `UNKNOWN` is sent to the platform as `DENIED`.
      - `ad_user_data` 'GRANTED' | 'DENIED' | 'UNKNOWN': Whether user data may be used for advertising.
      - `ad_personalization` 'GRANTED' | 'DENIED' | 'UNKNOWN': Whether ads may be personalised.
  - ConversionEvent[]
    - `email` string: The person's email. Hashed at rest.
    - `externalId` string: Your own id for the person.
    - `phone` string: Phone number in E.164 format. Hashed at rest.
    - `msclkid` string: Microsoft Advertising click id.
    - `gclid` string: Google Ads click id.
    - `gbraid` string: Google Ads click id for app campaigns on iOS.
    - `wbraid` string: Google Ads click id for web campaigns on iOS.
    - `rdt_cid` string: Reddit Ads click id.
    - `fbclid` string: Meta click id.
    - `oppref` string: ChatGPT Ads click id.
    - `li_fat_id` string: LinkedIn Ads click id.
    - `event` string: Funnel event name: `signup`, `trial_started`, `qualified_lead`, `paid` or `expansion`. Its conversion action is created on first use.
    - `conversionAction` string: An explicit conversion action name or id, as an alternative to `event`.
    - `value` number: Value of the event.
    - `currency` string: ISO 4217 currency of `value`.
    - `occurredAt` string, date-time: When the event happened (ISO 8601).
    - `orderId` string: Idempotency key, for example a Stripe object id or a CRM deal id.
    - `consent` ConsentSignal: Consent Mode signals for visitors in the EEA. `UNKNOWN` is sent to the platform as `DENIED`.
      - `ad_user_data` 'GRANTED' | 'DENIED' | 'UNKNOWN': Whether user data may be used for advertising.
      - `ad_personalization` 'GRANTED' | 'DENIED' | 'UNKNOWN': Whether ads may be personalised.
  - object: A batch of your own events, or a provider payload that the server normalises according to `source`.
    - `events` ConversionEvent[]
      - `email` string: The person's email. Hashed at rest.
      - `externalId` string: Your own id for the person.
      - `phone` string: Phone number in E.164 format. Hashed at rest.
      - `msclkid` string: Microsoft Advertising click id.
      - `gclid` string: Google Ads click id.
      - `gbraid` string: Google Ads click id for app campaigns on iOS.
      - `wbraid` string: Google Ads click id for web campaigns on iOS.
      - `rdt_cid` string: Reddit Ads click id.
      - `fbclid` string: Meta click id.
      - `oppref` string: ChatGPT Ads click id.
      - `li_fat_id` string: LinkedIn Ads click id.
      - `event` string: Funnel event name: `signup`, `trial_started`, `qualified_lead`, `paid` or `expansion`. Its conversion action is created on first use.
      - `conversionAction` string: An explicit conversion action name or id, as an alternative to `event`.
      - `value` number: Value of the event.
      - `currency` string: ISO 4217 currency of `value`.
      - `occurredAt` string, date-time: When the event happened (ISO 8601).
      - `orderId` string: Idempotency key, for example a Stripe object id or a CRM deal id.
      - `consent` ConsentSignal: Consent Mode signals for visitors in the EEA. `UNKNOWN` is sent to the platform as `DENIED`.
        - `ad_user_data` 'GRANTED' | 'DENIED' | 'UNKNOWN': Whether user data may be used for advertising.
        - `ad_personalization` 'GRANTED' | 'DENIED' | 'UNKNOWN': Whether ads may be personalised.
    - `source` 'stripe' | 'webhook' | 'hubspot' | 'salesforce' | 'ga4': Which provider `payload` comes from.
    - `payload` object: The provider's own payload, when `source` is set.
    - `config` object: Per-call source settings, such as event or stage mappings.

## Response `200`

OK. The result is in `data`. List responses also carry `meta` with `nextCursor` and `total`.

- SuccessEnvelope: The shape of every successful response.
  - `data` unknown, required
  - `meta` object: Present on list responses.
    - `nextCursor` union: Pass as `cursor` to get the next page. `null` on the last page.
      - string
      - number
    - `total` integer: Number of items in this page.

## Other responses

- `201`: Created. The new resource is in `data`.
- `400`: The request is malformed or fails validation. `error.code` is `VALIDATION_ERROR` (with `details.issues[]` naming each field), `INVALID_REQUEST` (the body is not valid JSON or has the wrong shape), or one of the specific codes listed in this operation's description.
- `401`: The bearer token is missing, invalid, expired or revoked (`INVALID_TOKEN`).
- `403`: The token lacks the scope this operation needs (`INSUFFICIENT_SCOPE`), the plan is read-only (`READ_ONLY_MODE`), or the caller is not a member of the Space named in `X-Space-Id` (`NOT_A_MEMBER`).
- `404`: No such resource in the active Space (`NOT_FOUND`), or `X-Space-Id` names a Space that does not exist (`SPACE_NOT_FOUND`).
- `409`: The request conflicts with the current state, for example a delete blocked by dependents or a sync already running. This operation's description names the `error.code` values it can return.
- `429`: Too many requests (`RATE_LIMITED`). Wait for the number of seconds in the `Retry-After` header, then retry.

## Changes

- **2026-10-20** `f02611b531aa`: 1 breaking, 5 info
  - removed `subschema #2, subschema #3` from the request body `oneOf` list
  - added the new optional request property `oneOf[#/components/schemas/ConversionEvent]/fbclid`
  - added the new optional request property `oneOf[#/components/schemas/ConversionEvent]/li_fat_id`
  - added the new optional request property `oneOf[#/components/schemas/ConversionEvent]/oppref`
  - …2 more

[Operation history](https://skmtc.dev/growomat/apis/growomat-public-api/changes/api/v1/conversions/events/post.md)

---

[API](https://skmtc.dev/growomat/apis/growomat-public-api.md) · [All operations](https://skmtc.dev/growomat/apis/growomat-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/growomat/apis/growomat-public-api/revisions/f02611b531aa?raw)