Use the Basis Platform API

The Basis Platform API is an easy-to-use RESTful API that lets you connect to Basis and retrieve campaign planning and delivery data. Learn how to authenticate to and interact with the Basis Platform API endpoints in our API documentation: https://api.basis.net/docs/

You can gather data for delivery metrics and conversions using the following Basis Platform API endpoints:

• /v1/conversions
• /v1/conversions/{id}
• /v1/stats/{scope}

Available Conversions Metrics

The following table shows which conversions metrics are currently available in the API.

Find Conversion Details for a Client or Campaign

To find conversion details for a specific client or campaign, use the /v1/stats/{scope} endpoint with daily_by_conversion as the scope to retrieve all conversions and filter by client_id or campaign_id.

• GET /v1/stats/daily_by_conversion?client_id={id}

• GET /v1/stats/daily_by_conversion?campaign_id={id}

The endpoint provides the following conversions metrics:

• Conversion ID
• CTC
• CTC Revenue
• VTC
• Total Conversions
• Total Conversions Revenue

Sample Requests: Make a GET call to the /v1/stats/{scope} endpoint.

curl -X GET "https://api.basis.net/v1/stats/daily_by_conversion?client_id=b2086aa6-7202-4970-b1c1-a2cac11034fc" -H "accept: application/json" -H "Authorization: Bearer <access_token>"

curl -X GET "https://api.basis.net/v1/stats/daily_by_conversion?campaign_id=01681839-7363-47fa-ab96-ee4f9dc75a2f" -H "accept: application/json" -H "Authorization: Bearer <access_token>"

Sample Response: The following sample response is truncated.

{
  "metadata": {
    "cursor": "NjIyMzc5ZGItNTY1OS00ZWM4LWE0OGYtYjg1ZDg5ZDMwMWNlLDM5MTc0ZWFkLTQ2YTctNDkxNS04M2NiLTJhODhlMmZjNjZjMiw4OTc2NzFiYS0zNTYwLTQ0MDktYWU5Mi1mNTQ3N2JkOWVmNGMsNDg2NTQwOSw3ZDIzZWQ0YzZmNjQ2YTU1YzdjYWNjNGQzZDRiYjRhZWQzMzA0ODZiLDIwMjEtMTItMTU=",
    "page_size": 700,
    "total": 3737
  },
  "data": [
    {
      "line_item_id": "0a31998f-c5b7-4e2d-9a0b-7c591c47309d",
      "line_item_lineage_id": eae82dd5-28a2-4af5-b6e2-c45750a13f1b",
      "delivery_source_id": "6c50053d-7f5d-417b-9f48-16f7fd8a8045",
      "creative_id": "3340e6a7-28ed-497c-81bc-24ee160ac758",
      "external_ad_ref": "118966570992",
      "conversion_id": "ab7ba26d51324a23a215ee90076fae93",
      "delivered_date": "2021-09-15",
      "conversion_metrics": {
        "click_conversions": 2,
        "click_conversion_revenue": 10,
        "view_conversions": 3,
        "view_conversion_revenue": 5,
        "total_conversions": 5,
        "total_conversion_revenue": 15
      }
    }
  ]
}

For each conversion that is returned in the response, use the conversions endpoint to find the following conversion metrics:

• Conversion ID
• Name
• Revenue
• Channel Source

Sample Request: Make a GET call to the /v1/conversions endpoint.

curl -X GET "https://api.basis.net/v1/conversions/ab7ba26d51324a23a215ee90076fae93" -H "accept: application/json" -H "Authorization: Bearer <access_token>"

Sample Response: The following sample is truncated.

{
  "data": {
    "conversion_id": "ab7ba26d51324a23a215ee90076fae93",
    "name": "Apply Now",
    "external_source": "adwords",
    "external_ref": "123456789"
  }
}

Find Conversion Details for a Tactic

There currently isn't an endpoint for retrieving tactic conversions. You can use the following steps to find conversion details for tactics in the API.

