🐦 A Woodpecker Javascript API
Switch branches/tags
Clone or download
Latest commit 66a5f17 Oct 18, 2017
Permalink
Failed to load latest commit information.
test removed debug Oct 18, 2017
.editorconfig added prospect editing Oct 18, 2017
.gitignore test stuff Oct 18, 2017
.travis.yml fixed test Oct 18, 2017
README.md added webhook subscriptions Oct 18, 2017
package-lock.json renamed package Oct 18, 2017
package.json version up Oct 18, 2017
woodpecker.js fix tests Oct 18, 2017

README.md

Woodpecker.co API

npm package

Build status Coverage Dependency Status


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: 'mrtest@somedomain.com'
}, 2034)

To add prospects to the prospects list:

Woodpecker.prospects().add([{
  firstName: 'mr',
  lastName: 'mr test',
  email: 'mrtest@somedomain.com'
},{
  firstName: 'mrs',
  lastName: 'mrs test',
  email: 'mrstest@somedomain.com'
}])

To edit prospect data:

Woodpecker.prospects().edit({
  firstName: 'mr',
  lastName: 'mr test',
  email: 'mrtest@somedomain.com'
})

To delete the prospect data:

Woodpecker.prospects().delete('mrtest@somedomain.com')

To delete the prospect from a campaign:

Woodpecker.prospects().delete('mrtest@somedomain.com', 2034)

To change prospect status to BLACKLIST:

Woodpecker.prospects().blacklist('mrtest@somedomain.com')

To subscribe to a webhook event

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