Update prospects in 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 update one or multiple prospects in your global prospect list in a single request. You can update their statuses and snippet data.

Existing prospects will be updated, while new prospects that do not exist in your database will be added. The key difference between this and add prospects endpoint is the update property.

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 update and prospects[].email field is required, while all other fields are optional. If omitted, they will not be updated.

info

You can update up to 20 000 prospects per request

{
  "update": true,
  "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
`update`	boolean	Yes	This property has to be set to `true` to update prospects. Otherwise existing prospects will return `E_DUPLICATE` code
`file_name`	string	No	Name of the import batch, visible in the `imported` column. If not specified, it will clear the existing values
`[].prospects`	object	Yes	Contains prospect data, there can be multiple prospects
└─ `email`	string	Yes	Prospect's email address
└─ `status`	string	No	Prospect's status. Available statuses: `ACTIVE`, `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

Request sample

Update prospects

The example below showcases how to update 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 '{
    "update": true,
    "prospects": [
      {
        "email": "jared@piedpiper.com",
        "snippet1": "New snippet value"
      },
      {
        "email": "erlich@bachman.com",
        "snippet1": "New 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 = """
      {
        "update": true,
        "prospects": [
          {
            "email": "jared@piedpiper.com",
            "snippet1": "New snippet value"
          },
          {
            "email": "erlich@bachman.com",
            "snippet1": "New 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 fetch = require("node-fetch");

const apiUrl = "https://api.woodpecker.co/rest/v1/add_prospects_list";
const apiKey = "YOUR_API_KEY";

const requestBody = {
  update: true,
  prospects: [
    {
      email: "jared@piedpiper.com",
      snippet1: "New snippet value",
    },
    {
      email: "erlich@bachman.com",
      snippet1: "New snippet value",
    },
  ],
};

const updateProspects = async () => {
  try {
    const response = await fetch(apiUrl, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": apiKey,
      },
      body: JSON.stringify(requestBody),
    });

    const responseData = await response.json();
    console.log("Response Code:", response.status);
    console.log("Response Body:", responseData);
  } catch (error) {
    console.error("Error:", error);
  }
};

updateProspects();

Response

Response examples

All prospects have been updated. Any prospect that did not previously exist has 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 of a 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 updated or added to the prospect list. Any prospects that could not be updated are returned with an appropriate error description.

{
  "prospects": [
    {
      "email": "jared@piedpiper.com",
      "id": 1091123456
    },
    {
      "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 of a prospect
└─`[].status`	string/null	`ERROR`. Returned if the prospect has not been updated
└─`[].code`	string/null	Code indicating the error category. Returned if the prospect has not been updated
└─`[].msg`	string/null	Descriptive error message. Returned if the prospect has not been updated
`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 updated

{
  "prospects": [
    {
      "email": "jared@piedpiper.com",
      "id": 1091123456,
      "status": "ERROR",
      "code": "E_INV_STATUS",
      "msg": "Status unknown."
    },
    {
      "email": "erlichbachman.com",
      "status": "ERROR",
      "code": "E_EMAIL",
      "msg": "This looks like invalid email format: erlichbachman.com"
    }
  ],
  "status": {
    "status": "ERROR",
    "code": "E_EMAIL",
    "msg": "Emails could not be added."
  }
}