API Doc: 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.

Prospects

With this resource, you will be able to browse the prospect database in all possible direction and get some additional information about every single contact that was added to Woodpecker. There are a couple of ways to filter, search and order prospects. You are able to list basic information about prospects, like their full name, organization name, their status, etc. There are also ways to gain additional information about a specific group of prospects, like to which campaign they belong, when have they been created or used. 

Table of contents: 

  • Get a list of prospects  
  • Add / edit prospects in campaign 
  • Add / edit prospects on a global list   
  • Delete prospects  

Get a list of prospects

To get list of prospects 

GET /rest/v1/prospects

Sample request 

curl -u API_KEY:dummy_password https://api.woodpecker.co/rest/v1/prospects

Sample response 

{
    "id": 4804,
    "email": "erlich@bachman.com",
    "first_name": "Erlich",
    "last_name": "Bachman",
    "company": "Bachmanity",
    "website": "http://www.bachmanity.com/",
    "tags": "visioneer ",
    "title": "VC Angel",
    "phone": "",
    "address": "221 Newell Rd ",
    "city": "Palo Alto",
    "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",
    "snipet1": "Aesthetic bitters drinking vinegar, banh mi everyday",
    "snipet2": "Artisan post-ironic coloring book mumblecore before they sold out",
    "snipet3": "Blue bottle master cleanse raclette chicharrones venmo",
    "snipet4": "Cray whatever offal, snackwave pitchfork pok.,
    "status": "REPLIED"
  }

Query parameters 

Thanks to those parameters you will be able to narrow your results to prospects that fulfill conditions that you chose. Using the below parameters you can, for example, search for prospects that were contacted and did not reply or sort the results by a specific status. But that is only one of the possible scenarios. Using various combinations you will be able to get: 

URL Value type Description
per_page= number Number of results per page (default 100; max 500)
page= number Pagination controler - number of pages that you want the access to
sort=sort order | sort field sort order (+/-)


sort field name
This switch allows defining sort order, as well as fields on which the sort should be provided.
Sort order  (+ ascending) (- descending - default) 

Definition of fields on where sort will be provided.

List of available fields:
id - prospect id (can be used while sorting the most and least recent prospects)
last_replied - date of the mose recent response
status - status of the prospect
updated - date of the most recent update in prospect's data
email - email address
first_name - first name
last_name - last name
company - company name
industry - industry of the company
website - website address
tags - tags of the prospect
title - title of the prospect
phone - phone number of the prospect
address - physical address of the prospect
city - city of the prospect
state - state or geographical region of the prospect
country - country of the prospect
snippet1 .. snippet15 - custom snippet of the prospect

Custom cases - sorting by fields that require adding another parameter:
last_opened - requires the activity=OPENED parameter also given
last_clicked - requires the activity=CLICKED parameter also given
campaigns_id number This query parameter is used to define campaign/s where specific prospects are 
status enum It can be used to view prospects with specific status
(status explanation can be found here).
Available statuses [ ACTIVE | BOUNCED | TO-CHECK | TO-REVIEW | REPLIED | AUTOREPLIED | PAUSED | BLACKLIST|INVALID]
contacted bool This parameter allows to show prospects that have already been contacted [ 1 | yes | true ] or not [ 0 | no | false ]
activity enum The activity allows filtering prospects that have or have not made specific actions with the email that was sent to them. For example, you can browse prospects that have opened your email.    
Available switches: 
- OPENED - when prospect to whom the email was sent opened it at last once 
- NOT-OPENED - when a prospect to whom an email was sent have not opened it
- CLICKED - when a prospect to whom an email was sent clicked on a link placed in the email*
- NOT-CLICKED - when a prospect to whom an email was sent have not clicked on a link placed in email* 
* - available only when the click tracking is on - more info  here 
diff= field_type >  datetime datetime





field_type 		This option shows data that were changed since the specific date for a particular field type provided in a query. So, for example, you can request a list of prospects that were updated in a past week or month.

