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