All Collections
Universal Data API
How do I get my Custom Conversion data into AdStage through the API?
How do I get my Custom Conversion data into AdStage through the API?
Upload data from your CRM, marketing automation systems, apps, BI tools, and billing systems into AdStage
JD Prater avatar
Written by JD Prater
Updated over a week ago

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 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:


  • 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": ""

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. 


{"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:


  • 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


  • 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 cross-network Report widget, then select your custom conversion metric from the 'Field' dropdown. 


Custom Conversions will also appear in Automate where you can build Alerts, Rules or other complex automations based on your Custom Conversion data.

Did this answer your question?