Dateformat YYYY-MM-DD'T'HH:MM:SSZ

Fields type available: 
- updated - this date field changes every time the prospect data are updated (for example, it detects every reply or opening of an email) via web interface, API or by Woodpecker system. 
- last_opened - email open events 
- last_clicked - email click events 
search=field_type=example-query field_type






















example-query 		id - prospect id (can be used while sorting the prospects by most and least recent prospects)
last_replied - date of the most recent response
status - status of the prospect
updated - date of the most recent update in prospect's data
email - email address
first_name - first name
last_name - last name
company - company name
industry - industry of the company
website - website address
tags - tags of the prospect
title - title of the prospect
phone - phone number of the prospect
address - physical address of the prospect
city - city of the prospect
state - state or geographical region of the prospect
country - country of the prospect
snippet1 .. snippet15 - custom snippet of the prospect 

Custom cases - sorting by this field requires adding another parameter:
last_opened - requires the activity=OPENED parameter also given
last_clicked - requires the activity=CLICKED parameter also given

String that you are searching for
campaigns_details=true bool Thanks to this parameter you are able to see more details about campaigns a specific prospect belongs to   
interested  enum You can sort prospects with specific interest level (INTERESTED | NOT-INTERESTED | MAYBE-LATER | NOT-MARKED)



Sample request 

https://api.woodpecker.co/rest/v1/prospects?status=REPLIED&campaigns_details=true&sort=+id

Sample response 

{
        "id": 10176741,
        "email": "erlich@bachman.com",
        "first_name": "Erlich",
        "last_name": "Bachman",
        "company": "Bachmanity",
        "industry": "",
        "website": "https://bachmanity.com",
        "tags": "",
        "title": "",
        "phone": "",
        "address": "",
        "city": "",
        "state": "",
        "country": "",
        "last_contacted": "2018-06-19T13:12:01+0100",
        "last replied": "2018-06-19T13:12:04+0100",
        "updated": "2018-06-19T13:13:47+0100",
        "snippet1": "",
        "snipet1": "",
        "snippet2": "",
        "snipet2": "",
        "snippet3": "",
        "snipet3": "",
        "snippet4": "",
        "snipet4": "",
        "snippet5": "",
        "snippet6": "",
        "snippet7": "",
        "snippet8": "",
        "snippet9": "",
        "snippet10": "",
        "snippet11": "",
        "snippet12": "",
        "snippet13": "",
        "snippet14": "",
        "snippet15": "",
        "status": "REPLIED",
        "campaigns_details": [
            {
                "campaign_id": 96937,
                "campaign_name": "Campaign",
                "campaign_status": "COMPLETED",
                "campaign_prospect_status": "REPLIED",
                "interested": "INTERESTED",
                "campaign_email": "hello@customer-success.us"
            },
            {
                "campaign_id": 64218,
                "campaign_name": "Campaign name",
                "campaign_status": "COMPLETED",
                "campaign_prospect_status": "REPLIED",
                "interested": "NOT_MARKED",
                "campaign_email": "hello@customer-sueccess.us"
            }
        ]

    }

Add / edit prospects 


Add prospect to campaign 

Sample request

POST /rest/v1/add_prospects_campaign
{
       "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"
    }
}

Sample response for duplicated prospects 
( full error code list)

{
	"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"
	}
}

Add prospect to prospects list 

If you want to add a prospect to global list you need to modify endpoint you are calling, as well as remove campaign details from the payload. 

POST /rest/v1/add_prospects_list
{
	"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",
    	"snipet1":"snipet1",
    	"snipet2":"snipet2",
    	"snipet3":"snipet3",
    	"snipet4":"snipet4"
    	}
]
}

Sample response

{
   "prospects":    [
      {"email": "add@email.co"}
   ],
   "status":    {
      "status": "OK",
      "code": "OK",
      "msg": "OK"
   }
}

Edit prospects data

NOTE: 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

Sample request

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

Related Articles