Measurement

Conversion Event

POST conversion_event

Record a mobile measurement conversion event. The response will indicate Twitter or Twitter Audience Platform (TAP) attribution.

This relates to the GET conversion_attribution endpoint.

Either Twitter, TAP or no attribution will be claimed in the response. The twitter_attribution node will always be present and have a value of null when there is no Twitter attribution (see the example response below). If TAP attribution is claimed a tpn_attribution node will be present and populated accordingly. Please refer to the TAP overview for more information.

There are several optional parameters available to set metadata associated with each conversion event. This metadata has no effect on attribution calculations.

Resource URL

https://ads-api.twitter.com/3/conversion_event

Parameters

Name Description
app_id
required

The unique identifier with the corresponding app store.

Type: int, string

Example: 333903271, com.vine.android
conversion_time
required

The time of the conversion event in an ISO-8601 timestamp format, with milliseconds appended.

Type: string

Example: 2014-05-22T02:38:28.103Z
conversion_type
required

The type of conversion event.

Type: enum

Possible values: PURCHASE, SIGN_UP, INSTALL, RE_ENGAGE, UPDATE, TUTORIAL_COMPLETE, RESERVATION, ADD_TO_CART, ADD_TO_WISHLIST, LOGIN, CHECKOUT_INITIATED, SEARCH, LEVEL_ACHIEVED, ACHIEVEMENT_UNLOCKED, CONTENT_VIEW, SHARE, INVITE, ADDED_PAYMENT_INFO, SPENT_CREDITS, RATED
hashed_device_id
required

The HMAC_SHA-256 hashed IDFA or AdID.

Type: string

Example: ABCD1234XYZ
os_type
required

The OS type for the app.

Type: enum

Possible values: IOS, ANDROID
click_window
optional

The click window for this event in days.

Type: int

Default: 14
Possible values: 1, 7, 14, 30
extra_device_ids
optional

A SHA256 of the SHA1 of the device ID passed in hashed_device_id, plus any additional hashed device IDs.

Type: string

Example: ABCD1234XYZ, DCBA4321XYZ
non_twitter_engagement_time
optional

The time of the last non-twitter engagement prior to the conversion.

Type: string

Example: 2014-05-22T02:38:28.103Z
non_twitter_engagement_type
optional

The type of non-twitter engagement prior to the conversion event.

Type: enum

Possible values: CLICK, VIEW
view_through_window
optional

The view through window for this event in days.

Type: int

Default: 1
Possible values: 0, 1, 7, 14, 30

Example Request

https://ads-api.twitter.com/3/conversion_event?app_id=333903271&os_type=IOS&hashed_device_id=ABCD1234XYZ&conversion_type=INSTALL&conversion_time=2013-04-16T07:00:00.123Z&click_window=14&view_through_window=1

Example Response

{
  "data": {
    "conversion_value_micro": 0,
    "view_through_window": 1,
    "tpn_attribution": null,
    "conversion_time": "2017-01-21T01:14:00.602Z",
    "click_window": 30,
    "limit_ad_tracking": false,
    "event_metadata": null,
    "non_twitter_engagement_type": null,
    "conversion_type": "INSTALL",
    "partner_client_id": "com.appname contact id",
    "app_id": "com.appname",
    "extra_device_ids": null,
    "hashed_device_id": "lke1GZa3AseB343ZcCQq7svfHzLfuSqyYnE+Rf49MOI=",
    "twitter_attribution": {
      "country": "US",
      "engagement_time": "2017-01-21T01:13:00.602Z",
      "engagement_type": "CLICK",
      "attribution_type": "PROMOTED",
      "promoted_properties": {
        "campaign_id": "4ns44",
        "line_item_id": "3x44d",
        "account_id":"18ce11e3egb",
        "line_item_objective": "APP_INSTALLS",
        "campaign_name": null
      },
      "tweet_id": "11434635565377600"
    },
    "os_type": "ANDROID",
    "non_twitter_engagement_time": null
  },
  "request": {
    "params": {
      "version_number": "1",
      "app_id": "com.appname",
      "conversion_type": "INSTALL",
      "os_type": "ANDROID",
      "hashed_device_id": "lke1GZa3AseB343ZcCQq7svfHzLfuSqyYnE+Rf49MOI=",
      "conversion_time": "2017-01-21T01:14:00.602Z",
      "click_window": "30",
      "view_through_window": "1",
      "limit_ad_tracking": "false"
    }
  }
}