Managing prospects

Learn how to browse the prospect database and get some additional information about your potential leads

Weronika Wróblewska avatar
Written by Weronika Wróblewska
Updated over a week ago

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
},
"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
}
]
}

Did this answer your question?