Pushing Conversion Events
Last updated
Last updated
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.
The base URL for all API requests is:
POST
/events
mqx-token
<your-api-key>
Content-Type
application/json
A conversion event shall include the list of identifiers as key-value pairs and detailed information about the event.
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.
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: John_Smith@gmail.com Normalized format: john_smith@gmail.com 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 (650)555-1212 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:
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:
additional
object
Optional. A map that includes additional business data about the user.
Example:
At least one identifier is needed for the conversion event to be valid.
Detailed information about the event triggered by the user.
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:
IP address and timestamp need to be valid for the conversion event to be valid.
IPv6 is not supported for conversion events.
OK
Successful event response. In sucessfull events, system reflects the request parameters.
MQX_TOKEN_MISSING
You need to add mqx-token parameter in the header of your request.
MQX_TOKEN_INVALID
INVALID_FORMAT
Sample Response:
To create a valid API key, see .
If you have your mqx-token please see .
Your mqx-token is invalid.
You can enable, re-generate your token, or create a new one, see .
Your request is invalid. To build a valid request please see . You can analyze the response to see why your request is invalid.