Pitchbox API Local (2.0)

E-mail: api@pitchbox.com License: proprietary

Pitchbox Developer API V2

The new Pitchbox API (API V2) allows you to access and interact with your Pitchbox data. The RESTful interface with JSON-formatted responses provides an easy way for developers to access the campaign, project, and outreach-related data.

Downloads

To help you test the API, Download a Swagger file to use in other API documentation tools such as Postman.

To get a proper directory structure when importing to Postman, please select "Tag" as the "Folder Organization" option. See screenshot below.

Folder Organization

Requests

Pagination

All "List" methods include pagination. To control limit and page numbers, use parameters page and limit.

Example of Opportunity Search with 10 results starting at page 3:

/api/opportunities?page=3&limit=10

The default limit is 100 items per page and maximum is 1000. If limit is set to greater than 1000, only 1000 results will be returned.

Filters

Results from list method can be filtered using two ways:

A q parameter, which is very dynamic and mimics Advanced Search functionality in the Pitchbox application.
Specific parameters defined for each method in the documentation.

The q parameter supports the following conditions:

Condition	Example
=	q=project.name="Example", q=project.name=""
!=	q=project.name!="Example", q=project.name!=""
:	(Like) q=project.name:"Example"
!:	(Not like) q=project.name!:"Example"
>=	q=project.id>=5
<=	q=project.id<=5
>	q=project.id>5 -> project.id > 5
<	q=project.id<5 -> project.id < 5

Rate Limit

The rate limit is 300 requests per minute (rolling), per user. If the limit is reached, requests will be throttled and fail with status code 429.

Responses

Possible response status codes and messages:

Status Code	Description	Response Body
200	OK	JSON
400	Bad request, missing required data, etc.	`{"message": "Missed required request parameters"}`
401	Unauthorized. Invalid or missing signature	`{"message": "Access token is required for this operation."}`
403	Access denied for inactive users	`{"message": "User or account inactive"}`
404	Resource not found	`{"message": "Account contact not found"}`
503	Maintenance	`{"message": "Maintenance"}`

API Authentication

Overview

Pitchbox's API supports API Keys (JWT) authentication method. API Keys can be retrieved using two methods: using Pitchbox's user interface or using the "Get Refresh Token" endpoint.

First method is simple: API keys are created and managed in Pitchbox's user interface. To generate and retrieve API keys, click on the 'My Profile' menu item and select the 'API Keys' option. Then click on the 'New API Key' button to generate new keys. To retrieve an existing key, click the 'Copy' icon.

Api Credentials

The second method requires two steps:

Step 1 - Get Refresh Token: Send a request to the “Get Refresh Token” endpoint with your authorization data (email, password, account_name)

Step 2 - Get Access Token: Send a request to the “Get Access Token” endpoint and pass the newly generated Refresh Token. Access Tokens are active for 30 minutes.

Authentication

JWT

The Pitchbox API V2 uses JWT (JSON Web Tokens) to authenticate user-level access. JWT one of the most secure ways to authenticate to the Pitchbox's API and is an open standard. When authenticating to the Pitchbox's API, a JWT should be included as a Bearer <JWT> in each request's header.

Example:

// example.http
GET https://apiv2.pitchbox.com/api/opportunities
Authorization: Bearer <your token here>

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

ClientIdInHeader

Security Scheme Type	API Key
Header parameter name:	X-Client-Id

ClientKeyInHeader

Security Scheme Type	API Key
Header parameter name:	Authorization

Auth

Get Access Token

Returns an access_token valid for 30 minutes.

Request Body schema: application/json

refresh_token

string

Responses

Request samples

Payload

Content type

application/json


{"refresh_token": "eyJ0e.eyJleHAiOm51b.b2dYOEfpg"
}

Response samples

200

Content type

application/json


{"access_token": "eyJ0e.eyJleHAiOm51b.b2dYOEfpg"
}

Get Refresh Token

Returns a refresh_token needed to generate an access_token. This request will also provide the initial access_token, which is good for 30 minutes. When the access_token expires, use the Get Access Token method to generate a new one.

Request Body schema: application/json

email	string
password	string
account_name	string

Responses

