Old API Docs

This is the old version of API documentation (version from 20.07.2018). We maintain this version for some time until new API docs will be mature. 

To view latest version visit this link

Overview

API Key is a part of an API Key and Integrations add-on, click here to learn how to get it on Marketplace »

How to generate an API Key?

To generate a new API Key, follow the 3 steps below:

  1. Log into your Woodpecker account on app.woodpecker.co.
  2. Go to Settings > API Keys.

  3. Click the green button "Create a Key" in the top right corner of the page.

Endpoints
Authentication

This is an HTTPS-only API. Authentication is based on API Keys. Each API Key is associated with a Woodpecker user. Results returned from various responses are based upon the role of the user to which the API key is tied.

The API Key is passed via HTTP Basic Authentication and goes in the username field. A dummy password, such as X, goes in the password field.

To try the API via curl on the command-line, the general form used would be:

curl -u API_KEY:DUMMY_PASSWORD API_URL

For instance, if your API key is 60783dd23ef, you would execute:

curl -u 60783dd23ef:X https://api.woodpecker.co/rest/v1/campaign_list


All API requests are made to  https://api.woodpecker.co/ and all requests are served over HTTPS. The current version is v1.

Each endpoint specifies the response format in the URL. However, the API will only support JSON at this time. If you have further questions feel free to write  integrations@woodpecker.co

Contents

1. Browsing prospects  
2. Browsing campaigns
3. Adding prospects
4. Deleting prospects
5. Blacklisting prospects
6. Webhooks 



1. Browsing prospects

To get the list of prospects:

REQUEST: 

GET /rest/v1/prospects

RESPONSE: (sample record)  

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

To get the list of prospects with additional information:

REQUEST: 

GET /rest/v1/prospects?campaigns_details=true

RESPONSE: (sample record)  

