API Key is a part of an API Key and Integrations add-on, click here to learn how to get it on Marketplace »
Browsing prospects
To get a list of all prospects added to your Woodpecker account, use the following request:
GET /rest/v1/prospects
Sample response:
[ {
"id": 4804,
"email": "[email protected]",
"first_name": "Erlich",
"last_name": "Bachman",
"company": "Bachmanity",
"organization_id": 93784,
"industry": "Software as a Service",
"website": "http://www.bachmanity.com/",
"linkedin_url": "https://www.linkedin.com/in/erlich-bachman/",
"tags": "#VISIONEER #SECONDARYEMAIL",
"title": "VC Angel",
"phone": "",
"address": "221 Newell Rd ",
"city": "Palo Alto",
"state": "California",
"country": "USA",
"last_contacted": "2016-08-14T02:08:58+0200",
"last replied": "2016-08-19T02:08:58+0200",
"updated": "2016-09-03T15:02:57+0200",
"snippet1": "Pied Piper board member",
"snipet1": "Pied Piper board member",
"snippet2": "no longer codes",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": "",
"status": "REPLIED",
},
{
"id": 2974,
"email": "[email protected]",
"first_name": "Jared",
"last_name": "Dunn",
"company": "Pied Piper",
"organization_id": 72894,
"industry": "Software as a Service",
"website": "http://www.piedpiper.com/",
"linkedin_url": "https://www.linkedin.com/in/jared-dunn/",
"tags": "#PR #SECONDARYEMAIL",
"title": "PR specialist",
"phone": "",
"address": "221 Newell Rd ",
"city": "Palo Alto",
"state": "California",
"country": "USA",
"last_contacted": "2016-08-14T02:08:58+0200",
"last replied": "2016-08-19T02:08:58+0200",
"updated": "2016-09-03T15:02:57+0200",
"snippet1": "Pied Piper board member",
"snippet2": "",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": "",
"status": "REPLIED"
}
]
A detailed explanation for parameters can be found below.
Sorting, filtering and paging prospects
If you want to easily manage your results, you can either use sorting, filtering or paging.
Query | Use | Description |
per_page | number | Defines a number of results per page. |
page | number | Defines a page number you want access to. |
sort | +/- and parameter | Defines the sort order, as well as the field on which sorting will be based. |
Sample queries:
GET /rest/v1/prospects?per_page=2
GET /rest/v1/prospects?page=10
GET /rest/v1/prospects?sort=+id
GET /rest/v1/prospects?status=RESPONDED&sort=+id
While sorting, use + for ascending order and – for descending order.
Remember to provide the field on which sorting will be based. We provide sorting for the following parameters:
Parameter | Type | Description |
id | number | Prospect’s ID. |
last_replied | string | Date of the most recent reply. |
status | string | Prospect’s status saved on a Prospects list. Available statuses: ACTIVE, INVALID, BOUNCED, REPLIED, BLACKLIST. |
updated | string | Date of the most recent update done on prospect’s details. |
string | Prospect’s email address. | |
first_name | string | Prospect’s first name. |
last_name | string | Prospect’s last name. |
company | string | Name of the company prospect is assigned to. |
industry | string | Type of industry prospect is working in. |
website | string | Website address. |
linkedin_url | string | An URL to the prospect’s Linkedin profile. |
tags | string | Prospect’s tags. |
title | string | Prospect’s job title. |
phone | string | Prospect’s phone number. |
address | string | Prospect’s address. |
city | string | Prospect’s city. |
state | string | Prospect’s state or another geographical region he’s living in. |
country | string | Prospect’s country. |
snippet | string | Any snippet provided for a prospect. Use snippet1, snippet2… snippet15 to sort prospects by chosen custom field. |
activity | string | Defines prospect’s activity. Available |
snippet | string | Any snippet provided for a prospect. Use snippet1, snippet2… snippet15 to sort prospects by chosen custom field. |
Searching specific prospects
If you know what prospects you’re looking for, you can use a search parameter to get information only about them. Remember to provide a search attribute – you can find a list of available parameters below.
Sample queries:
GET /rest/v1/[email protected]
GET /rest/v1/prospects?search=first_name=Erlich
Parameter |
Type |
Description |
|
string |
Prospect’s email address. |
first_name |
string |
Prospect’s first name. |
last_name |
string |
Prospect’s last name. |
company |
string |
Name of the company prospect is assigned to. |
industry |
string |
Type of industry prospect is working in. |
website |
string |
Website address. |
linkedin_url |
string |
An URL to the prospect’s Linkedin profile. |
tags |
string |
Prospect’s tags. |
title |
string |
Prospect’s job title. |
phone |
string |
Prospect’s phone number. |
address |
string |
Prospect’s address. |
city |
string |
Prospect’s city. |
state |
string |
Prospect’s state or another geographical region he’s living in. |
country |
string |
Prospect’s country. |
Prospect’s details
If you want to check the campaign details for a specific prospect, use the following request:
GET /rest/v1/prospects?id=num&campaigns_details=true
where id stands for prospect’s ID. You can easily use parameters other than prospect’s ID. just remember to add campaigns_details to your request to get more detailed information.
Sample response:
[ {
"id": 4804,
"email": "[email protected]",
"first_name": "Erlich",
"last_name": "Bachman",
"company": "Bachmanity",
"organization_id": 93784,
"industry": "Software as a Service",
"website": "http://www.bachmanity.com/",
"linkedin_url": "https://www.linkedin.com/in/erlich-bachman/",
"tags": "#VISIONEER #SECONDARYEMAIL",
"title": "VC Angel",
"phone": "",
"address": "221 Newell Rd ",
"city": "Palo Alto",
"state": "California",
"country": "USA",
"last_contacted": "2016-08-14T02:08:58+0200",
"last replied": "2016-08-19T02:08:58+0200",
"updated": "2016-09-03T15:02:57+0200",
"snippet1": "Pied Piper board member",
"snipet1": "Pied Piper board member",
"snippet2": "no longer codes",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": "",
"status": "REPLIED",
},
{
"id": 2974,
"email": "[email protected]",
"first_name": "Jared",
"last_name": "Dunn",
"company": "Pied Piper",
"organization_id": 72894,
"industry": "Software as a Service",
"website": "http://www.piedpiper.com/",
"linkedin_url": "https://www.linkedin.com/in/jared-dunn/",
"tags": "#PR #SECONDARYEMAIL",
"title": "PR specialist",
"phone": "",
"address": "221 Newell Rd ",
"city": "Palo Alto",
"state": "California",
"country": "USA",
"last_contacted": "2016-08-14T02:08:58+0200",
"last replied": "2016-08-19T02:08:58+0200",
"updated": "2016-09-03T15:02:57+0200",
"snippet1": "Pied Piper board member",
"snippet2": "",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": "",
"status": "REPLIED"
"campaigns_details": [
{
"campaign_id": 96937,
"campaign_name": "Pied Piper for Hooli",
"campaign_status": "COMPLETED",
"campaign_prospect_status": "REPLIED",
"interested": "INTERESTED", },
{
"campaign_id": 64218,
"campaign_name": "Pied Piper joins Raviga",
"campaign_status": "COMPLETED",
"campaign_prospect_status": "REPLIED",
"interested": "NOT_MARKED",
}
]
}
If you need more details about those campaigns, use the campaign related endpoints. Detailed documentation can be found here.
Parameter | Type | Description |
campaigns_details | JSON object | Detailed information about campaigns in which was or currently is a specific prospect. |
campaign_id | number | Campaign ID. |
campaign_prospect_status | string | Prospect’s status saved on a campaign level. Available statuses: ACTIVE, INVALID, BOUNCED, BLACKLIST, REPLIED, PAUSED. |
interested | string | Prospect’s interest level in a specific campaign. Available Options: INTERESTED, NOT INTERESTED, MAYBE LATER. |
Adding prospects to the prospect list
Adding prospects to the global prospects list is available with the POST method. Use the following endpoint and provide the prospect’s details in the payload body. You can add multiple prospects in one request.
POST /rest/v1/add_prospects_list
Sample body:
{
"update": "true",
"prospects": [
{
"email": "[email protected]",
"first_name": "Erlich",
"last_name": "Bachman",
"company": "Bachmanity",
"organization_id": 93784,
"industry": "Software as a Service",
"website": "http://www.bachmanity.com/",
"linkedin_url": "https://www.linkedin.com/in/erlich-bachman/",
"tags": "#VISIONEER #SECONDARYEMAIL",
"title": "VC Angel",
"phone": "",
"address": "221 Newell Rd ",
"city": "Palo Alto",
"state": "California",
"country": "USA",
"snippet1": "Pied Piper board member",
"snipet1": "Pied Piper board member",
"snippet2": "no longer codes",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": ""
},
{
"email": "[email protected]",
"first_name": "Jared",
"last_name": "Dunn",
"company": "Pied Piper",
"organization_id": 72894,
"industry": "Software as a Service",
"website": "http://www.piedpiper.com/",
"linkedin_url": "https://www.linkedin.com/in/jared-dunn/",
"tags": "#PR #SECONDARYEMAIL",
"title": "PR specialist",
"phone": "",
"address": "221 Newell Rd ",
"city": "Palo Alto",
"state": "California",
"country": "USA",
"snippet1": "Pied Piper board member",
"snippet2": "",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": ""
}
]
}
Sample response:
{
"prospects": [
{
"email": "[email protected]"
},
{
"email: "[email protected]"
}
],
"status": {
"status": "OK",
"code": "OK",
"msg": "OK"
}
}
Adding prospects to the campaign
You can also add prospects to the specific campaign with the POST method. Use the following endpoint and provide the prospect’s details in the payload body. You can add multiple prospects in one request.
POST /rest/v1/add_prospects_campaign
Sample body:
{
"campaign":{
"campaign_id": 4539
},
"update": "true",
"prospects": [
{
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"status": "ACTIVE",
"tags": "#tags",
"company": "company",
"industry": "industry",
"linkedin_url": "https://www.linkedin.com/in/john-doe/",
"title": "title",
"phone": "+123 456 789",
"address": "address",
"city": "city",
"state": "state",
"country": "country",
"website": "website",
"snippet1": "snippet1",
"snippet2": "snippet2",
"snippet3": "snippet3",
(...)
"snippet15": "snippet15"
}
]
}
Sample response:
{
"prospects": [
{
"email": "[email protected]"
"id": 47356575
},
],
"status": {
"status": "OK",
"code": "OK",
"msg": "OK"
}
}
If by mistake you’ll add a duplicated prospect to the campaign, you’ll receive a proper server response. Full error code list is available here.
{
"prospects": [
{
"email": "[email protected]"
"id": 47356575,
"prospects": "DUPLICATE"
},
],
"status": {
"status": "OK",
"code": "OK",
"msg": "OK"
}
}
Updating prospects data
Some prospect’s details are outdated? No worries, you can always update them. Simply provide the prospect’s ID in the payload. Remember, all fields mentioned in the request will be updated.
Sample request:
POST /rest/v1/add_prospects_list
{
"update": "true",
"prospects": [
{
"id": 47356575,
"email": "[email protected]"
"first_name": "Eddy"
}
]
}
Sample response:
{
"prospects": [
{
"email": "[email protected]"
"id": 47356575,
},
],
"status": {
"status": "OK",
"code": "OK",
"msg": "OK"
}
}
Delete prospects data
If you no longer want to contact some of your prospects, delete them from a specific campaign or entire database.
DELETE /rest/v1/prospects?id=1
DELETE /rest/v1/prospects?id=1&campaigns_id=1
Sample response:
200 OK