Request samples

Payload

Content type

application/json


{"email": "superman@pitchbox.com",
"password": "12345",
"account_name": "superman"
}

Response samples

200

Content type

application/json


{"access_token": "yJ0e.eyJleHAiOm51b.b2",
"refesh_token": "yJ0e.eyJleHAiOm51b.b2",
"expires_in": "1800",
"client_payload": 
[null
],
"profile": 
{"user_id": "1",
"first_name": "Steeve",
"last_name": "Jobs",
"email": "superman@pitchbox.com"
}
}

Address Book

Get Contact By Id

Get Contact By Id
Response item cost: 1
Request cost: 2

q	string Filter by response properties
campaign.id	number Filtering by campaign.id
email	string Filtering by email
is_unsubscribed	boolean Filtering by is_unsubscribed
opportunity.id	number Filtering by opportunity.id
project.id	number Filtering by project.id

input required	Array of strings Array of urls
metrics_filter_template_id	number Campaign metrics filter template (see List Metrics Filter Templates)

input required	Array of strings Array of keywords/urls
metrics_filter_template_id	number Campaign metrics filter template (see List Metrics Filter Templates)

required	Array of objects Array of opportunity data
	object Full list of personalization fields can be obtained at /api/personalization endpoint.
	object Full list of custom fields can be obtained at /api/custom_fields endpoint.
metrics_filter_template_id	number Campaign metrics filter template (see List Metrics Filter Templates)

clone_campaign_id	number Requests with this field will copy the settings such as templates, outreach schedules, and personalization fields from a given campaign ID.
name required	string Campaign name
project required	number Campaign project
country	string Country code (ISO 3166-1 alpha-2, example: us, gb)
input required	Array of strings Array of urls
tag_campaign_ids	Array of numbers Array of tag ids
limit	number Campaign opportunities limit (maximum depends on your plan)
backlink_type	string Specify integration partner to use. Options are: moz, majestic, ahrefs, moz-url, majestic-url, ahrefs-url, ahrefs-broken. Integration partner campaigns require authorization and configuration through the app.
get_metrics	boolean
get_contacts	boolean
opportunity_deduplication	boolean
metrics_filter_template_id	number Campaign metrics filter template (see List Metrics Filter Templates)

q	string Filter by response properties
id	number Filtering by id
name	string Filtering by name
project.id	number Filtering by project.id
status	string Filter by status. Possible values: active, archived, deleted

name	string Nullable
domain_contact	boolean Nullable
disable_deduplication	boolean Nullable
approval_workflow	boolean Nullable

daily_limit	number Nullable
schedule_time_from	string Nullable
schedule_time_to	string Nullable
is_active	boolean Nullable
pause_outreach_until	string <date-time> Nullable Pause outreach until (Accepts 30-minute increments only)
	object

q	string Filter by response properties
sent_at_from required	string <date-time> Example 1 (single date): `2020-07-07 10:10` Example 2 (date range): `2025-02-24\|2025-02-27` Filtering by the sent_at_from can be done with a single date or a date range. When date range is used, separate the FROM and TO dates by a pipe, `\|`. The data ranges are inclusive.
sent_at_to required	string <date-time> Example 1 (single date): `2020-07-07 10:10` Example 2 (date range): `2025-02-24\|2025-02-27` Maximum period is 30 days
campaign.id	number Filtering by campaign.id
contact.id	number Filtering by contact.id
email_account.id	number Filtering by email_account.id
opportunity.id	number Filtering by opportunity.id
project.id	number Filtering by project.id
user.id	number Filtering by user.id

url	string Opportunity url (For contact-based opportunity, do not provide 'url'. Just add value to 'contact' field.)
campaign required	number Opportunity project
	Array of objects Array of opportunity contacts (in case of empty url it will opportunity)
	object Oppotunity personalization. Field names: website, email_address, opportunity_name, first_name, last_name, company, job_title, work_phone, mobile_phone, contact_form_url, site_name, page_title

custom_field	integer Nullable Id of related custom_field
value	string Nullable

personalization_field	integer Nullable Id of related personalization_field
value	string Nullable

