How to Access and Use Propensity's API

What This Is

The Propensity API allows you to programmatically interact with your ABM campaigns and engagement data. Use it to create and update audiences, retrieve contact and account engagement data, and integrate Propensity with your CRM or other marketing automation tools.

When to Use This

Use the Propensity API when you need to:

• Create or update audiences programmatically from third-party list sources
• Retrieve contact or account engagement data from your ABM campaigns
• Integrate Propensity with your CRM or marketing automation tools

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.

Base URL

All requests should be made to:

https://api.propensity.com/

Creating an Audience

Endpoint: POST https://api.propensity.com/create_audience?workspace_api_key={{user_api_key}}

To create a new audience, send a request without an audience_id. The API returns an audience_id in the response, save this ID if you plan to update the audience later.

Example request:

{
  "user_api_key": "YOUR_API_KEY",
  "audience_name": "Enterprise SaaS Buyers - Q3",
  "minimum_propensity_score": 60,
  "maximum_propensity_score": 100,
  "keywords": ["cloud migration", "devops automation"],
  "negative_keywords": ["free trial"],
  "target_country": ["United States", "Canada"],
  "target_industry": ["Software", "Financial Services"],
  "using_intent_data": true
}

Updating an Audience

To update an existing audience, include the audience_id returned when the audience was originally created. If you only update audience_name, the audience's underlying data is not reprocessed. If you change any other field, the audience will be re-enriched.

Example request:

{
  "user_api_key": "YOUR_API_KEY",
  "audience_id": "AUDIENCE_ID_FROM_CREATE_RESPONSE",
  "audience_name": "Enterprise SaaS Buyers - Q3",
  "websites": ["examplecompany.com"]
}

Field Reference for creating and updating audiences 

Core fields

Targeting & scoring

List fields (send each as an array of strings)

Date fields

Funding amount fields

Reading the Response

The endpoint always returns HTTP 200, regardless of success or failure. Always check the response body to confirm whether your request went through:

{
  "error": false,
  "message": "success",
  "audience_id": "a0B..."
}

• If audience_id is populated, your audience was created or updated successfully.
• If audience_id is empty (""), the request did not go through. The most common cause is an invalid API key, double-check your key and try again.

Available Endpoints

In addition to the audience creation endpoint, Propensity provides read-only endpoints for reporting and analytics. Access these from the API Keys screen in your workspace settings.

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.
• Always check the response body rather than the HTTP status code to confirm success.
• Minimize unnecessary API calls to stay efficient and within rate limits.

Important Notes

• The endpoint always returns HTTP 200, do not rely on the status code alone to confirm success. Always check audience_id in the response body.
• When updating an audience, omitted fields may be cleared rather than left unchanged, depending on the field. Include all fields you want to keep in every update request.