1. Use the v1/delivery_sources endpoint to retrieve all delivery sources, or use the external source and external ID parameters to filter a specific delivery source (v1/delivery_sources?external_source =dsp&external_id=<tacticId>).

   Sample Request: Make a GET call to the v1/delivery_sources endpoint.

   Copy

   curl -X GET "https://api.basis.net/v1/delivery_sources" -H "accept: application/json" -H "Authorization: Bearer <access_token>"

   Sample Response: The following sample is truncated.

   Copy

   {
     "metadata": {
       "cursor": "MjczZWVkMzItYTBhZi00NjRlLWExZDYtYjRhM2Y1MmMwZWQ2",
       "page_size": 100,
       "total": 613
     },
     "data": [
       {
         "id": "0933b9b1-af83-4e23-9ea6-991c048fee33",
         "external_source": "dsp",
         "external_id": "1689263",
         "name": "Tactic263",
         "size": null
        },
        {
         "id": "273eed32-a0af-464e-a1d6-b4a3f52c0ed6",
         "external_source": "dsp",
         "external_id": "1388311",
         "name": "Tactic789",
         "size": null
       }
     ]
   }

2. Call the stats endpoint using the daily_by_conversion scope and the delivery source ID retrieved from step 1 as the filter parameter (/v1/stats/{scope}?delivery_source_id=<deliverySourceId>).

   Sample Request: Make a GET call on the /v1/stats/{scope} endpoint.

   Copy

   curl -X GET "https://api.basis.net/v1/stats/daily_by_conversion?delivery_source_id=273eed32-a0af-464e-a1d6-b4a3f52c0ed6" -H "accept: application/json" -H "Authorization: Bearer <access_token>"

   Sample Response: The following sample response is truncated.

   Copy

   {
     "metadata": {
       "cursor": "MGIxMDcxMDUtZjFmNC00ZjcyLTg3ZjYtN2VhZDBkMzg0N2JmLDFmZTQ2OTBhLTg2NTYtNGRkOC1iMzczLTYzZmNjNTU5ODVjYSxiNjJlMjU2NS1kYTAzLTQyODAtODdlNC0zOWM0ZWVlZWI1MGUsNDk3MTYzMzQ4LDZkNmU3YTYyZWEzMmM0ZmUwZWEyMTUzMGQ5NDA2MzhkN2U2ZGQxMTAsMjAyMS0wNi0wNQ==",
       "page_size": 700,
       "total": 7189
     },
     "data": [
       {
           "line_item_id": "c507e300-a943-4a20-a29b-e5424ffbcc4c",
         "line_item_lineage_id": "0b107105-f1f4-4f72-87f6-7ead0d3847bf",
         "delivery_source_id": "077c57f0-57fc-4d32-8e9f-6ee38bcef1c5",
         "creative_id": "c7504293-dabd-48b5-86ab-6e06c701ad37",
         "external_ad_ref": "497163867",
         "conversion_id": "6d6e7a62ea32c4fe0ea21530d940638d7e6dd110",
         "delivered_date": "2021-06-03",
         "conversion_metrics": {
           "click_conversions": 1,
           "click_conversion_revenue": 0,
           "view_conversions": 0,
           "view_conversion_revenue": 0,
           "total_conversions": 1,
           "total_conversion_revenue": 0
         }
       },
       {
         "line_item_id": "c507e300-a943-4a20-a29b-e5424ffbcc4c",
         "line_item_lineage_id": "0b107105-f1f4-4f72-87f6-7ead0d3847bf",
         "delivery_source_id": "0933b9b1-af83-4e23-9ea6-991c048fee33",
         "creative_id": "b62e2565-da03-4280-87e4-39c4eeeeb50e",
         "external_ad_ref": "497163348",
         "conversion_id": "bb8ddc2f44204524844a9398c5cb3105",
         "delivered_date": "2021-06-05",
         "conversion_metrics": {
           "click_conversions": 1,
           "click_conversion_revenue": 0,                    
           "view_conversions": 0,
           "view_conversion_revenue": 0,
           "total_conversions": 1,
           "total_conversion_revenue": 0
         }
       }
     ]
   }

3. Retrieve conversion details for each conversion ID that is returned in the response. Use the conversions endpoint to find the following conversion metrics:

   • Conversion ID

   • Name

   • Revenue

   • Channel Source

   Sample Request: Make a GET call to the /v1/conversions endpoint with the conversion IDs retrieved from step 2.

   Copy

   curl -X GET "https://api.basis.net/v1/conversions/bb8ddc2f44204524844a9398c5cb3105" -H "accept: application/json" -H "Authorization: Bearer <access_token>"
                       

   Sample Response: The following sample response is truncated.

   Copy

   {
     "data": {
     "conversion_id": "ab7ba26d51324a23a215ee90076fae93",
     "name": "Get Insurance Quote",
     "external_source": "dsp",
     "external_ref": "519729693"
     }
   }