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

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 want to upgrade, contact support@woodpecker.co.

How to generate an API Key?

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

Log into your Woodpecker account on app.woodpecker.co.
Go to Settings > API Keys.
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

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

Old API Docs

Overview

How to generate an API Key?

EndpointsAuthentication

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:

RESPONSE: (sample record)

To get the list of prospects with additional information:

REQUEST:

RESPONSE: (sample record)

To browse prospects from specific campaigns:

REQUEST:

RESPONSE:

To browse prospects of a specific status:

REQUEST:

REQUEST:

To browse prospects that performed a specific action:

REQUEST:

To browse interest rate:

REQUEST:

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

REQUEST:

To browse results of prospects search:

REQUEST:

Field types available:

To browse data of a specific prospect:

REQUEST:

To browse a specific page of data search:

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

To sort results:

REQUEST:

REQUEST:

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

REQUEST:

Aliases / Shortcuts

Browsing prospects extract !!! NERD ALERT !!!

2. Browsing campaigns

To get campaign list:

REQUEST:

To get campaign list filtered by status:

REQUEST:

To get the details of a specific campaign:

REQUEST:

Sample response:

3. Adding prospects

To add prospects to the campaign:

REQUEST:

RESPONSE:

To add prospects to the prospects list:

REQUEST:

RESPONSE:

To edit prospect data:

REQUEST:

RESPONSE:

4. Deleting prospects

To delete prospect's data:

REQUEST:

5. BLACKLISTING prospects

To change prospect status to BLACKLIST:

REQUEST:

RESPONSE:

6. Webhooks

WebHooks Overview

Submission REQUEST:

Submission RESPONSE:

Supported events subscription:

Detailed samples of results after subscribing to the events:

Sample result

Sample result

Integration libraries

Contact Us

Endpoints
Authentication

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