# Custom Integration Params

> Look up every parameter the AnyTrack Custom Integration endpoint accepts, including accepted aliases for click_id and value, the conversion_type to event mapping, the items array, customer traits, and xat_ passthrough parameters.

This page is a complete reference for the parameters the AnyTrack Custom Integration endpoint accepts in a postback or webhook payload.

If you want to learn how to set up the integration, see [Postback URL Integration](/docs/custom). If you want to decide whether a custom integration is the right approach, see [Is a Custom Integration Right for You?](/docs/custom-integration-fit). For the full list of event attributes across all of AnyTrack, see [Event Attributes](/docs/event-attributes).

> 🚧 **Limited**
>
> AnyTrack does not offer setup support for custom integrations not listed in the Integration Catalog. The behavior documented here is provided so you can build the integration yourself.

## How the Endpoint Reads Parameters

When you install a Custom Integration, AnyTrack gives you an endpoint URL. Your platform sends conversions to it as query parameters or a JSON body:

```txt webhook endpoint
https://t1.anytrack.io/<account-id>/collect/<integration-slug>
```

For the core conversion fields below (`click_id`, `value`, `transaction_id`, and similar), names are matched flexibly: case is ignored, and underscores and hyphens are stripped. So `click_id`, `clickid`, and `click-id` all resolve to the same field. Customer traits, `conversion_type`, and passthrough parameters are matched exactly as listed in their sections.

## Identity Parameters

Every payload must include at least one of these so AnyTrack can match the conversion to the original click. If none are present, the conversion is rejected with a "Missing click_id, ref_id and email" error.

| Parameter | Accepted names | Type | Description |
|-----------|----------------|------|-------------|
| `click_id` | `click_id`, `clickid`, `click` | string | The AnyTrack [click ID](/docs/generate-retrieve-and-use-atclid) stored against the visitor session. The primary, recommended match key. |
| `ref_id` | `ref_id`, `refid`, `ref` | string | An external identifier used as an alternative to `click_id`. See [External ID as Click ID](/docs/external-id-as-click-id). |
| `email` | `email` | string | Used as a fallback match key when neither `click_id` nor `ref_id` is present. |

> 📘 **Note**
>
> When only `ref_id` or `email` is sent, AnyTrack uses that value as the match reference instead of the click ID. `click_id` always produces the most reliable attribution.

## Conversion Value

| Parameter | Accepted names | Type | Default | Description |
|-----------|----------------|------|---------|-------------|
| `value` | `value`, `commission`, `amount`, `revenue`, `total`, `total_value`, `event_value` | string or number | — | The monetary value of the conversion. |
| `currency` | `currency`, `cur`, `curr` | string | Property currency | Three-letter currency code (for example, USD). Defaults to the [property default currency](/docs/property-settings) when omitted. |

## Event Classification

AnyTrack decides which event the conversion becomes from three inputs, in this order of priority:

1. **`event_name`** — if present, the conversion is recorded as a custom event with this exact name.
2. **`conversion_type`** — if present (and `event_name` is not), it is mapped to a standard event using the table below.
3. **Automatic** — if neither is sent, AnyTrack infers the event from the conversion value.

| Parameter | Accepted names | Type | Description |
|-----------|----------------|------|-------------|
| `event_name` | `event_name`, `eventname`, `event` | string | A custom event name. Overrides `conversion_type`. Whitespace is trimmed. |
| `conversion_type` | `conversion_type` | string | A standard conversion type. Matched against the values in the mapping table below. |

### conversion_type to Event Mapping

`conversion_type` is matched case-insensitively against these values:

| `conversion_type` value | Resulting AnyTrack event |
|-------------------------|--------------------------|
| `click`, `outbound_click`, `outboundclick` | `OutboundClick` |
| `form_submit`, `formsubmit` | `FormSubmit` |
| `lead`, `cpl` | `Lead` |
| `registration`, `complete_registration`, `completeregistration`, `acquisition`, `cpa` | `CompleteRegistration` |
| `purchase`, `sale`, `cps` | `Purchase` |

