AdStage integrates with many networks to bring the data you need into AdStage automatically. If you need to get outside data into AdStage, like CRM leads and opportunities, there are a handful of different ways. If you have access to developer resources to pipe conversion data in, this article is the place.
If you are looking to automatically join Salesforce leads/opps or Google Analytics goals back to the paid data the conversions came from, AdStage Join is your best bet. Alternatively, if you want to drop in a CSV from another CRM or outside source to join data, Join - Upload Data is the technique to use.
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 through the AdStage API.
--------------------------------------------------------------------------------------------------------------------------
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, you can use a Build Report API call as a guide.
The IDs are stored in the metadata for a metrics row as "entity_id"
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?
Report
After you've successfully uploaded your custom conversions to the AdStage API, simply create or edit any cross-network Report widget, then select your custom conversion metric from the 'Field' dropdown.
Automate
Custom Conversions will also appear in Automate where you can build Alerts, Rules or other complex automations based on your Custom Conversion data.
