Pushing Conversion Events

Authentication

All requests must be authenticated with an API Key.

Use the HTTP header Authorization with the API Key, where the API key you created in the MediaQX application.

See Managing API Keys.

Pushing Events

Base URL

The base URL for all API requests is:

https://conversions.app.mediaqx.com

Method

POST

URI

/events

Header

Key	Value
mqx-token	<your-api-key>
Content-Type	application/json

Payload

{
  "identifiers": {
    "email": "string",
    "phone": "string",
    "ext_id": [{
      "provider": "string",
      "key": "string",
      "id": "string"
    }],
    "maid": {
      "idfa": "string",
      "idfv": "string",
      "gps_adid": "string"
    },
    "additional": {}
  },
  "events": {
    "time": "integer",
    "ip": "string",
    "type": "string",
    "additional": {}
  }
}

Payload Parameters

A conversion event shall include the list of identifiers as key-value pairs and detailed information about the event.

Identifiers

The targettable identifier(s) of the user who created the event. The identifiers can be first-party identifiers such as email, phone_number, or third-party identifiers such as maid, crm_id.

You can push your well-known first-party identifiers such as email and phone directly within the identifiers object, or add your third-party identifiers in the ext_id object.

Parameter	Description
email string	Optional. Email address of the user either in raw or hashed format. Trim any leading and trailing spaces. Convert all characters to lowercase. Example: Email address: [e-mail] Normalized format: [e-mail] If hashed, expected SHA256 output: 62a14e44f765419d10fea99367361a727c12365e2520f32218d505ed9aa0f62f
phone string	Optional. The phone number of the user, either raw or hashed format. Remove symbols, letters, and any leading zeros. Phone numbers must include a country code to be used for matching (e.g., the number 1 must precede a phone number in the United States). Always include the country code as part of your customers' phone numbers, even if all of your data is from the same country. Example: Input: US phone number [phone] Normalized format: 16505551212 If hashed, expected SHA256 output: e323ec626319ca94ee8bff2e4c87cf613be6ea19919ed1364124e16807ab3176
ext_id list	Optional. The list of any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs. Example: [{ "provider":"crm, "key": "crm_user_id", "id": "2344" }] [{ "provider":"facebook", "key": "facebook_user_id", "id": "2344a8230cd7d0e9fb4871d3ba8a53d6" }]
maid object	Optional. Your mobile advertiser ID, the advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device. Note: This parameter is for app events only Note: You should add one of the following fields, idfa, gps_adid, idfv. Example: { "idfa": "2344a8230cd7d0e9fb4871d3ba8a53d6" }
additional object	Optional. A map that includes additional business data about the user. Example: { "customer_segment": "gold" }

At least one identifier is needed for the conversion event to be valid.

Events

Detailed information about the event triggered by the user.

Parameter	Description
time integer	Required. A Unix timestamp in seconds indicating when the actual event occurred. The specified time may be earlier than the time you send the event to MediaQX. Example: 1710936269
ip string	Required. The IP address of the client corresponding to the event must be a valid IPV4 address. The ip parameter must never be hashed. No spaces should be included. Always provide the real IP address to ensure accurate matching. Example: IPV4: 168.212.226.204
type string	Required. A standard event name. This field is used to attribute user events after a TV ad is seen. You can define your event types there is no validation for event names. Example: session_start add_to_card page_view
additional object	Optional. A map that includes additional business data about the event. Example: { "basket_amount":00.00, "currency": "USD" }

IP address and timestamp need to be valid for the conversion event to be valid.

IPv6 is not supported for conversion events.

Response Types

Code	Status	Description
200	OK	Successful event response. In sucessfull events, system reflects the request parameters.
403	MQX_TOKEN_MISSING	You need to add mqx-token parameter in the header of your request. To create a valid API key, see Managing API Keys. If you have your mqx-token please see Authentication.
400	MQX_TOKEN_INVALID	Your mqx-token is invalid. You can enable, re-generate your token, or create a new one, see Managing API Keys.
400	INVALID_FORMAT	Your request is invalid. To build a valid request please see Payload Parameters. You can analyze the response to see why your request is invalid. Sample Response: { "detail": [ { "type": "missing", "loc": [ "body", "identifiers" ], "msg": "Field required", "input": { "...": "..." }, "url": "<https://errors.pydantic.dev/2.5/v/missing>" } ] }