> ⚠️ **Warning**
>
> A `conversion_type` value that is not in this table is rejected with an "Unknown conversion_type" error, unless you also send `event_name`. Send a value from the list, or use `event_name` for anything custom.

> ❗ **Important**
>
> For predictable classification, always send `conversion_type` or `event_name`. When you omit both, AnyTrack records a Purchase only if a positive value is sent as `commission`. A value sent under another alias (such as `value`) with no `conversion_type` is recorded as a Lead.

## Transaction and Timing

| Parameter | Accepted names | Type | Default | Description |
|-----------|----------------|------|---------|-------------|
| `transaction_id` | `transaction_id`, `transactionid`, `transaction` | string or number | — | Unique conversion identifier. Used for [deduplication](/docs/deduplication). |
| `brand_name` | `brand_name`, `brandname`, `brand` | string | — | The product or brand name associated with the conversion. |
| `timestamp` | `timestamp`, `time`, `date`, `datetime`, `created_at` | string or number | Time received | A timestamp in seconds that replaces the time AnyTrack received the event. |

## Customer Traits

Customer traits raise Event Match Quality. AnyTrack normalizes and hashes them automatically before sending to ad platforms, so send raw values and never pre-hash them. These names are matched exactly as written.

| Parameter | Accepted names | Type | Notes |
|-----------|----------------|------|-------|
| `email` | `email` | string | Also acts as an identity fallback (see Identity Parameters). |
| `first_name` | `first_name`, `firstName` | string | |
| `last_name` | `last_name`, `lastName` | string | |
| `full_name` | `full_name`, `fullName`, `name` | string | Fills first and last name when sent on its own. |
| `phone` | `phone` | string | Include country and area code. |
| `birthdate` | `birthdate` | string | For example, 1991-05-26. |
| `city` | `city` | string | |
| `state` | `state` | string | Two-letter state or province code. |
| `zipcode` | `zipcode` | string | Zip or postal code. |
| `country` | `country` | string | Two-letter country code recommended. |

## Items Array

For eCommerce conversions, send an `items` array (also accepted as `line_items` or `products`). Each object in the array accepts these fields:

| Field | Accepted names | Type | Description |
|-------|----------------|------|-------------|
| `id` | `id`, `product_id`, `item_id` | string | The item or SKU identifier. |
| `name` | `name`, `title`, `label`, `product_name`, `item_name` | string | The item name. |
| `variant` | `variant`, `variant_id`, `product_variant`, `item_variant` | string | The item variant. |
| `price` | `price`, `product_price`, `item_price` | number | The item price. |
| `quantity` | `qty`, `quantity`, `product_quantity`, `item_quantity` | number | Number of units. |

## Passthrough Parameters

Any parameter whose name starts with `xat_` is stored on the conversion as a passthrough value, with the `xat_` prefix removed. For example, `xat_plan=gold` is stored as `plan=gold`. Use these to carry your own custom data through to AnyTrack.

> 🚧 **Beta**
>
> Passthrough parameters are limited to 5 per conversion and may change. Only parameters with a non-empty value are kept. If you send more than 5, the first 5 are stored and the rest are dropped.

## Limits and Defaults

- **Match key** — At least one of `click_id`, `ref_id`, or `email` is required. Missing all three rejects the conversion.
- **Currency** — Defaults to the property default currency when `currency` is omitted.
- **Timestamp** — Defaults to the time AnyTrack receives the conversion when `timestamp` is omitted.
- **Passthrough parameters** — Maximum 5 (`xat_` prefix). Extra parameters beyond 5 are dropped.
- **Unknown conversion_type** — Rejected unless `event_name` is also sent.

## Example

A Purchase sent as a JSON payload with identity, value, traits, and items:

```json
{
  "click_id": "f8e3bf8dfba8b51ce3340",
  "conversion_type": "purchase",
  "value": 120.00,
  "currency": "USD",
  "transaction_id": "24356562534585",
  "brand_name": "Acme",
  "email": "jsmith@example.com",
  "full_name": "John Smith",
  "country": "US",
  "state": "CA",
  "zipcode": "94025",
  "items": [
    { "id": "20291", "name": "ZX Series Headphones", "quantity": 1, "price": 20.00 },
    { "id": "49292", "name": "Audio Connector", "quantity": 1, "price": 100.00 }
  ],
  "xat_plan": "gold"
}
```

The same conversion as a query string:

```txt postback url
https://t1.anytrack.io/<account-id>/collect/<integration-slug>?click_id=f8e3bf8dfba8b51ce3340&conversion_type=purchase&value=120&currency=USD&transaction_id=24356562534585
```

<FaqAccordion
  title="Custom Integration Parameters FAQ"
  icon="fa-duotone fa-circle-question"
  items={[
    {
      question: "Which parameter names does the Custom Integration accept for revenue?",
      answer: "The conversion value can be sent under any of these names: <code>value</code>, <code>commission</code>, <code>amount</code>, <code>revenue</code>, <code>total</code>, <code>total_value</code>, or <code>event_value</code>. AnyTrack reads the first one it finds. For the most predictable results, pick one name and use it consistently across all your conversions."
    },
    {
      question: "Do parameter names need to match the exact case?",
      answer: "For core conversion fields like <code>click_id</code>, <code>value</code>, and <code>transaction_id</code>, case is ignored and underscores or hyphens are stripped, so <code>click_id</code> and <code>clickid</code> are read the same way. Customer traits, <code>conversion_type</code> values, and <code>xat_</code> passthrough parameters are matched exactly as documented."
    },
    {
      question: "What happens if I send a conversion_type that is not on the list?",
      answer: "The conversion is rejected with an Unknown conversion_type error, unless you also send an <code>event_name</code>. Use one of the documented values such as <code>purchase</code>, <code>lead</code>, or <code>cpa</code>, or send <code>event_name</code> to record a custom event with any name you choose."
    },
    {
      question: "Can I send a conversion without a click_id?",
      answer: "Yes, as long as you send a <code>ref_id</code> or an <code>email</code> instead. AnyTrack uses one of these three values to match the conversion to a session. The <code>click_id</code> gives the most reliable attribution, so use it when you can. See <a href='/docs/external-id-as-click-id'>External ID as Click ID</a> for the alternative match key."
    },
    {
      question: "How many passthrough parameters can I send?",
      answer: "Up to 5 parameters prefixed with <code>xat_</code> are stored on the conversion, with the prefix removed (for example, <code>xat_plan</code> becomes <code>plan</code>). Only parameters with a non-empty value count. If you send more than 5, the first 5 are kept and the rest are dropped. This limit may change."
    }
  ]}
/>

<Cards columns={2}>
  <Card title="Postback URL Integration" href="/docs/custom" icon="fa-plug" iconColor="blue-500">
    <p>Step-by-step setup of the Custom Integration postback URL.</p>
  </Card>
  <Card title="Event Attributes" href="/docs/event-attributes" icon="fa-list-check" iconColor="blue-500">
    <p>The full list of attributes you can send with any AnyTrack event.</p>
  </Card>
  <Card title="Is a Custom Integration Right for You?" href="/docs/custom-integration-fit" icon="fa-circle-question" iconColor="blue-500">
    <p>Decide whether to build a custom integration before you start.</p>
  </Card>
  <Card title="Standard CRM Integrations" href="/docs/standard-crm-integrations" icon="fa-arrows-turn-right" iconColor="blue-500">
    <p>The full CRM-to-Facebook end-to-end workflow.</p>
  </Card>
</Cards>