Conversion API

Use this endpoint to submit events from a server to the AppLovin Conversions API.

Request format

To submit one or more events to the AppLovin Event API, send an HTTP POST request to https://b.applovin.com/v1/event.

Authentication

Your requests must include this HTTP header:

Header name	Value
`Authorization`	Your API Access Token

Query parameters

Name	Type	Required?	Description
`pixel_id`	string	true	Your Pixel ID

Response codes

Response code	Description
200	All events processed successfully.
400	There is an error with your request. The API dropped this batch of events.
401	Authentication failed.

POST payload

The POST payload of your HTTP request describes the event or events that you submit:

Name	Type	Required?	Description
`events`	`ServerEvent[]`	true	List of events to submit. All events must be valid. Any invalid event will fail the batch. The maximum batch size is 100 events.

The `ServerEvent` object

Name	Type	Required?	Description
`data`	`EventData[]`	true	The data for this event.
`dedupe_id`	string	true	A unique identifier for this event. This is used for de-duplication. See Deduplicating events.
`event_source_url`	string	true	The complete URL where the event occurred (e.g. `https://example.com/product?product_name=widget`).
`event_time`	number	true	The current Unix epoch time in milliseconds.
`name`	string	true	The name of this event. See Axon Pixel events and objects for available events.
`user_data`	`UserData`	true	User data to help identify the user who performed the event.
`measurement_partner_data`	`MeasurementData`	false	Measurement data to inform how much credit is given to AppLovin for the event.

The `EventData` object

See Axon Pixel events and objects for the structures of the various EventData objects.

There is also an optional app_open event. Trigger this event when a user starts the app. There is no data object for this event.

The `UserData` object

Name	Type	Required?	Description
`aleid`	string	true	See Sending `aleid` for more details.
`client_ip_address`	string	true	IP address (without any spaces) of the browser corresponding to the event. You can use either an IPv4 or an IPv6 address. However, the user’s IPv4 address is typically more stable and changes less frequently than the IPv6 address, and so if you use the IPv4 address you can expect more accurate targeting and attribution.
`client_user_agent`	string	true	User Agent of the device/browser
`esi`	string	true	Source of the event: Was it on `app` or `web` that this event happened?
`alart`	string	true^*	Set as `alart` as a query parameter. ^*See Sending User Identifiers for more details.
`axwrt`	string	true^*	Set as `axwrt` in the Axon Pixel. ^*See Sending User Identifiers for more details.
`client_id`	string	true^*	A stable first-party user identifier. ^*See Sending User Identifiers for more details.
`email`	string	true^*	The customer email address (can come in SHA-256 hash). ^*See Sending User Identifiers for more details.
`phone`	string	true^*	The customer phone number (can come in SHA-256 hash). ^*See Sending User Identifiers for more details.
`user_id`	string	true^*	A unique customer identifier. ^*See Sending User Identifiers for more details.
`ifa`	string		The user’s identifier for advertisers (`idfa` or `gaid`)
`idfv`	string		The user’s identifier for vendors
`os`	string		The user’s operating system: `android`, `desktop_os`, or `ios`
`country_code`	string	false	the user’s ISO 3166 billing country code
`sid`	string	false	Session ID
`zip`	string	false	The user’s billing zip code. Use only the first five digits for U.S. zip codes.

The `MeasurementData` object

