Managing prospects

Integrations are available with API Key. To generate a new API Key you need to be a Team Pro, Agency or Enterprise user.
If you'd like to upgrade your plan, contact support@woodpecker.co.

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 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/",
    "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/",
    "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

f 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/v2/prospects?per_page=2 
GET /rest/v2/prospects?page=10 
GET /rest/v2/prospects?sort+id 
GET /rest/v2/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.   
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 other geographical region he's living in.
country string Prospect's country.
snippet string Any snippet provided for 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 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/",
    "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", 		
            "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", 		
            "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",
    	    "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
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us