The Enriched Contacts API provides access to Backstory-generated and enriched Contacts derived from your GTM motions.
Note that, depending on the organization’s Backstory configuration, the API will either return contacts created in your CRM system or contact candidates not synced with your CRM. For simplicity, we’ll refer to both variations as “contacts”.
Request Format
The Enriched Contacts API is a bulk REST API, which means data extraction jobs will be generated based on your requests, with files available for download upon completion.
curl -X POST |
Request Parameters
Parameter | Format | Description |
include_historical | Boolean | Will include contacts that are not matched to an account or opportunity |
include_existing | Boolean | Will include contacts that already exist in your CRM |
output_format | String | One of: "JSON", "CSV" |
start_date | String | Start date of your data retrieval, starting at 0:00 AM UTC of that day
Acceptable values follow the “yyyy-mm-dd” format |
end_date | String | End date of your data retrieval, ending at 11:59 PM UTC of that day
Acceptable values follow the “yyyy-mm-dd” format |
is_sourced_by_people_ai | Boolean | Will include only contacts created by us and generated candidates |
country | String | [Optional] Allows filtering contacts based on country, format "United States" |
state | String | [Optional] Allows filtering contacts based on state, format "New York" |
Response
Upon successful job creation, the API will return the following fields:
Field | Format | Description |
job_id | String | Unique identifier for the bulk export |
state | String | One of: “Queued”, “Running”, “Completed”, “Canceled”, “Failed” |
output_format | String | Export format requested. One of: "JSON", "CSV" |
job_created_time | yyyy-MM-ddTHH:mm:ssZ (UTC) | Time of the request |
job_start_time | yyyy-MM-ddTHH:mm:ssZ (UTC) | Time processing of the request started |
job_end_time | yyyy-MM-ddTHH:mm:ssZ (UTC) | Time processing of the request ended in any form (including cancellation and failure) |
results_size | Long | Result size in bytes (when the job is finished) |
fragments | Integer | Count of fragments for parallel data download, see below |
Job Status Request Format
To query the status of your job, use:
curl -X GET |
The response format for a job status request is the same as the response format for a successful job creation.
Data Retrieval
Once your job is complete, you can retrieve your data with:
curl -X GET |
For parallel retrieval, use fragments. When omitted, all fragments are stitched together to form a single file.
Parameter | Format | Description |
fragment | Integer | 0-based number of the fragment to retrieve |
Need help? Contact us at support@backstory.ai.