API Key is a part of an API Key and Integrations add-on, click here to learn how to get it on Marketplace »
IN THIS ARTICLE:
Browsing prospects
To get a list of all prospects added to your Woodpecker account, use the following request:
GET https://api.woodpecker.co/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": "#VISIONARY #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",
"encrypted": false,
"snipet1": "Pied Piper board member",
"snipet2": "no longer codes",
"snipet3":
"snipet4":
"snippet1": "Pied Piper board member",
"snippet2": "no longer codes",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": "",
"snippet_labels": {
"My snippet label": "Pied Piper board member"
},
"status": "REPLIED"
}
]
Response data type:
id - number, prospect ID.
email - string, prospect's email address.
first_name - string, prospect's first name.
last_name - string, prospect's last name.
company - string, prospect's company.
organization_id - number, organization ID if assigned.
industry - string, prospect's industry.
website - string, prospect's website.
linkedin_url - string, a link to the prospect's LinkedIn profile.
tags - string, prospect's tags.
title - string, prospect's title.
phone - string, prospect's phone number.
address - string, prospect's home address.
city - string, prospect's city.
state - string, prospect's state.
country - string, prospect's country.
last_contacted - string, an information about the the time when last email was sent to the prospect.
last replied - string, date of the most recent reply. Notice there is no underscore.
updated - string, an information about the last update of prospect's data.
encrypted - boolean, an information about the GDPR encryption.
snipet1...snipet4 - string, legacy custom fields.
snippet1...snippet15 - string, custom fields.
snippet_labels - JSON object, a list of custom snippet names and their values.
status - string, prospect's status.
Note:
Legacy parameters snipet1...snipet4 work the same way as snippet1...snippet4. However, we do not recommend using them in you integrations. Use snippet1...snippet4 instead.
Sorting and paging prospects
If you want to easily manage your results, you can either use sorting, filtering or paging.
Available parameters:
per_page - number, defines a number of results per page.
page - number, defines a page number you want access to.
sort - use with +/- and specific parameter, defines the sort order as well as the parameter on which sorting will be based.
Paging allows you to display prospects in desired batches.
Sample queries:
GET https://api.woodpecker.co/rest/v1/prospects?per_page=2
GET https://api.woodpecker.co/rest/v1/prospects?page=10
A default number of prospects per page is 100. You can increase this number up to 1000 by using a per_page parameter. Providing a higher number will give you results narrowed down to 1000.
Sorting allows you to sort the query results by the chosen parameter. Use + for ascending order and - for descending order. You can combine sorting with different parameters to get specific results.
Sample queries:
GET https://api.woodpecker.co/rest/v1/prospects?sort=+id
GET https://api.woodpecker.co/rest/v1/prospects?status=REPLIED&sort=+id
Sorting is available for the following parameters:
id
email
first_name
last_name
company
organization_id
industry
website
linkedin_url
tags
title
phone
address
city
state
country
last_contacted
last_replied - notice that this time there is an underscore
updated
snipet1...snipet4 - check Note for more information
snippet5...snippet15 - check Note for more information
status - check Note for more information
Note:
If you want to sort prospects by their status, using + to define the order will sort your prospects by their status in a following order: ACTIVE, BLACKLIST, BOUNCED, INVALID, REPLIED.
If you want to sort prospects by their status, using - to define the order will rost your prospects by their status in a following order: REPLIED, INVALID, BOUNCED, BLACKLIST, ACTIVE.
If you sort your prospects by their status and notice that there are some blacklisted prospects between those with status REPLIED and INVALID - they have the OPT-OUT status in the app and usually a tag #UNSUBSCRIBED.
Sorting by snippets works for snipet1...snipet4 and then for snippet5...snippet15. Sorting for snippet1...snippet4 is not provided.
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 https://api.woodpecker.co/rest/v1/[email protected]
GET https://api.woodpecker.co/rest/v1/prospects?search=first_name=Erlich
Searching is available for the following parameters:
email
first_name
last_name
company - you can use name with spaces
organization_id
industry
website
linkedin_url - you can use name with spaces
tags - provide tags without #
title - you can use name with spaces
phone
address
city
state
country
Filtering prospects by their activity
You can also filter prospect by their activity by adding an activity parameter to your request.
GET https://api.woodpecker.co/rest/v1/prospects?activity=NOT-OPENED
Available activities:
OPENED - for filtering prospects who opened any email from you
NOT-OPENED - for filtering prospects who didn't open any email from you
CLICKED - for filtering prospects who clicked on any link in your emails
NOT-CLICKED - for filtering prospects who didn't click on any link in your emails
Sample response for activity OPENED will include the following parameters:
last_open - string, last time prospect opened any email from you.
sent_mails - number, total number of emails sent to the prospect from all campaigns they belong to.
Sample response for activity CLICKED will include the following parameters:
last_clicked - string, last time prospect clicked on any link in your emails.
click_url - string, a link that was clicked most recently.
Filtering prospects by campaign they belong to
If you want to find all prospects that were added to the specific campaign, use the following request:
GET https://api.woodpecker.co/rest/v1/prospects?campaigns_id=1
You can provide multiple campaign IDs separated by comma.
By default we return information about 100 prospects so if you need to access more data, use a page or per_page parameters.
Prospect's details
If you want to check the campaign details for a specific prospect, use the following request:
GET https://api.woodpecker.co/rest/v1/prospects?campaigns_details=true
You can use different parameters in your request as well to get more specific results.
GET https://api.woodpecker.co/rest/v1/prospects?campaigns_details=true&status=REPLIED
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": "#VISIONARY #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",
"encrypted": false,
"snipet1": "Pied Piper board member",
"snipet2": "no longer codes",
"snipet3":
"snipet4":
"snippet1": "Pied Piper board member",
"snippet2": "no longer codes",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": "",
"snippet_labels": {
"My snippet label": "Pied Piper board member"
},
"status": "REPLIED",
"campaigns_details": [
{
"campaign_id": 96937,
"campaign_name": "Pied Piper for Hooli",
"campaign_status": "COMPLETED",
"campaign_prospect_status": "REPLIED",
"interested": "INTERESTED,
"campaign_email": "[email protected]"
"campaign_emails": [
"[email protected]",
"[email protected]",
"[email protected]"
]
},
{
"campaign_id": 64218,
"campaign_name": "Pied Piper joins Raviga",
"campaign_status": "COMPLETED",
"campaign_prospect_status": "REPLIED",
"interested": "NOT_MARKED"
}
]
}
]
Response data type:
campaigns_details - JSON object, detailed information about campaigns in which was or currently is a specific prospect.
campaign_id - number, campaign ID.
campaign_name - string, campaign name.
campaign_status - string, campaign status.
campaign_prospect_status - string, prospect's status in this specific campaign.
interested - string, interest level.
campaign_email - string, an email address the campaign is sent from.
campaign_emails - array, multiple email addresses the campaign is sent from.
If you need more details about those campaigns, use the campaign related endpoints. Detailed documentation can be found here.
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 https://api.woodpecker.co/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",
"snippet2": "no longer codes",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": ""
}
]
}
Sample response:
{
"prospects": [
{
"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 https://api.woodpecker.co/rest/v1/add_prospects_campaign
Sample body:
{
"campaign":{
"campaign_id": 4539
"send_after": "2025-08-11T00:00:00-0000"
},
"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. This response also shows when you change the prospect status in campaign.
{
"prospects": [
{
"email": "[email protected]"
"id": 47356575,
"prospects": "DUPLICATE"
},
],
"status": {
"status": "OK",
"code": "OK",
"msg": "OK"
}
}How to force a status change
Sometimes you may get an error that says, for example, "Status is other than ACTIVE". To prevent unwanted sending we decided to limit the ability of changing prospects' statuses via API.
When you change the status manually, we assume it's your careful decision. But when you do it in bulk with our API, you can't easily control any changes that happen in the back-end of our app. This is why the following tip must be use carefully, especially if you want to change such statuses as BLACKLISTED or RESPONDED. To fully understand how our statuses work and how they spread across campaigns, check this article.
You can force a status change on the following endpoints:
POST https://api.woodpecker.co/rest/v1/add_prospects_list
POST https://api.woodpecker.co/rest/v1/add_prospects_campaign
To do that, simply use a "force" parameter set to "true" in your request body.
Sample request for updating prospects on a Prospect's list:
{
"update": "true",
"force": "true",
"prospects": [
{
"id": 47356575,
"email": "[email protected]",
"first_name": "Eddy"
}
]
}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 https://api.woodpecker.co/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 https://api.woodpecker.co/rest/v1/prospects?id=1
DELETE https://api.woodpecker.co/rest/v1/prospects?id=1&campaigns_id=1
You can provide multiple prospect IDs by separating them with a comma:
DELETE https://api.woodpecker.co/rest/v1/prospects?id=1,2,3
Sample response:
200 OK
Changing prospects' Interest level
You can force the change of an Interest level of your prospect with the following endpoint:
POST https://api.woodpecker.co/rest/v1/add_prospects_campaign
To do that, simply use a "force" parameter set to "true" in your request body.
Remember to specify in which campaign you want the Interest level to be changed.
Sample request:
{
"campaign":
{
"campaign_id": 1591595
},
"force": "true",
"update": "true",
"prospects": [
{
"email": "[email protected]",
"interested": "MAYBE_LATER" // INTERESTED / MAYBE_LATER / NOT_INTERESTED / NOT_MARKED
}
]
}