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.

email

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": "[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

Did this answer your question?