API – Managing prospects
API Key is a part of an API Key and Integrations add-on, click here to learn how to get it on Marketplace »
With this document, you'll be able to browse the prospect database in all possible directions and get some additional information about every single contact that you've added to Woodpecker.
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": "erlich@bachman.com",
"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",
"snipet2": "no longer codes",
"snippet3": "",
"snipet3": "",
"snippet4": "",
"snipet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snipper9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": "",
"status": "REPLIED",
},
{
"id": 2974,
"email": "jared@piedpiper.com",
"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",
"snipet1": "Pied Piper board member",
"snippet2": "",
"snipet2": "",
"snippet3": "",
"snipet3": "",
"snippet4": "",
"snipet4": "",
"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 number of results per page. |
| page | number | Defines a page number you want an 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. |
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": "erlich@bachman.com",
"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",
"snipet2": "no longer codes",
"snippet3": "",
"snipet3": "",
"snippet4": "",
"snipet4": "",
"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 POST method. Use the following endpoint and provide 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": "erlich@aviato.com",
"first_name": "Erlich",
"last_name": "Bachman",
"status": "ACTIVE",
"company": "Aviato",
"industry": "technology",
"website": "https://bachmanity.com",
"linkedin_url": "https://www.linkedin.com/in/erlich-bachman/",
"tags": "#evangelist",
"title": "software designer",
"phone": "+1 6951934",
"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": "",
"snippet9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": ""
},
{
"email": "jared@piedpiper.com",
"first_name": "Jared",
"last_name": "Dunn",
"status": "ACTIVE",
"company": "Pied Piper",
"industry": "technology",
"website": "https://piedpiper.com",
"linkedin_url": "https://www.linkedin.com/in/jared-dunn/",
"tags": "",
"title": "PR",
"phone": "+1 7432674",
"address": "221 Newell Rd",
"city": "Palo Alto",
"state": "California",
"country": "USA",
"snippet1": "Pied Piper PR specialist",
"snippet2": "",
"snippet3": "",
"snippet4": "",
"snippet5": "",
"snippet6": "",
"snippet7": "",
"snippet8": "",
"snippet9": "",
"snippet10": "",
"snippet11": "",
"snippet12": "",
"snippet13": "",
"snippet14": "",
"snippet15": ""
}
]
}
Sample response:
{
"prospects": [
{
"email": "erlich@aviato.com"
},
{
"email": "jared@piedpiper.com"
}
],
"status": {
"status": "OK",
"code": "OK",
"msg": "OK"
}
}
Adding prospects to the campaign
You can also add prospects to the specific campaign with POST method. Use the following endpoint and provide 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": "add@email.co",
"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": "add@email.co",
"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": "richard@piedpiper.com",
"id": 615120,
"prospect": "DUPLICATE"
},
{
"email": "erlich@bahmanity.com",
"id": 3161,
"prospect": "DUPLICATE"
}
],
"status": {
"status": "OK",
"code": "OK",
"status_message": "OK"
}
}
Updating prospects data
Some prospect's details are outdated? No worries, you can always update them. Simply provide prospect's ID in the payload. Rememeber, all fields mentioned in the request will be updated.
Sample request:
POST /rest/v1/add_prospects_list
{
"update": "true",
"prospects": [
{
"id": 1125,
"email": "email@to-update.com" ,
"first_name": "Eddy"
}
]
}
Sample response:
{
"prospects": [ {
"email": "email@to-update.com",
"id": 1125
}
],
"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