Advice and answers from the AdStage Support Team

AdStage Universal Data API

Get a full view of the ads driving the most value, down to actual revenue and return on ad spend.

Directly compare ad performance data with your CRM, marketing automation tools, billing systems or any other third party data using the AdStage API. 

Below is a step-by-step guide to accessing Custom Conversion data in AdStage.
--------------------------------------------------------------------------------------------------------------------------

Getting Started with Custom Conversions

Step 1: Sign up for AdStage API Program 

Please contact our Customer Success team at support@adstage.io to gain AdStage API access. 

--------------------------------------------------------------------------------------------------------------------------

Step 2: Get Your Personalized Tokens and Credentials

After you email our Customer Success team, one of our AdStage specialists will provide you with a token, user ID, and organization ID. You will need these credentials to pass through 3rd party data into AdStage. 

--------------------------------------------------------------------------------------------------------------------------

Step 3: Create and Name Your Conversion Columns

In this step, you're telling AdStage what you would like to name your column for a specific custom conversion. Ideally this should only be done once.

You must first create a metric descriptor to name you column. Send a POST to /api/organizations/:organization_id/metric_descriptors to create a metric descriptor and get a name, where :organization_id is your id.

After that, a link will be provided in the response that tells you the url to upload data to, with the descriptor id filled in at the appropriate place.

Step 3 Request:

Parmeters:

  • organization_id: your organization id
POST /api/organizations/:organization_id/metric_descriptors
Authorization: Bearer <your adstage token>
Content-Type: application/json
{
  "name": "Sales Leads: A+",
  "short_name": "A+ Leads",
  "tooltip": "Leads scored A+ in Salesforce"
}

Step 3 Response:

{
  "id": "custom_conversions:14:conversions",
  "category": "CUSTOM_CONVERSION",
  "type": "METRIC",
  "name": "Sales Leads: A+",
  "short_name": "A+ Leads",
  "tooltip": "Leads scored A+ in Salesforce",
  "default_sort_order": "DESC",
  "format": "DEFAULT",
  "_links": {
    "adstage:custom_conversion_upload": {
      "href": "https://platform.adstage.io/api/organizations/40/metric_descriptors/14/conversions"
    }
  }
}

For example: I want to see a column with the number of "Sales Leads: A+"
and a 2nd column containing the number of demo requests from my landing page. So, I will need to create 2 metric description one titled 'Sales Leads: A+' and another titled 'Demos Converted'.
--------------------------------------------------------------------------------------------------------------------------

Step 4: Find Your Account, Campaign, Ad Sets/ Ad Groups, and Ad IDs

Get campaign, ad groups, ads, and keyword ids from the native network or if you use UTMs, extract the IDs from there.

Note: AdStage will only pull in the custom conversion data that have an attribution key. The attribution key is assigned by identifying individual account element's ID (account, campaign, ad group/ad set, or ad ID)
--------------------------------------------------------------------------------------------------------------------------

Step 5: Convert Attribution, IDs, and Values into AdStage Conversion Data Format (JSON)

To find valid AdStage IDs, use the AdStage Ads List Query Sample as a guide. 

  • The IDs are stored as "campaign_uri", "ad_uri", "account_uri", "ad_group_uri"

Each conversion will have at least 2 keys:

1 -  "timestamp" key 

  • The time the conversion data was collected.

2 - "attribution" key 

  • How much weight you want to give an individual account, campaign, ad group/ad set, or ad per conversion. 
  • By default, you should use 1, but if you want to do custom multi touch attribution models you can use partial values or multipliers. 
  • If you want to roll up values from, for example campaigns, to their account, you must also include attribution for the account in the attribution map.  

3 -  "value" key (optional)

  • These are used to compute Return on Ad Spend and total conversion value.
  • "value" will be multiplied by the weight to determine the conversion value. 

Example

{"timestamp": "2016-11-11T06:00Z", "value": 35.01, "attribution": {"/network/adwords/campaign/143365350": 1, "/network/adwords/account/143365350": 1}}

--------------------------------------------------------------------------------------------------------------------------

Step 6: Upload Custom Conversions

To upload custom conversions, POST to the following URL:

/api/organizations/:organization_id/metric_descriptors/:descriptor_id/conversions.

  • Note: We've already seen this URL👆 in the Step 3: Request 

Next, fill in the metric descriptor (name) ID from Step 1. Then POST data in JSON format to this endpoint with a "conversions" key and a "date_range" key.

Step 6 Request

Parmeters:

  • organization_id: your organization id
  • descriptor_id: the id for the custom descriptor from step 1 - in the example, this is "14".
POST /api/organizations/:organization_id/metric_descriptors/:descriptor_id/conversions
Authorization: Bearer <your adstage token>
Content-Type: application/json
{
  "conversions": [
      {"timestamp": "2016-11-11T06:00Z", "value": 35.0, "attribution": {"/network/adwords/campaign/143365350": 1, "/network/adwords/account/143365350": 1}},
      {"timestamp": "2016-11-11T07:00Z", "value": 41.25, "attribution": {"/network/adwords/campaign/143365350": 0.5, "/network/adwords/campaign/143365350": 0.5}},
      {"timestamp": "2016-11-11T07:30Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-11T08:00Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-11T08:40Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-12T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-13T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-14T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-15T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-16T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}},
      {"timestamp": "2016-11-17T06:02Z", "attribution": {"/network/adwords/campaign/143365350": 1}}
   ],
   "date_range": "2016-11-11..2106-11-17"
}

--------------------------------------------------------------------------------------------------------------------------

Where Can I See My Custom Conversions?

After you've successfully uploaded your custom conversions to the AdStage API, simply create or edit any Report widget, then select your custom conversion metric from the 'Field' dropdown. 

Did this answer your question?