Add prospects to database

warning

This is a v1 legacy endpoint. It uses a different path /rest/v1 and may return different error codes and response formats compared to v2. While it remains functional, consider handling errors accordingly.

This endpoint allows you to add one or multiple prospects to your global prospect list in a single request. Prospects will not be enrolled in any campaign but will be available in your account for further actions.

If a prospect already exists, their data will remain unchanged. To update prospect data, see this guide.

Request

Endpoint

POST https://api.woodpecker.co/rest/v1/add_prospects_list

Headers

x-api-key: {YOUR_API_KEY}
Content-type: application/json

For details on how to authenticate your requests, please see the authentication guide.

Body

The example below shows all available fields. The prospects[].email field is required, while all other fields are optional. If omitted, they will remain blank.

info

You can add up to 20 000 prospects per request

{
  "file_name": "API import YYYY-MM-DD",
  "prospects": [
    {
      "email": "erlich@bachman.com",
      "status": "ACTIVE",
      "first_name": "Erlich",
      "last_name": "Bachman",
      "company": "Bachmanity",
      "website": "http://www.bachmanity.com/",
      "linkedin_url": "https://www.linkedin.com/in/erlich-bachman/",
      "tags": "#VC",
      "title": "VC Angel",
      "phone": "111222333",
      "address": "221 Newell Rd",
      "city": "Palo Alto",
      "state": "California",
      "country": "USA",
      "industry": "Software as a Service",
      "snippet1": "Pied Piper board member",
      "snippet2": "A personalized sentence <br/> in two lines",
      "snippet3": "string",
      "snippet4": "string",
      "snippet5": "string",
      "snippet6": "string",
      "snippet7": "string",
      "snippet8": "string",
      "snippet9": "string",
      "snippet10": "string",
      "snippet11": "string",
      "snippet12": "string",
      "snippet13": "string",
      "snippet14": "string",
      "snippet15": "string"
    }
  ]
}

Body schema

Field	Type	Required	Description
`[].prospects`	object	Yes	Contains prospect data, there can be multiple prospects
└─ `email`	string	Yes	Prospect's email address
└─ `status`	string	No	Prospect's status. By default the status is set to `ACTIVE`. Other available: `BLACKLIST`, `BOUNCED`, `INVALID`, `REPLIED`
└─ `first_name`	string	No	Prospect's first name
└─ `last_name`	string	No	Prospect's last name
└─ `company`	string	No	Prospect's company name
└─ `website`	string	No	Prospect's website URL
└─ `linkedin_url`	string	No	Prospect's LinkedIn profile URL
└─ `tags`	string	No	Tags associated with the prospect. Tags start with a `#` and are separated with a space
└─ `title`	string	No	Prospect's job title
└─ `phone`	string	No	Prospect's phone number
└─ `address`	string	No	Prospect's address
└─ `city`	string	No	Prospect's city
└─ `country`	string	No	Prospect's country
└─ `snippet`	string	No	Prospect custom snippets. There are 15 snippet fields (`snippet1` to `snippet15`)
└─ `industry`	string	No	Prospect's industry
└─ `state`	string	No	Prospect's state or region
`file_name`	string	No	Name of the import batch, visible in the `imported` column

Request sample

Add prospects

The example below showcases how to add multiple prospects only with selected snippets.

cURL
Java
Node.js

curl --request POST \
  --url "https://api.woodpecker.co/rest/v1/add_prospects_list" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "prospects": [
      {
        "email": "jared@piedpiper.com",
        "first_name": "Jared",
        "last_name": "Dunn",
        "company": "Pied Piper",
        "snippet1": "Custom snippet value"
      },
      {
        "email": "erlich@bachman.com",
        "first_name": "Erlich",
        "last_name": "Bachman",
        "company": "Aviato",
        "snippet1": "Custom snippet value"
      }
    ]
  }'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    String apiUrl = "https://api.woodpecker.co/rest/v1/add_prospects_list";
    String apiKey = "YOUR_API_KEY";

    String jsonBody = """
      {
        "prospects": [
          {
            "email": "jared@piedpiper.com",
            "first_name": "Jared",
            "last_name": "Dunn",
            "company": "Pied Piper",
            "snippet1": "Custom snippet value"
          },
          {
            "email": "erlich@bachman.com",
            "first_name": "Erlich",
            "last_name": "Bachman",
            "company": "Aviato",
            "snippet1": "Custom snippet value"
          }
        ]
      }
      """;

    HttpClient httpClient = HttpClient.newHttpClient();

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(apiUrl))
      .header("Content-Type", "application/json")
      .header("x-api-key", apiKey)
      .POST(HttpRequest.BodyPublishers.ofString(jsonBody, StandardCharsets.UTF_8))
      .build();

    try {
      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println("Response Code: " + response.statusCode());
      System.out.println("Response Body: " + response.body());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

const axios = require("axios");

const API_URL = "https://api.woodpecker.co/rest/v1/add_prospects_list";
const API_KEY = "YOUR_API_KEY";

const requestBody = {
  prospects: [
    {
      email: "jared@piedpiper.com",
      first_name: "Jared",
      last_name: "Dunn",
      company: "Pied Piper",
      snippet1: "Custom snippet value",
    },
    {
      email: "erlich@bachman.com",
      first_name: "Erlich",
      last_name: "Bachman",
      company: "Aviato",
      snippet1: "Custom snippet value",
    },
  ],
};

async function addProspects() {
  try {
    const response = await axios.post(API_URL, requestBody, {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": API_KEY,
      },
    });

    console.log("Response Code:", response.status);
    console.log("Response Body:", response.data);
  } catch (error) {
    console.error("Error:", error.response ? error.response.data : error.message);
  }
}

addProspects();

Response

Response examples

All prospects have been added to the prospect list.

{
  "prospects": [
    {
      "email": "jared@piedpiper.com",
      "id": 1091123456
    },
    {
      "email": "erlich@bachman.com", 
      "id": 1091123457
    }
  ],
  "status": {
    "status": "OK",
    "code": "OK",
    "msg": "OK"
  }
}

Body schema

Field	Data Type	Description
`prospects`	array[object]	An array of prospects added to the prospect list
└─`[].email`	string	Prospect's email
└─`[].id`	integer	Unique ID assigned to the prospect
`status`	object	Object containing the status details of the request
└─`status`	string	General status message
└─`code`	string	Code indicating the error category
└─`msg`	string	Error message

At least one prospect has been added to the prospect list. Any duplicates or prospects that could not be added are returned with an appropriate error description.

{
  "prospects": [
    {
      "email": "erlich.bachman@bachman.com",
      "id": 1091123458
    },
    {
      "email": "jared@piedpiper.com",
      "id": 1091123456,
      "status": "ERROR",
      "code": "E_DUPLICATE",
      "msg": "Duplicate. The prospect has been added to your prospect base before."
    },
    {
      "email": "erlichbachman.com",
      "status": "ERROR",
      "code": "E_EMAIL",
      "msg": "This looks like invalid email format: erlichbachman.com"
    }
  ],
  "status": {
    "status": "OK",
    "code": "OK",
    "msg": "OK"
  }
}

Body schema

Field	Data Type	Description
`prospects`	array[object]	An array of processed prospects
└─`[].email`	string	Prospect's email
└─`[].id`	integer/null	Unique ID assigned to the prospect if successfully added. For duplicates, returns the ID of the existing prospect
└─`[].status`	string/null	`ERROR`. Returned if the prospect has not been added
└─`[].code`	string/null	Code indicating the error category. Returned if the prospect has not been added
└─`[].msg`	string/null	Descriptive error message. Returned if the prospect has not been added
`status`	object	Object containing the status details of the request
└─`status`	string	General status message
└─`code`	string	Code indicating the error category
└─`msg`	string	Error message

None of the requested prospects have been added to the prospect list

{
  "prospects": [
    {
      "email": "jared@piedpiper.com",
      "id": 1091123456,
      "status": "ERROR",
      "code": "E_DUPLICATE",
      "msg": "Duplicate. The prospect has been added to your prospect base before."
    },
    {
      "email": "erlichbachman.com",
      "status": "ERROR",
      "code": "E_EMAIL",
      "msg": "This looks like invalid email format: erlichbachman.com"
    }
  ],
  "status": {
    "status": "ERROR",
    "code": "E_DUPLICATE",
    "msg": "Duplicate. The prospect has been added to your prospect base before."
  }
}