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

# Conversion Postback

> Send server-side conversion events to Growth Channel.

<Note>
  This endpoint is protected and requires a public API key for access.
</Note>

<RequestExample>
  ```bash Request theme={null}
    curl --request POST \
      --url 'http://gc-api-prod.us-east-1.elasticbeanstalk.com/api/public/growth-channel-postback/' \
      --header 'Content-Type: application/json' \
      --header 'X-Api-Key: YOUR_PUBLIC_API_KEY' \
      --data '{
        "ref_id": "abc123xyz",
        "event_name": "user_converted",
        "revenue": 123,
        "conversion_data": {
          "order_id": "order_98765",
          "lead_source": "callrail"
        }
      }'
  ```
</RequestExample>

<CardGroup>
  <Card title="Method" icon="puzzle-piece">
    `POST`
  </Card>

  <Card title="Endpoint" icon="link">
    `/api/public/growth-channel-postback/`
  </Card>
</CardGroup>

## Overview

Use this endpoint to send server-side conversion events to Growth Channel. The client should capture a unique tracking ID from the campaign landing URL and send it back when a conversion happens.

<Info>
  Send `ref_id` for every conversion. Add `event_name`, `revenue`, `tracker_id`, and `conversion_data` when you need more specific attribution or reporting metadata.
</Info>

## Headers

<ParamField header="X-Api-Key" type="string" required>
  Your public API key for authorization.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="ref_id" type="string" required>
  Unique tracking ID captured from the landing page URL.
</ParamField>

<ParamField body="tracker_id" type="string">
  Conversion tracker ID when the conversion should be attributed to a specific tracker.
</ParamField>

<ParamField body="event_name" type="string" example="user_converted">
  Name of the conversion event, for example `user_converted` or `phone_call`.
</ParamField>

<ParamField body="revenue" type="number" example="123">
  Revenue amount for the conversion.
</ParamField>

<ParamField body="conversion_data" type="object">
  Additional metadata for the conversion.

  <Expandable title="object">
    <ParamField body="order_id" type="string" example="order_98765">
      Order or transaction identifier.
    </ParamField>

    <ParamField body="lead_source" type="string" example="callrail">
      Source associated with the lead or conversion.
    </ParamField>

    <ParamField body="call_duration" type="number" example="180">
      Call duration in seconds.
    </ParamField>

    <ParamField body="customer_type" type="string" example="new">
      Customer category or segment.
    </ParamField>
  </Expandable>
</ParamField>

## Setup Guide

<Steps>
  <Step title="Add a tracking ID to the landing URL">
    Add a tracking ID macro to the campaign landing URL.

    ```text theme={null}
    https://example.com/track?ref_id={TRACKING_ID}
    ```
  </Step>

  <Step title="Capture the tracking ID">
    Capture and store `ref_id` when the visitor lands on the site.
  </Step>

  <Step title="Send the conversion">
    When the user converts, send `ref_id` to this endpoint with optional `event_name`, `revenue`, and `conversion_data`.
  </Step>

  <Step title="Use a tracker when needed">
    Use `tracker_id` only when attribution should go to a specific conversion tracker.
  </Step>
</Steps>

## Example

```json theme={null}
{
  "ref_id": "abc123xyz",
  "event_name": "user_converted",
  "revenue": 123,
  "conversion_data": {
    "order_id": "order_98765",
    "lead_source": "callrail"
  }
}
```

## Responses

<Tabs>
  <Tab title="200 OK">
    ```json theme={null}
    {
      "status": "ok"
    }
    ```

    <ResponseField name="status" type="string">
      Request status value.
    </ResponseField>
  </Tab>

  <Tab title="400 Bad Request">
    Returned if the request body is invalid or `ref_id` is missing.

    ```json theme={null}
    {
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Missing required field: ref_id",
        "request_id": "..."
      }
    }
    ```
  </Tab>

  <Tab title="401 Unauthorized">
    Returned if the `X-Api-Key` header is missing or invalid.
  </Tab>

  <Tab title="502 Bad Gateway">
    Returned if the conversion provider is temporarily unavailable.

    ```json theme={null}
    {
      "error": {
        "code": "CONVERSION_PROVIDER_UNAVAILABLE",
        "message": "Conversion provider temporarily unavailable",
        "request_id": "..."
      }
    }
    ```
  </Tab>
</Tabs>