Backstory exposes a set of Bulk APIs to pull your data into the BI platform of your choice for further analysis, such as when joined with your organization’s own datasets. Our APIs can be grouped into two main categories:

Activity APIs providing access to raw activity data ingested from your GTM motions
Contact APIs providing access to Contacts created by and/or enriched by Backstory

Use Limits

To protect the integrity of our platform, usage of the Backstory APIs is subject to these use limits:

Maximum number of concurrent export jobs	2
Maximum number of queued export jobs (inclusive of currently exporting jobs)	10
File retention period	10 days
Maximum date range for snapshot data	1 year
Maximum date range for non-snapshot (delta) data	14 days

URL Format

Our APIs use versioned URLs for version control purposes. The default URL format is:

curl -X GET/POSThttps://api.people.ai/[action]/[version]/[API name]-H "Authorization: Bearer [bearer token]"-H "Content-Type: [content type]"-d "[request parameters]"

HTTP request methods are API-specific; APIs will return a 404 HTTP response code for unsupported methods.

Response Format

The default output format for the Activity APIs is JSON Lines. For the Object APIs, it’s CSV. Due to their data schemas, different APIs support various output formats. To switch between them, use the output_format request parameter described below.

Authentication

Authentication for the Backstory APIs is managed through 2-legged OAuth 2.0.

Getting Started

Backstory administrators can manage up to 5 active API key/secret pairs in the Backstory web application. Each API key/secret pair is restricted to a single API type: Activity, Insight, or Object.

To generate a new API key/secret pair, navigate to Settings > API Key Management.

The API Key Management screen lists all of your current API keys organized by type, status, and creation time.

To generate an API key/secret pair, click the Generate API Key button. Your new API key/secret pair will be displayed.

For security reasons, we’re unable to retrieve your API secrets after they have been generated. Please ensure that you store them in a secure location.
Should you ever lose track of an API secret, you can revoke the corresponding API key as described below and generate a new API key/secret pair.

API Key Management

API keys can be paused and revoked in the API Key Management screen. If you revoke an API key, it will be permanently disabled. Pausing an API key, on the other hand, is a temporary action that can be undone.

To revoke or pause an API key, highlight the key in the API Key Management screen, click the menu button (), and select your desired action. To unpause an API key, follow the same flow and click the Unpause button.

API Authentication

All Backstory API requests require a valid bearer token. To generate a token, pass the appropriate API key/secret pair into the token generation API:

curl -X POSThttps://api.people.ai/auth/v1/tokens-H "Content-Type: application/x-www-form-urlencoded"-d "grant_type=client_credentials&client_id='[API key]'&client_secret='[API secret]'"

According to the OAuth 2.0 specification, authentication requests must include the Content-Type: application/x-www-form-urlencoded header.

The API service will return your bearer token:

{
  "access_token": [access token],
  "token_type": "bearer"
  "expires_in": [remaining lifespan in seconds, int]
}

Access is provided in the JSON Web Tokens (JWT) format, and has a default lifespan of 7200 seconds. If you call the Token API before the access token has expired, the API will issue the new access token. The previously issued access token for this API key/secret will also remain active within its remaining lifespan.

Pass your newly generated bearer token in the Authorization: Bearer header of your API requests.

Need help? Drop us a line at support@backstory.ai

Authentication

API Key Management

Activity APIs: Resources

Backstory APIs for Ingesting Transcripts

Forecasting Query API