Skip to main content

How to Use Propensity's API

Updated

This article provides a technical overview of Propensity’s API, including how to authenticate, send requests, and interact with two key endpoints. Use this guide to enhance your ABM strategy by integrating Propensity’s API into your existing workflows and tools.

 

1. Overview

Propensity’s API allows customers to programmatically interact with their ABM campaigns and underlying engagement data. You can use it to:

  • Retrieve lists of contacts/accounts who have engaged with your ABM campaigns and / or website
  • Integrate Propensity with your CRM or other marketing automation tools
  • Dynamically build ABM campaigns
  • Dynamically build audiences from your 3rd party list sources to be used in your ABM Campaigns

 

2. Authentication

Getting Your API Key

To get your API key:

  1. Log into Propensity
  2. Click on your profile in the top right
  3. Go to Workspace Settings
  4. Click on the Connections Tab
  5. Under the Your Data Connections section, find the link to access your API connections
  6. Copy the API key based on your specific use case

Your API key is sensitive information—keep it secure. Never share it publicly or include it in client-side code like browsers or mobile apps. Instead, load it securely from environment variables or a server-side key management system.

 

3. Base URL and Versioning

Base URL:

All requests should be made to the following base URL:

https://api.propensity.com/

 

4. Request Structure and Conventions

Headers

All requests must include: workspace_api_key

Content-Type: text/html

 

5. API Endpoints

5.1 Create an audience of contacts

  • Endpoint: POST /create_contact_audience
     
  • Purpose: Create an audience of accounts and contacts in Propensity.  At least one combination of the following parameters are required for each contact:
    • email
    • linkedin_url
    • first_name, last_name, company_name
    • first_name, last_name, website
       

Request Body

{ contacts: 
  [
    { 
        first_name: “string”,
        last_name: “string”,
        company_name: “string”,
        website: “string”,
        email: “string”,
        linkedin_url: “string”
    }
  ]
}

Response

{ 
  results: 
    {
      error: boolean
      message: “string”
  }
}

 

5.2 Create an audience of accounts

  • Endpoint: POST /create_account_audience
     
  • Purpose: Create an audience of accounts in Propensity.  
     

Request Body

{ accounts: 
  [
    { 
        website: “string”
    }
  ]
}

Response

{ 
  results: 
    {
      error: boolean
      message: “string”
  }
}

 

Other API Keys:

Name
Description
ABM Campaign SummarySummary description of all of your unarchived ABM Campaigns.
ABM ROI AnalyticsShows day over day ROI of your ABM campaigns.
Account EngagementShows engagement metrics for each account in your ABM campaigns.
Asset AnalyticsShows asset level performance for each asset in your ABM campaigns.
Campaign PacingShows pacing performance of your ABM campaigns.
Contact EngagementShows engagement metrics for each contact in your ABM campaigns.
Daily ABM ActivitiesDetails of all daily activities in your ABM Campaign.
Daily Programmatic SpendDaily breakdown of your impressions and spend by programmatic ad channel.
Website AnalyticsShows website analytics for all website visitors in your ICP.

 

6. Best Practices

  • Keep your API key private and never expose it in public code.
     
  • Store your API key securely using environment variables.
     
  • Use query parameters to filter and limit your data requests.
     
  • Always check for error: false in the API response.
     
  • Minimize unnecessary calls to stay efficient and within rate limits.

 

Need Help?

If you're still unsure on how to use Propensity’s API or are seeing errors when integrating, please reach out to Propensity Support via the live chat or success@propensity.com. 

Related articles