For API key setup and audience endpoints, see How to Access and Use Propensity’s API.
What This Is
The Propensity API provides read-only endpoints for exporting accounts, contacts, and signals stored in your workspace. These endpoints return paginated JSON records, including available account and contact attributes, engagement histories, and signal data.
Unlike reporting endpoints, these exports retrieve currently retained source records without applying reporting date filters. Some sources may already contain aggregated metrics, such as impression and click counts.
When to Use This
Use these endpoints when you need to:
- Export workspace data to an external data warehouse or analytics system
- Process account, contact, or signal records in custom applications
- Access stored source-level data rather than summarized reporting results
Where to Find the Export Endpoints
To access the export endpoints in Propensity:
- Log in to your Propensity workspace
- Open Workspace Settings
- Select the Connections tab
- Under Your Data Connections, open the link to your API connections
- On the API Keys page, locate Exporting Accounts, Contacts and Signals
Each endpoint URL includes your workspace API key, which is required to authenticate requests. Keep this key secure and use it only in trusted server-side applications.
Available Export Endpoints
Use the following read-only endpoints to retrieve data currently stored in your workspace. Each request returns a limited page of JSON records that you can process or store in another system.
| Method and Path | Included Data |
|---|---|
GET /export_accounts |
All current workspace accounts, including identifiers, domains, ICP status, stored scores, and CRM keys. Available company enrichment appears under record.company
|
GET /export_contacts |
All currently stored workspace contact documents, including identifiers, aliases, profile fields, company associations, and stored histories. The Contact Engagement report's 90-day warmth filter does not apply |
GET /export_signals |
All retained records from the six signal sources described below, including events, website visits, score snapshots, score contributions, and stored analytics |
These endpoints return stored data rather than generating new reports. The information available depends on which records have been collected and retained for your workspace.
Use the endpoint URL shown on the API Keys page for your environment. You can access your API connections through Workspace Settings → Connections.
Authentication and Parameters
Send your existing workspace API key in the workspace_api_key parameter. Existing workspace and IP access rules apply.
Keep API keys on your server and never expose them in public or client-side code. Because the API key is included in the request URL, ensure that query strings containing credentials are not recorded in application logs, proxy logs, or monitoring tools.
| Parameter | Usage |
|---|---|
workspace_api_key |
Required for every request |
limit |
Optional number of records to return per page, from 1 to 1000. Defaults to 500 |
cursor |
Continuation value returned as next_cursor in the previous response. Reuse it unchanged with the same workspace and endpoint |
schema=declared |
Returns the endpoint's declared data contract without reading export records. Send it without limit or cursor
|
Understanding the cursor
A cursor tells the API where to continue retrieving records. Instead of requesting page numbers, you send the next_cursor value returned by the previous request. This allows you to retrieve large datasets in smaller, manageable batches.
Do not modify or construct cursor values manually.
Important: These exports do not support reporting date filters, page offsets, or incremental watermarks. They return currently retained data without applying reporting filters or using cached report results.
Request Examples
The following examples use https://api.propensity.com as the base URL.
Retrieve the First Page
Replace the placeholder with your workspace API key:
GET https://api.propensity.com/export_accounts?workspace_api_key=YOUR_WORKSPACE_API_KEY&limit=500
This retrieves up to 500 account records from your workspace.
Retrieve the Next Page
If the response includes has_more: true, URL-encode the returned next_cursor and include it in your next request:
GET https://api.propensity.com/export_accounts?workspace_api_key=YOUR_WORKSPACE_API_KEY&limit=500&cursor=RETURNED_CURSOR
Use the same approach with /export_contacts and /export_signals.
Retrieve the Endpoint Contract
To review the declared data contract without retrieving records, use:
GET https://api.propensity.com/export_signals?workspace_api_key=YOUR_WORKSPACE_API_KEY&schema=declared
This returns information about the endpoint's supported parameters, data sources, response structure, and documented behavior.
Response and Pagination
Each successful export request returns a JSON response containing the retrieved records and information about whether additional pages are available.
The response follows the contract propensity.workspace_export.v1, schema version 1.0.0.
Understanding the Response
The main response fields include:
| Field | Description |
|---|---|
data |
Array containing the returned records |
returned_results |
Number of records included in the current response |
limit |
Maximum number of records requested for the page |
source_namespace |
Storage source from which the current records were retrieved |
next_cursor |
Continuation value used to retrieve the next page |
has_more |
Indicates whether more pages remain in the export |
source_exhausted |
Indicates whether the current source has been exhausted |
traversal_complete |
Indicates whether the entire export has finished |
generated_at |
Timestamp when the response was generated |
consistency |
Indicates whether the export uses a frozen snapshot or live data |
historical_capture_complete |
Indicates whether the completeness of historical data capture has been established |
The response also includes contract and schema_version.
Example response
The following simplified example illustrates a signals export page that contains no records but still has additional sources to process. The cursor is a placeholder, not a real continuation value.
{
"contract": "propensity.workspace_export.v1",
"schema_version": "1.0.0",
"data": [],
"returned_results": 0,
"limit": 500,
"source_namespace": "signal_events",
"next_cursor": "RETURNED_CURSOR",
"has_more": true,
"source_exhausted": true,
"traversal_complete": false,
"generated_at": "2026-11-18T12:00:00.000Z",
"consistency": "live_not_frozen",
"historical_capture_complete": null
}In this example, the current source has been exhausted, but the overall export is not complete. Because has_more is true, the next request must use next_cursor to continue.
Understanding Individual Records
Each item in the data array includes:
| Field | Description |
|---|---|
export_id |
Identifier for the exported record within its source |
source_namespace |
Source that contains the record |
record_id |
Original record identifier, which may be a single value or an array of key values |
workspace_id |
Workspace associated with the record |
source_version |
Stored version of the source record |
record |
Original stored data associated with the exported record |
The contents of record vary depending on the export endpoint and source.
For example, account records can include company enrichment data, while contact records can contain profile information and stored engagement histories.
Source versions are represented as strings to preserve large numeric values accurately. Campaign analytics records have a null source_version.
Some contact and campaign analytics values use Extended JSON, a representation that preserves data types such as dates and numbers. When importing these records into another system, preserve these values rather than automatically converting them to plain text.
Retrieve Every Page
To retrieve the complete set of currently retained records:
- Request the first page without a cursor
- Process or save the records returned in
data - If
has_moreistrue, send another request usingnext_cursor - Continue until
has_moreisfalse
Important: Do not stop simply because a page contains fewer records than the requested limit or because data is empty. Signals exports can return an empty page while moving between sources.
The source_exhausted field describes the current source, while traversal_complete describes the entire export.
For repeatable imports, use the combination of (workspace_id, export_id) to identify records when inserting or updating data in your destination system. This helps avoid duplicates when requests are retried or records are retrieved again.
The API does not provide a total population count for these exports.
Signal Sources and Interpretation
The /export_signals endpoint retrieves retained records from six sources:
| Source | Description |
|---|---|
signal_events |
Stored signal events |
website_events_raw |
Retained raw website events |
website_account_visits |
Retained account website visit records |
score_snapshots |
Stored scoring snapshots |
score_contributions |
Stored contributions associated with scoring |
propensity_campaign_analytics |
Retained campaign analytics documents and aggregates |
Understanding the differences between sources
These sources do not all represent the same type of information.
Some contain individual events or website visits. Others contain stored scoring information or aggregated analytics.
For example, a campaign analytics record may contain a counter representing multiple ad impressions. That counter does not mean the API returns a separate record for every impression.
Records can also contain overlapping information across sources. Avoid adding together records from every source as though each represented a unique engagement event.
The API preserves available nested histories, counters, timestamps, URLs, and attribution information. If a source record does not contain attribution information, the export does not generate or infer it.
Consistency and Coverage
These endpoints retrieve data from live storage rather than a frozen snapshot.
The consistency field returns live_not_frozen, meaning that records may change while an export is in progress.
For example, if new activity is recorded after you begin an export, the new data may not appear in the current traversal if it falls behind the cursor. Running the export again can help retrieve changes or additions that were not included.
Historical data coverage
The historical_capture_complete field returns null.
This does not mean the export failed. It means the API cannot certify that every historical event from upstream systems was originally captured.
The endpoints return currently retained records from their supported sources, but they do not guarantee that all historical activity is available.
Deletion tracking
These endpoints do not provide deletion tracking or an incremental synchronization feed.
If you regularly import data into another system, account for the possibility that records may change or no longer appear in later exports.
Errors and Retries
Unlike the audience creation endpoint, these export endpoints use HTTP status codes to indicate request errors.
Always check both the HTTP status and the response body before accepting or processing a page.
| HTTP Status | Meaning and Next Step |
|---|---|
401 |
Missing or invalid workspace authentication. Check the API key and applicable access rules |
405 |
Unsupported HTTP method. Use GET to retrieve export records |
422 |
Invalid limit, cursor, schema request, unsupported parameter, or format. Correct the request and ensure the cursor belongs to the same workspace and endpoint |
503 |
A source is unavailable or a processing capacity limit was reached. Retry the failed request and reduce the page limit if necessary |
When a request fails with 503, no completed page or new cursor is returned.
Retry using the last successfully saved continuation cursor, or restart without a cursor if the first page failed. Use a limited number of retry attempts with increasing delays between attempts.
Recommended approach
Process and save one page at a time, and save its continuation cursor only after successfully handling the returned records. This reduces the risk of skipping data when a request fails.
Start with the default limit of 500 records per page. If a request encounters a capacity error, try a smaller limit.