twitter_attribution
node will always be present and have a value of null
when there is no X 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.
https://ads-api.x.com/12/conversion_event
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 Note: click_window must be greater than or equal to view_through_windowDefault: 14 Possible values: 1 , 7 , 14 , 30 |
device_ip_address optional | IPv4 or IPv6 address of the device when the conversion event happened. Type: string Example: 192.133.78.1 |
level optional | A level associated with this event. Type: int Example: 2 |
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 |
number_items optional | Number of items associated with this event. Type: int Example: 2 |
price_currency optional | Expected to be an ISO 4217 code to indicate the currency associated with this event. Type: String Examples: EUR ,USD ,JPY |
price_micro optional | A price amount associated to this event in micro. Type: int Example: 123450000 |
user_payment_info optional | A boolean value to indicate if the user’s payment information is stored in the app associated with this event. Type: bool Possible values: true or false |
view_through_window optional | The view through window for this event in days. Note: click_window must be greater than or equal to view_through_window.Type: int Default: 1 Possible values: 0 , 1 , 7 , 14 , 30 |
https://ads-api.x.com/12/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
https://ads-api.x.com/12/accounts/:account_id/app_event_tags
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
app_event_tag_ids optional | Scope the response to just the desired app event tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: jhp |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags?app_event_tag_ids=jhp
https://ads-api.x.com/12/accounts/:account_id/app_event_tags/:app_event_tag_id
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
app_event_tag_id required | A reference to the app event tag you are operating with in the request. Type: string Example: jhp |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags/jhp
https://ads-api.x.com/12/accounts/:account_id/app_event_tags
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
app_store_identifier required | The app store identifier. Type: string Example: com.twitter.android |
conversion_type required | The type of conversion event. Type: enum Possible values: ACHIEVEMENT_UNLOCKED , ADDED_PAYMENT_INFO , ADD_TO_CART , ADD_TO_WISHLIST , CHECKOUT_INITIATED , CONTENT_VIEW , INSTALL , INVITE , LEVEL_ACHIEVED , LOGIN , PURCHASE , RATED , RESERVATION , RE_ENGAGE , SEARCH , SHARE , SIGN_UP , SPENT_CREDITS , TUTORIAL_COMPLETE , UPDATE |
os_type required | The OS type for the app. Type: enum Possible values: IOS , ANDROID |
provider_app_event_id required | The ID of the conversion tag on provider’s site. Type: string Example: provider_tag_j5394 |
provider_app_event_name required | The name of the conversion tag on provider’s site. Type: string Example: provider_name_a4382 |
deep_link_scheme optional | Specify the deep link URI for the app associated with this tag. Type: string Example: twitter:// |
post_engagement_attribution_window optional | The post-engagement attribution window for these events. Type: int Default: 30 Possible values: 1 , 7 , 14 , 30 |
post_view_attribution_window optional | The post-view attribution window for these events. Type: int Default: 1 Possible values: 0 , 1 , 7 , 14 , 30 |
retargeting_enabled optional | Specify if retargeting should be enabled for this app event tag. Type: boolean Default: true Possible values: true , false |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags?app_store_identifier=com.twitter.android&os_type=ANDROID&conversion_type=PURCHASE&provider_app_event_id=abc123&provider_app_event_name=test-tag
https://ads-api.x.com/12/accounts/:account_id/app_event_tags/:id
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
id required | A reference to the app event tag you are operating with in the request. Type: string Example: jhp |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags/jhp
https://ads-api.x.com/12/accounts/:account_id/app_lists
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
app_list_ids optional | Scope the response to just the desired app lists by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: wm7x |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/app_lists?app_list_ids=wm7x
https://ads-api.x.com/12/accounts/:account_id/app_lists/:app_list_id
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
app_list_id required | A reference to the app list you are operating with in the request. Type: string Example: 28ukf |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/app_lists/28ukf
app_list
associated with the current account.
Currently there is a limit of 100 app_list
objects per account_id
and 500 apps per app_list
.
https://ads-api.x.com/12/accounts/:account_id/app_lists
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
app_store_identifiers required | The app store identifiers to include in the app_list Type: string Example: com.twitter.android |
name required | The name you will assign to the app_list Type: string Example: My First App List |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/app_lists?name=app list&app_store_identifiers=com.twitter.android
https://ads-api.x.com/12/accounts/:account_id/app_lists/:app_list_id
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
app_list_id required | A reference to the app list you are operating with in the request. Type: string Example: 28ukf |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/app_lists/28ukf
https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
ids optional | Scope the response to just the desired configurations by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 25n |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/11/accounts/18ce54d4x5t/app_event_provider_configurations?ids=25n
https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations/:id
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
id required | A reference to the app event provider configuration you are operating with in the request. Type: string Example: 25n |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/11/accounts/18ce54d4x5t/app_event_provider_configurations/25n
https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
provider_advertiser_id required | The advertiser’s identifier from the provider’s site Type: string Example: client1 |
POST https://ads-api.x.com/11/accounts/18ce54d4x5t/app_event_provider_configurations?provider_advertiser_id=client1
https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations/:id
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
id required | A reference to the app event provider configuration you are operating with in the request. Type: string Example: e5g |
DELETE https://ads-api.x.com/11/accounts/18ce54d4x5t/app_event_provider_configurations/e5g
twitter_attribution
node will always be present and have a value of null
when there is no X attribution and be populated as seen in 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.
https://ads-api.x.com/12/conversion_attribution
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: ACHIEVEMENT_UNLOCKED , ADDED_PAYMENT_INFO , ADD_TO_CART , ADD_TO_WISHLIST , CHECKOUT_INITIATED , CONTENT_VIEW , INSTALL , INVITE , LEVEL_ACHIEVED , LOGIN , PURCHASE , RATED , RESERVATION , RE_ENGAGE , SEARCH , SHARE , SIGN_UP , SPENT_CREDITS , TUTORIAL_COMPLETE , UPDATE |
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 |
GET https://ads-api.x.com/12/conversion_attribution?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=0