Woodpecker.co API Client

Common errors

• Error: You must provide an API Key.

  cause The Woodpecker API client factory function was called without a valid API key string.
  fix Initialize the client by passing your Woodpecker API key as a string: `const Woodpecker = require('woodpecker-api')('YOUR_API_KEY');`

• TypeError: Woodpecker.prospects is not a function

  cause The `prospects` accessor was treated as a property directly exposing methods, instead of a method that returns a query builder object.
  fix Invoke `prospects()` as a method to get the query builder: `Woodpecker.prospects().find(...)`

• Request failed with status code 400 - limit cannot exceed 500

  cause A `find` query was made with the `$limit` parameter set to a value greater than 500.
  fix Reduce the `$limit` parameter to 500 or less. For retrieving larger datasets, implement client-side pagination by making multiple requests and incrementing the `$page` or `$skip` parameter.

Warnings

• gotcha The Woodpecker API documentation might contain discrepancies regarding field names. For example, the official docs might refer to `second_name`, but this client library correctly maps it to `lastName` for prospect searches.
  Fix: Always use `lastName` when querying for prospect last names via this client library.
• gotcha An API key is mandatory for all interactions. The client factory function must be invoked with a valid key immediately upon import, or API requests will fail.
  Fix: Ensure `require('woodpecker-api')(process.env.WOODPECKER_API_KEY)` is called with a valid API key, preferably loaded from environment variables for security and flexibility.
• gotcha Pagination limits exist for `find` queries. The `$limit` parameter has a maximum value of `500`. Attempts to request more than 500 records per page will result in an API error.
  Fix: Implement client-side pagination logic to fetch data in chunks of 500 or less, iterating through `$page` or adjusting `$skip` parameters for larger datasets.
• gotcha The library exclusively uses JavaScript Promises for all asynchronous operations. Developers must handle results using `.then()`/`.catch()` or `async`/`await` syntax.
  Fix: Always wrap API calls in `try...catch` blocks when using `async/await` or attach `.catch()` handlers to Promise chains to properly manage errors.

Install

• npm install woodpecker-api npm
• yarn add woodpecker-api yarn
• pnpm add woodpecker-api pnpm

Imports

• WoodpeckerClientFactory
  wrong:

  import WoodpeckerClientFactory from 'woodpecker-api';

  correct:

  const WoodpeckerClientFactory = require('woodpecker-api');

  This imports the factory function. You must then call it with your API key to get the actual client instance.
• WoodpeckerClientInstance
  wrong:

  const Woodpecker = require('woodpecker-api');

  correct:

  const Woodpecker = require('woodpecker-api')(process.env.WOODPECKER_API_KEY);

  The imported factory function requires immediate invocation with your Woodpecker API key to instantiate the client. This library is designed for CommonJS.
• resource methods (e.g., prospects)
  wrong:

  Woodpecker.prospects.find(...)

  correct:

  Woodpecker.prospects().find(...)

  Resource accessors like `prospects()` are methods that return a chainable query builder object; they are not properties that directly expose methods.

Quickstart

This quickstart demonstrates how to initialize the Woodpecker API client, find prospects by various criteria, and access specialized lists like 'newest' and 'replied' prospects, including robust error handling.

const Woodpecker = require('woodpecker-api')(process.env.WOODPECKER_API_KEY ?? '');

async function fetchAndManageProspects() {
  if (!process.env.WOODPECKER_API_KEY) {
    console.error('Error: WOODPECKER_API_KEY environment variable is not set.');
    console.error('Please set it before running the script.');
    return;
  }

  try {
    // Find prospects named 'd' with a limit of 1
    console.log('Searching for prospects with first name "d"...');
    const results = await Woodpecker.prospects()
      .find({
        firstName: 'd',
        $limit: 1
      });

    console.log('Found Prospect(s):', JSON.stringify(results, null, 2));

    if (results && results.length > 0) {
      const firstProspectId = results[0].id;
      console.log(`\nAttempting to retrieve newest prospects...`);
      const newest = await Woodpecker.prospects().newest();
      console.log(`Retrieved ${newest.length} newest prospects.`);

      // Example: Find 100 prospects who replied (if applicable)
      // Note: This often requires specific campaign context for real-world use.
      console.log('\nAttempting to retrieve replied prospects (if any)...');
      const replied = await Woodpecker.prospects().replied();
      console.log(`Retrieved ${replied.length} replied prospects.`);
    } else {
      console.log('No prospects found matching the initial search criteria.');
    }

  } catch (e) {
    console.error('\nAn error occurred during API interaction:');
    if (e.response && e.response.data) {
      console.error('API Error Details:', JSON.stringify(e.response.data, null, 2));
    } else {
      console.error(e.message);
    }
  }
}

fetchAndManageProspects();