campaigns_over_time	boolean Include campaigns over time
workflow_over_time	boolean Include workflow over time
outreach_over_time	boolean Include outreach over time
won_lost_over_time	boolean Include won lost over time
responses_by_attempt	boolean Include responses by attempt
start_date	string <date> Reports start date
end_date	string <date> Reports end date
project_id	integer Reports by projects
campaign_id	integer Reports by campaigns
tag_opp_ids	Array of numbers Reports by opportunity tags
tag_campaign_ids	Array of numbers Reports by campaign tags

q	string Filter by response properties
group	string Context group of call usage. Available groups: by_domain,with_fields_and_metrics.
project.id required	number Filtering by project.id
campaign.id	number Filtering by campaign.id
campaign.status	string Filter by status. Possible values: active, archived, deleted
created_at	string <date> Example 1 (single date): `2025-02-27` Example 2 (date range): `2025-02-24\|2025-02-27` Filtering by the created_at can be done with a single date or a date range. When date range is used, separate the FROM and TO dates by a pipe, `\|`. The data ranges are inclusive.
domain.name	string Filtering by domain.name
id	number Filtering by id
include_contacts	boolean Include opportunity contacts to response
last_communication_date	string <date> Example 1 (single date): `2025-02-27` Example 2 (date range): `2025-02-24\|2025-02-27` Filtering by the last_communication_date can be done with a single date or a date range. When date range is used, separate the FROM and TO dates by a pipe, `\|`. The data ranges are inclusive.
last_communication_type	string Filtering by last_communication_type
milestone.id	number Filtering by milestone.id
milestone_date	string <date> Example 1 (single date): `2025-02-27` Example 2 (date range): `2025-02-24\|2025-02-27` Filtering opportunities by the last milestone_date can be done with a single date or a date range. When date range is used, separate the FROM and TO dates by a pipe, `\|`. The data ranges are inclusive.
name	string Filtering by name
outreach_in_progress	boolean Filtering by outreach_in_progress
outreach_started_date	string <date> Example 1 (single date): `2025-02-27` Example 2 (date range): `2025-02-24\|2025-02-27` Filtering by the outreach_started_date can be done with a single date or a date range. When date range is used, separate the FROM and TO dates by a pipe, `\|`. The data ranges are inclusive.
project.status	string Filter by status. Possible values: active, archived, deleted
tag_name	string Filter by tag name
updated_at	string <date> Example 1 (single date): `2025-02-27` Example 2 (date range): `2025-02-24\|2025-02-27` Filtering by the updated_at can be done with a single date or a date range. When date range is used, separate the FROM and TO dates by a pipe, `\|`. The data ranges are inclusive.
url	string Filtering by url
workflow_status	string Filtering by workflow_status

visibility	string Nullable
	object Nullable
	object Nullable
	object Nullable
	object Nullable
	object Nullable
	object Nullable
name	string Nullable

assigned_to	integer Nullable Id of related assigned_to
project required	integer Nullable Id of related project
campaign	integer Nullable Id of related campaign
communication	integer Nullable Id of related communication
opportunity	integer Nullable Id of related opportunity
name required	string Nullable
description	string Nullable
due_date	string <date-time> Nullable
autocomplete_on_communication	boolean Nullable
autocomplete_on_milestone	boolean Nullable

q	string Filter by response properties
type	string Filter by tag type (campaign or opportunity)

Pitchbox API Local (2.0)

Pitchbox Developer API V2

Downloads

Requests

Pagination

Filters

Rate Limit

Responses

API Authentication

Overview

Authentication

JWT

ClientIdInHeader

ClientKeyInHeader

Auth

Get Access Token

Request Body schema: application/json

Responses

Request samples

Response samples

Get Refresh Token

Request Body schema: application/json

Responses

Request samples

Response samples

Address Book

Get Contact By Id

Authorizations:

Responses

Response samples

List Contacts

Authorizations:

query Parameters

Responses

Response samples

Update Contact By Id

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Campaigns

Add Campaign Tags

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Add to Backlink Campaign

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Add to Discovery Campaign

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Add to Import Campaign

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Add to Link Removal Campaign

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Create Backlink Campaign

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Create Discovery Campaign

Authorizations: