{"id":16276,"library":"woodpecker-api","title":"Woodpecker.co API Client","description":"The `woodpecker-api` package provides a Promise-based JavaScript client for interacting with the Woodpecker.co email outreach platform's API. It abstracts the underlying HTTP requests, offering a fluent interface for managing prospects, campaigns, and other Woodpecker resources directly from a Node.js application. The current stable version is 1.1.0, and releases appear to be feature-driven rather than on a fixed cadence, with recent updates introducing functionalities such as prospect editing, blacklisting, and webhook subscriptions. A key differentiator of this library is its role as a thin, unopinionated wrapper around the official Woodpecker API, designed to simplify asynchronous operations through the use of Promises. To utilize the library, developers must obtain and provide a valid API key from their Woodpecker.co account dashboard. It primarily targets CommonJS environments, requiring a specific factory function invocation pattern for client instantiation.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/agencyenterprise/woodpecker","tags":["javascript"],"install":[{"cmd":"npm install woodpecker-api","lang":"bash","label":"npm"},{"cmd":"yarn add woodpecker-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add woodpecker-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This imports the factory function. You must then call it with your API key to get the actual client instance.","wrong":"import WoodpeckerClientFactory from 'woodpecker-api';","symbol":"WoodpeckerClientFactory","correct":"const WoodpeckerClientFactory = require('woodpecker-api');"},{"note":"The imported factory function requires immediate invocation with your Woodpecker API key to instantiate the client. This library is designed for CommonJS.","wrong":"const Woodpecker = require('woodpecker-api');","symbol":"WoodpeckerClientInstance","correct":"const Woodpecker = require('woodpecker-api')(process.env.WOODPECKER_API_KEY);"},{"note":"Resource accessors like `prospects()` are methods that return a chainable query builder object; they are not properties that directly expose methods.","wrong":"Woodpecker.prospects.find(...)","symbol":"resource methods (e.g., prospects)","correct":"Woodpecker.prospects().find(...)"}],"quickstart":{"code":"const Woodpecker = require('woodpecker-api')(process.env.WOODPECKER_API_KEY ?? '');\n\nasync function fetchAndManageProspects() {\n  if (!process.env.WOODPECKER_API_KEY) {\n    console.error('Error: WOODPECKER_API_KEY environment variable is not set.');\n    console.error('Please set it before running the script.');\n    return;\n  }\n\n  try {\n    // Find prospects named 'd' with a limit of 1\n    console.log('Searching for prospects with first name \"d\"...');\n    const results = await Woodpecker.prospects()\n      .find({\n        firstName: 'd',\n        $limit: 1\n      });\n\n    console.log('Found Prospect(s):', JSON.stringify(results, null, 2));\n\n    if (results && results.length > 0) {\n      const firstProspectId = results[0].id;\n      console.log(`\\nAttempting to retrieve newest prospects...`);\n      const newest = await Woodpecker.prospects().newest();\n      console.log(`Retrieved ${newest.length} newest prospects.`);\n\n      // Example: Find 100 prospects who replied (if applicable)\n      // Note: This often requires specific campaign context for real-world use.\n      console.log('\\nAttempting to retrieve replied prospects (if any)...');\n      const replied = await Woodpecker.prospects().replied();\n      console.log(`Retrieved ${replied.length} replied prospects.`);\n    } else {\n      console.log('No prospects found matching the initial search criteria.');\n    }\n\n  } catch (e) {\n    console.error('\\nAn error occurred during API interaction:');\n    if (e.response && e.response.data) {\n      console.error('API Error Details:', JSON.stringify(e.response.data, null, 2));\n    } else {\n      console.error(e.message);\n    }\n  }\n}\n\nfetchAndManageProspects();","lang":"javascript","description":"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."},"warnings":[{"fix":"Always use `lastName` when querying for prospect last names via this client library.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always wrap API calls in `try...catch` blocks when using `async/await` or attach `.catch()` handlers to Promise chains to properly manage errors.","message":"The library exclusively uses JavaScript Promises for all asynchronous operations. Developers must handle results using `.then()`/`.catch()` or `async`/`await` syntax.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Initialize the client by passing your Woodpecker API key as a string: `const Woodpecker = require('woodpecker-api')('YOUR_API_KEY');`","cause":"The Woodpecker API client factory function was called without a valid API key string.","error":"Error: You must provide an API Key."},{"fix":"Invoke `prospects()` as a method to get the query builder: `Woodpecker.prospects().find(...)`","cause":"The `prospects` accessor was treated as a property directly exposing methods, instead of a method that returns a query builder object.","error":"TypeError: Woodpecker.prospects is not a function"},{"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.","cause":"A `find` query was made with the `$limit` parameter set to a value greater than 500.","error":"Request failed with status code 400 - limit cannot exceed 500"}],"ecosystem":"npm"}