{
    "id": 4804,
    "email": "erlich@bachman.com",
   (...)
    "snipet4": "Cray whatever offal, snackwave pitchfork pok.,
    "status": "REPLIED", 
    "campaigns_details": [
            {
                "campaign_id": 78570,
                "campaign_name": "Bachmanity and co",
                "campaign_status": "COMPLETED",
                "campaign_prospect_status": "REPLIED",
                "interested": "NOT_MARKED",
                "campaign_email": "hello@bachmanity.com"
            }
  }

To browse prospects from specific campaigns:

REQUEST: 
/rest/v1/prospects?campaigns_id=num1 - num stands for campaign ID
/rest/v1/prospects?campaigns_id=num1,num2,num3,...

RESPONSE: 

{
    (....)
    "status": "ACTIVE",
    "campaign_id": 10030,
    "campaign_name": "Bachmanity outreach",
    "campaign_email": "bighead@bachmanity.com",
    "sent_mails": 2
}

To browse prospects of a specific status:

REQUEST: 
/rest/v1/prospects?status=REPLIED 
status=enum (uppercase) [ ACTIVE | BLACKLIST | AUTOREPLIED | TO-CHECK | TO-REVIEW | BOUNCED | INVALID | REPLIED ]

Additional statuses TO-CHECK and PAUSED are also available while browsing prospects in certain campaigns. If you want to browse prospects with certain status, you need to add campaign ID to the request.

REQUEST: 
/rest/v1/prospects?campaigns_id=22&status=TO-CHECK 
/rest/v1/prospects?campaigns_id=30112&status=PAUSED

To browse prospects that performed a specific action:

REQUEST: 
/rest/v1/prospects?activity=OPENED 
/rest/v1/prospects?activity=OPENED&status=REPLIED
activity=enum (uppercase) [ OPENED | NOT-OPENED | CLICKED | NOT-CLICKED ]

To browse interest rate:

REQUEST: 
/rest/v1/prospects?campaigns_id=10074&interested=INTERESTED
interested=enum (uppercase) [ INTERESTED | NOT-INTERESTED | MAYBE-LATER | NOT-MARKED ]

Browsing of interest rate is only possible after specifying campaigns you are referring to "campaigns_id" should be added to the request.

To browse a list of prospects who were or were not contacted:

REQUEST: 
/rest/v1/prospects?contacted=no
contacted = boolean [ yes | no ]

To browse results of prospects search:

REQUEST: 
/rest/v1/prospects?search=first_name=John
/rest/v1/prospects?search=<field_type>=<query>
Field types available:
  • 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 orgin of the prospect
  • state - state or geographical region of the prospect
  • country - country of the prospect
  • snippet1 .. snippet4 - custom snippets of the prospect

To browse data of a specific prospect:

REQUEST: 
/rest/v1/prospects?id=num
/rest/v1/prospects?id=2225

To browse a specific page of data search:

REQUEST:

/rest/v1/prospects?page=num
/rest/v1/prospects?per_page=num
/rest/v1/prospects?status=REPLIED&page=2&per_page=30

Number of page of data search page=INT. Number of results per page per_page=INT (default=100, max=500)

To sort results:

REQUEST: 
/rest/v1/prospects?sort=[+/-]<value1> [ + ASC (default/optional) | - DESC ] 
/rest/v1/prospects?sort=-id

Sorting of data is only possible by fields below:

  • id - user id (can be used while sorting the prospects by most and least recently added)
  • last_replied - date of the mose recent response
  • status - status
  • 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 orgin of the prospect
  • state - state or geographical region of the prospect
  • country - country of the prospect
  • snippet1 .. snippet4 - custom snippet of the prospect

Custom cases - sorting by this fields requires adding another parameter:

  • last_opened - requires the activity=OPENED parameter also given
  • last_clicked - requires the activity=CLICKED parameter also given
REQUEST:
/rest/v1/prospects?activity=OPENED&sort=-last_opened
/rest/v1/prospects?activity=CLICKEd&sort=-last_clicked

To browse only the data updated after specific date (diff):

Thanks to this parameter, you can request to see the data that have been changed since any specific date

REQUEST: 
/rest/v1/prospects?diff=[type_of_changes]>YYYY-MM-dd'T'HH:mm:ssZ
/rest/v1/prospects?diff=updated>2015-09-06T12:41:42-0200

Types of changes you can monitor:

  • updated - when prospects' data were updated or changed
  • last_opened - the date of most recent opened email by a prospect (must also include the activity=OPENED parameter)
  • last_clicked - the date of most recent clicked link by a prospect (must also include the activity=CLICKED parameter)

The date format we support is: YYYY-MM-dd'T'HH:mm:ssZ.

Aliases / Shortcuts

/rest/v1/prospects/newest/ -> 100 newest prospects 
/rest/v1/prospects/replied/ -> 100 latest prospects who replied to the email
/rest/v1/prospects/opened/ -> 100 latest prospects who opened the email
/rest/v1/prospects/clicked/ -> 100 latest prospects who clicked on the email 
/rest/v1/prospects/not_contacted/ -> 100 latest prospects marked as not contacted

Browsing prospects extract !!! NERD ALERT !!!

Here is a description of Woodpecker's API that can only be understood by NERDS

campaigns_id=<id>,<id>,<id>,...
id=<id>,<id>,<id>
page=<int> 
per_page=<int> (default 100; max 500) 
status=[ ACTIVE | BOUNCED | TO-CHECK | TO-REVIEW | REPLIED | AUTOREPLIED| BLACKLIST | INVALID ]
contacted=[ off | no | false | 0 | on | yes | true | 1 ]
activity=[ OPENED | CLICKED | NOT-CLICKED | NOT-OPENED ]
interested=[ INTERESTED |NOT-INTERESTED | MAYBE-LATER | NOT_MARKED ] *
sort=[+|-][ id | last_contacted | last_replied | updated | status| email | first_name | last_name | company | industry | website | tags | title | phone | address | city | state | country| snippet1..4 | last_opened** | last_clicked** ]
diff=[ updated | last_opened | last_opened >YYYY-MM-dd'T'HH:mm:ssZ] 
search=<field_name>=<example_query>
* - needs additional campaigns_id value 
** - needs additional activity value correspondending to sort type

2. Browsing campaigns

To get campaign list:

REQUEST:
GET /rest/v1/campaign_list

[
      {
      "id": 4539,
      "name": "Campaign name",
      "status": "RUNNING",
      "from_name": "Sender name",
      "from_email": "sender@email.from",
      "created": "2016-04-11T13:14:57+0200"
   }
]

To get campaign list filtered by status:

REQUEST:
/rest/v1/campaign_list?status=RUNNING
status=enum (uppercase) [ RUNNING | PAUSED | COMPLETED | DRAFT | EDITED | STOPPED ]

To get the details of a specific campaign:

REQUEST:
/rest/v1/campaign_list?id=num num stands for campaign ID
/rest/v1/campaign_list?id=num1,num2

Sample response:

3. Adding prospects

To add prospects to the campaign:

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",
    	"snipet1":"snipet1",
    	"snipet2":"snipet2",
    	"snipet3":"snipet3",
    	"snipet4":"snipet4"
    	}
]
}
RESPONSE:
{
   "prospects":    [
      {"email": "add@email.co"}
   ],
   "status":    {
      "status": "OK",
      "code": "OK",
      "msg": "OK"
   }
}

To add prospects to the prospects list:

REQUEST:
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"
    	}
]
}

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

To edit prospect data:

NOTE: All fields mentioned in the request will be updated

