---
title: "Create a conversion action"
method: POST
path: "/api/v1/conversion-actions"
tags: ["conversions"]
---

# Create a conversion action

`POST /api/v1/conversion-actions`

## Request

- Base URL: `https://api.growomat.com`
- URL: `https://api.growomat.com/api/v1/conversion-actions`
- Auth: HTTP bearer

Creates the action locally. A sync exports it to the platforms, which assign the remote id and the tag snippet; a client cannot set the platform link itself.

**Errors**

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

## Headers

- `X-Space-Id` string

## Request body

- ConversionActionCreate: What counts as a conversion, and how it is counted and valued.
  - `name` string, required: Display name, also accepted wherever a conversion action is referenced by name.
  - `type` 'WEBPAGE' | 'AD_CALL' | 'WEBSITE_CALL' | 'UPLOAD_CLICKS' | 'UPLOAD_CALLS', required: Where the conversion is observed. `UPLOAD_CLICKS` and `UPLOAD_CALLS` are the types for conversions you report through this API.
  - `category` 'PURCHASE' | 'ADD_TO_CART' | 'BEGIN_CHECKOUT' | 'SUBSCRIBE_PAID' | 'SUBMIT_LEAD_FORM' | 'SIGNUP' | 'CONTACT' | 'BOOK_APPOINTMENT' | 'REQUEST_QUOTE' | 'GET_DIRECTIONS' | 'PAGE_VIEW' | 'DOWNLOAD' | 'PHONE_CALL_LEAD' | 'ENGAGEMENT' | 'DEFAULT', required: What kind of outcome this is, as the platforms classify it.
  - `status` 'ENABLED' | 'PAUSED': A paused action records nothing.
  - `countingType` 'ONE_PER_CLICK' | 'MANY_PER_CLICK': `ONE_PER_CLICK` for leads and sign-ups, `MANY_PER_CLICK` for purchases.
  - `valueSettings` ConversionActionValueSettings: How much a conversion of this action is worth.
    - `type` 'noValue' | 'fixedValue' | 'variableValue': `noValue`: count only. `fixedValue`: every conversion is worth `defaultValue`. `variableValue`: each upload carries its own value, with `defaultValue` as the fallback.
    - `defaultValue` number: The fixed or fallback value.
    - `currencyCode` string: ISO 4217 currency of `defaultValue`.
  - `clickThroughLookbackWindowDays` integer: How many days after a click a conversion still counts. Capped at 30 by the platform for all types except calls, where 60 is allowed.
  - `viewThroughLookbackWindowDays` integer: How many days after an ad view (without a click) a conversion still counts.
  - `attributionModel` 'DATA_DRIVEN' | 'LAST_CLICK': How credit is split across the clicks before a conversion.
  - `enhancedConversionsForLeads` boolean: Enable Enhanced Conversions for Leads, so uploads that carry only a hashed email or phone can still be matched after the click id is gone.
  - `leadStage` 'signup' | 'trial_started' | 'qualified_lead' | 'paid' | 'expansion': The funnel stage this action represents. Events reported with this `event` name land here.
  - `defaultEventValue` number: Value assigned to an event that arrives without one.
  - `includeInConversionsMetric` boolean: Whether the platform counts this action in its headline conversions number and optimises bidding for it.

## 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.

---

[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)