How to Use and Rotate Propensity's API

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.

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

1. 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.

2. Base URL and Versioning

Base URL:

All requests should be made to the following base URL:

https://api.propensity.com/

3. Request Structure and Conventions

Headers

All requests must include: workspace_api_key

Content-Type: text/html

4. API Endpoints

4.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”
  }
}

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

Rotating Your API Keys

Rotate your API keys if:

• Your keys were exposed or may have been compromised
• Your organization's security policy requires periodic key rotation
• A team member who had access to your API keys has left the organization
• You shared your keys with a third party temporarily and want to revoke that access
• You suspect unauthorized access to your workspace

Before you begin, confirm that all teams and integrations using your current API endpoints are ready to switch to new URLs. Once you confirm the rotation, your previous endpoints stop working immediately and there is no way to reverse the action.

1. On the API Keys page, click Rotate API Keys
2. Review the warning in the confirmation dialog
3. Click Confirm Key Rotation. Your previous endpoint URLs are disabled immediately
4. For each connection in the list, click Show API Key or Copy to retrieve the new endpoint URL
5. Update all active integrations with the new endpoint URLs

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.