REQUEST:
POST /rest/v1/add_prospects_list
{
	"update": "true",
	"prospects": [
    {
    	"id": 1125
	"email":"email@to-update.com", 
  
    	}
]
}
RESPONSE:
{
   "prospects":    [
      {
         "email": "email@to-update.com", 
         "id": 1125
      }
   ],
   "status":    {
      "status": "OK",
      "code": "OK",
      "msg": "OK"
   }
}

4. Deleting prospects

To delete prospect's data:

REQUEST:
DELETE /rest/v1/prospects?id=1
DELETE /rest/v1/prospects?id=1&campaigns_id=1

5. BLACKLISTING prospects

To change prospect status to BLACKLIST:

REQUEST:
POST /rest/v1/stop_followups
{
   "prospect":{
       "email":"add@email.co"
   }
}
RESPONSE:
{"status": {
 "status": "OK",
 "code": "OK",
 "msg": "OK:1"
}}


6. Webhooks

WebHooks Overview

Subscription URL:

https://api.woodpecker.co/rest/v1/webhooks/subscribe

Unsubscription URL:

https://api.woodpecker.co/rest/v1/webhooks/unsubscribe
Submission REQUEST:
POST -u <API_KEY> https://api.woodpecker.co/rest/v1/webhooks/subscribe\
-H Content-Type: application/json \
-d '{"target_url": "https://customer-endpoint.com/<unique_target_url>",
"event": "<event_name>"}'
Submission RESPONSE:
POST https://customer-endpoint.com/<unique_target_url> \
-H Content-Type: application/json \
-d <json result>
Supported events subscription:

a. When a prospect replies, or their status is manually changed to REPLIED
b. When a prospects clicks a link in your email 
c. When a prospect opens your email (for the first time)
d. When your email was bounced and a prospect is marked as ‘bounced’
e. When the prospect's email address is marked as ‘invalid’
f. When a prospect is marked as ‘interested’
g. When email is sent to a prospect from campaign 
h. When a prospect is marked as ‘maybe later’
i. When a prospect is marked as ‘not interested’
j. When an autoreply is detected by Woodpecker or if you manually change a prospect’s status to ‘autoreplied’
k. When you get an autoreply and you set a date to resume follow-ups

Detailed samples of results after subscribing to the events:

a. When a prospect replies, or their status is manually changed to REPLIED 
-- Event name: prospect_replied 

Sample result

{
"prospect": {
"website": "",
"city": "",
"first_name": "Name",
"last_name": ":Last",
"tags": "#TRIAL ",
"country": "",
"company": "",
"title": "",
"campaign_id": 1,
"phone": "",
"id": 2,
"last_contacted": "2016-03-09T21:05:28+0100",
"campaign_email": "send@test.com",
"status": "REPLIED",
"address": "",
"campaign_name": "test",
"email": "test@test.com",
"intrested": ""
},
"method": "prospect_replied"
}

b. When a prospects clicks a link in your email
-- Event name: link_clicked 

Sample result
{
"prospect": {
(...)
},
"click_url": "http://woodpecker.co/",
"method": "link_clicked",
"email_no": "#1"
}

c. When a prospect opens your email 
-- Event name: email_opened

Sample result

{
(...)
},
"method": "email_opened", 
"email_no": "#1" 
}

d. When your email was bounced and a prospect is marked as ‘bounced’
-- Event name: prospect_bounced

Sample result 

{
(...},
"method": "prospect_bounced"
}

e. When the prospect's email address is marked as ‘invalid’
-- Event name: prospect_invalid

Sample result 

{
(...)
},
"method": "prospect_invalid"
}

f. When a prospect is marked as ‘interested’
-- Event name: prospect_interested

Sample result

{
(...)
},
"method": "prospect_interested"
}

g. Email was sent from campaign
-- Event name: campaign_sent

Sample result

{
(...)
},
"method": "campaign_sent"
}

h. When a prospect is marked as ‘maybe later’
-- Event name: prospect_maybe_later

Sample result 

{
"prospect": {
(...)
},
"method": "prospect_maybe_later"
}

i. When a prospect is marked as ‘not interested’
-- Event name: prospect_not_interested

Sample result 

{
(...)
},
"method": "prospect_not_interested"
}

j. When an autoreply is detected by Woodpecker or if you manually change a prospect’s status to ‘autoreplied’
-- 
Event name: prospect_autoreplied

Sample result 

{
(...)
},
"method": "prospect_autoreplied"
}

k. When you get an autoreply and you set a date to resume follow-ups
-- Event name: followup_after_autoreply

Sample result 

{
(...)
},
"method": "followup_after_autoreply"
}

Integration libraries 

Node.js library by  arzynik (Devin Smith) - thank you AE Studio
https://github.com/agencyenterprise/woodpecker

RubyOnRails library by  quintasan (Michal Zajac)    
https://github.com/Quintasan/woodpecker

If you have further questions write us  integrations@woodpecker.co

Still need help? Contact Us Contact Us