woodpecker-api

Woodpecker.co API

---

Getting Started

You will first need a Woodpecker account, and your API key. See the Woodpecker API docs here. http://help.woodpecker.co/article/16-api-docs.

Installation

npm i woodpecker-api

Usage

The API uses Promises for all interaction.

const Woodpecker = require('woodpecker-api')('KEY')
 
Woodpecker.prospects()
  .find({
    firstName: 'd',
    $limit: 1
  })
  .then(d => {
    console.log(d)
  })
  .catch(e => {
    console.log(e)
  })

---

API Reference

prospects().find({query})

• id: Find by id
• ids: Find by an array of ids
• campaign: Find by a specific campaign_id
• campaigns: Find by an array of campaign_ids
• status: Find by prospect status. Valid values: ACTIVE | BLACKLIST | AUTOREPLIED | TO-CHECK | TO-REVIEW | BOUNCED | INVALID | REPLIED
• activity: Find by prospect action. Valid values: OPENED | NOT-OPENED | CLICKED | NOT-CLICKED
• interest: Find by prospect interest. Valid values: INTERESTED | NOT-INTERESTED | MAYBE-LATER | NOT-MARKED
• updated: Find where dates are greater then or less than an updated date. Accepts a diff object {op: '<', date: new Date} or a string >2017-01-01.
• opened: Find where dates are greater then or less than an opened date. Accepts a diff object {op: '<', date: new Date} or a string >2017-01-01.
• clicked: Find where dates are greater then or less than a clicked date. Accepts a diff object {op: '<', date: new Date} or a string >2017-01-01.
• contacted: If the user has been contacted or not. true or false
• firstName: Search within the prospects first_name
• lastName: Search within the prospects last_name. note that the Woodpecker docs are incorrect. second_name is invalid.
• email: Search within the prospects email
• company: Search within the prospects company
• industry: Search within the prospects industry
• website: Search within the prospects website
• tags: Search within the prospects tags
• title: Search within the prospects title
• phone: Search within the prospects phone
• address: Search within the prospects address
• city: Search within the prospects city
• state: Search within the prospects state
• country: Search within the prospects country
• snippet1: Search within the prospects snippet1. Can use snippet1 up to snippet15
• $limit: Sets the maximum results per page. Defaults to 100, max of 500
• $page: The page to display
• $skip: Amount of results to skip. To be used with $limit instead of $page
• $sort: Sort order object. Can be 1, ASC | true | +, or -1, DESC | false | -. Defaults to ASC. Available fields:
  • id, firstName, lastName, replied, status, updated, email, company, industry, website, tags, title, phone, address, city, state, country, opened (requires activity.OPENED), clicked (requires activity.CLICKED)

prospects().newest()

• 100 newest prospects

prospects().replied()

• 100 latest prospects who replied to the email

prospects().opened()

• 100 latest prospects who opened the email

prospects().clicked()