Name	Type	Required?	Description
`accounting_mode`	string	true	Either `CASH` or `ACCRUAL`
`attribution_model`	string	true	One of `LAST_CLICK`, `FIRST_CLICK`, `LINEAR`, `TIME_DECAY`, `CUSTOM_MULTI_TOUCH`, `LAST_NON_DIRECT_TOUCH`, `CLICKS_AND_VIEWS_ENHANCED`, or `ANY_CLICK`
`attribution_share`	number	true	A number between 0 and 1 that represents how much credit AppLovin gets for the event, based on the given attribution model and lookback
`is_claimable`	boolean	true	A flag that indicates whether AppLovin drove the event
`attribution_lookback_window_hours`	number	false	How far in the past a touchpoint can occur to gain credit for the conversion, in hours. Leave this empty for infinite lookback.
`campaign_id`	string	false	AppLovin’s campaign ID
`creative_set_id`	string	false	AppLovin’s creative set ID (also known as adset ID)
`first_purchase_ts`	number	false	The epoch timestamp, in milliseconds, indicating when the customer first made a purchase with the advertiser.
`first_visit_ts`	number	false	The epoch timestamp, in milliseconds, indicating when the customer first visited the advertiser.
`is_new_customer`	boolean	false	Indicates whether or not the customer has made a purchase with the advertiser before
`is_new_visitor`	boolean	false	Indicates whether or not the customer has visited the advertiser before
`last_purchase_ts`	number	false	The epoch timestamp, in milliseconds, indicating when the customer last made a purchase with the advertiser.
`last_visit_ts`	number	false	The epoch timestamp, in milliseconds, indicating when the customer last visited the advertiser.

Sending `aleid`

aleid is a query parameter that AppLovin adds to website URLs after a user clicks an AppLovin ad. If this query parameter is present, the click resulted from an AppLovin ad. To send the aleid to this API, you can do one of the following:

If you have the AXON Pixel installed on your site, the AXON Pixel automatically sets the cookie _axeid when it sees the aleid query parameter.
When you see that the aleid URL query parameter is present, retrieve its value. When your server sees the aleid query parameter, read the parameter server-side AppLovin recommends that you then set this as an HTTP cookie on your site with the name _axeid. Set this cookie to have a one-year expiration time.

Whichever method you use, when you see such a cookie, read its value and then send it in your Axon Server to Server API request as the value of the aleid query parameter.

Sending user identifiers

AppLovin requires that you send at least one of the following fields:

Field	Explanation
`alart`	For App users, when you see that the `alart` URL query parameter is present, retrieve its value.
`axwrt`	If you have the AXON Pixel installed on your site, the AXON pixel automatically sets the cookie `_axwrt`.
`client_id`	If you do not have the AXON Pixel installed on your site, pass another stable first-party cookie you store to identify visitors. It should be globally unique and stay the same across browsing sessions of the user.
`email`
`phone`
`user_id`

Example payload

"events" : [
  {
    "event_time": 1741784485001,
    "event_source_url": "https://applovin.com",
    "name": "purchase",
    "user_data": {
      "client_ip_address": "172.59.8.172",
      "client_user_agent": "chrome/123.456 android mobile",
      "aleid": "«aleid-query-param»",
      "axwrt": "«axwrt-cookie-value»",
	   "user_id": "«user-identifier»",
      "phone": "+1123456789",
      "email": "user@example.com",
      "client_id": "«first-party-identifier»",
      "sid": "«sid»",
      "ifa": "«idfa»",
      "idfv": "«idfv»",
      "os": "macos",
      "esi": "web",
	   "zip": "12345",
      "country_code": "US"
    },
    "measurement_partner_data": {
      "is_claimable": true,
      "attribution_model": "LAST_CLICK",
      "attribution_lookback_window_hours": 24,
      "attribution_share": 0.5,
      "accounting_mode": "ACCRUAL",
      "campaign_id": "456",
      "creative_set_id": "789",
      "is_new_customer": false,
      "last_purchase_ts": null,
      "is_new_visitor": true,
      "last_visit_ts": 1
    },
    "data": {
      "user_id": "«user-identifier»",
      "currency": "USD",
      "value": 30,
      "transaction_id": "«transaction-identifier»",
      "shipping": 5.99,
      "tax": 6,
      "items": [
        {
          "item_variant_id": "«item-variant-identifier»",
          "item_id": "«item-identifier»",
          "item_name": "«item-name»",
          "affiliation": "«affiliation»",
          "item_brand": "«item-brand»",
          "item_category": "«first-item-category»",
          "item_category_id": 604,
          "item_category2": "«second-item-category»",
          "image_url": "«image-URL»",
          "price": 15,
          "discount": 10,
          "quantity": 2
        }
      ]
    }
  }
]

Was this article helpful?

Asset Reporting API

Conversion API for Lead Generation