• 100 latest prospects who clicked on the email`

prospects().notContacted()

• 100 latest prospects marked as not contacted

prospects().add(PROSPECT | [PROSPECT])

• Accepts either a single prospect or an array of prospects. Available fields: firstName, lastName, email, company, industry, website, tags, title, phone, address, city, state, country, snippet[1-15]

prospects().edit(PROSPECT | [PROSPECT])

• Same as add, but will perform an update if they items exist. Requires id for each prospect. All fields mentioned in the request will be updated.

prospects().delete(ID | EMAIL)

• Deletes a prospect by id or email

prospects().blacklist(ID | EMAIL)

• Blacklists a prospect by id or email

campaigns().find({query})

• id: Find by id
• ids: Find by an array of ids
• status: Find by specific status. Valid values: RUNNING | PAUSED | COMPLETED | DRAFT | EDITED | STOPPED

webhooks().subscribe(URL, EVENT)

• Subscribes to an event for the given URL and EVENT. Valid event values: REPLIED, CLICKED, OPENED, BOUNCED, INVALID, INTERESTED, MAYBE-LATER, NOT-INTERESTED, AUTOREPLIED, FOLLOWUP

webhooks().unsubscribe(URL, EVENT)

• Same as above, but unsubscribes

---

Examples

To get the list of prospects:

Woodpecker.prospects().find()

To browse prospects from specific campaigns:

Woodpecker.prospects()
  .find({
    campaign: 1
  })
 
Woodpecker.prospects()
  .find({
    campaigns: [1,2,3]
  })

To browse prospects of a specific status:

Woodpecker.prospects()
  .find({
    status: Woodpecker.prospectStatus.REPLIED
  })
 
Woodpecker.prospects()
  .find({
    campaign: 22,
    status: Woodpecker.prospectStatus['TO-CHECK']
  })

To browse prospects that performed a specific action:

Woodpecker.prospects()
  .find({
    activity: Woodpecker.activity.OPENED
  })
 
Woodpecker.prospects()
  .find({
    activity: Woodpecker.activity.OPENED,
    status: Woodpecker.status.REPLIED
  })

To browse interest rate:

Woodpecker.prospects()
  .find({
    campaign: 10074,
    interest: Woodpecker.interest.INTERESTED
  })

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

Woodpecker.prospects()
  .find({
    contacted: false
  })

To browse results of prospects search:

Woodpecker.prospects()
  .find({
    firstName: 'devin',
    lastName: 'smith',
    email: '',
    company: '',
    industry: '',
    website: '',
    tags: '',
    title: '',
    phone: '',
    address: '',
    city: '',
    state: '',
    country: ''
  })

To browse data of a specific prospect:

Woodpecker.prospects()
  .find({
    id: 2225
  })

To browse a specific page of data search:

Woodpecker.prospects()
  .find({
    $page: 2
  })
Woodpecker.prospects()
  .find({
    $limit: 20
  })
Woodpecker.prospects()
  .find({
    $skip: 100
  })
Woodpecker.prospects()
  .find({
    $page: 2,
    $limit: 20,
    status: Woodpecker.prospectStatus.REPLIED
  })

To sort results:

Woodpecker.prospects()
  .find({
    firstName: 'devin',
    sort: '+first_name,+id,+country',
  })
 
Woodpecker.prospects()
  .find({
    firstName: 'devin',
    $sort: {
      id: 1,
      firstName: -1,
      lastName: -1
    }
  })

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

Woodpecker.prospects()
  .find({
    updated: {
      op: '>',
      date: new Date
    }
  })
 
Woodpecker.prospects()
  .find({
    opened: '>2017-01-01'
  })

Aliases / Shortcuts

Woodpecker.prospects().newest()
 
Woodpecker.prospects().replied()
 
Woodpecker.prospects().opened()
 
Woodpecker.prospects().clicked()
 
Woodpecker.prospects().notContacted()

To get campaign list:

Woodpecker.campaigns().find()

To get campaign list filtered by status:

Woodpecker.campaigns()
  .find({
    status: Woodpecker.campaignStatus.RUNNING
  })

To get the details of a specific campaign:

Woodpecker.campaigns()
  .find({
    id: 1
  })
 
Woodpecker.campaigns()
  .find({
    ids: [1,2]
  })

To add prospects to the campaign:

Woodpecker.prospects().add({
  firstName: 'mr',
  lastName: 'mr test',
  email: '[e-mail]'
}, 2034)

To add prospects to the prospects list:

Woodpecker.prospects().add([{
  firstName: 'mr',
  lastName: 'mr test',
  email: '[e-mail]'
},{
  firstName: 'mrs',
  lastName: 'mrs test',
  email: '[e-mail]'
}])

To edit prospect data:

Woodpecker.prospects().edit({
  firstName: 'mr',
  lastName: 'mr test',
  email: '[e-mail]'
})

To delete the prospect data:

Woodpecker.prospects().delete('[e-mail]')

To delete the prospect from a campaign:

Woodpecker.prospects().delete('[e-mail]', 2034)

To change prospect status to BLACKLIST:

Woodpecker.prospects().blacklist('[e-mail]')

To subscribe to a webhook event

Woodpecker.webhooks().subscribe('https://domain/page', Woodpecker.webhookEvent.REPLIED)