Get prospect responses

Retrieve a list of responses from a specified prospect. You can get a list of all responses or filter them by campaign.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/prospects/{prospect_id}/responses

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

Parameter	Required	Description
campaign_id	No	One or more campaign IDs separated by commas. Used to filter results by specific campaigns.

Request sample

Retrieve all responses from a specified prospect

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/prospects/{prospect_id}/responses" \
  --header "x-api-key: {YOUR_API_KEY}"

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY";
    String prospectId = "your_prospect_id";
    String urlString = "https://api.woodpecker.co/rest/v2/prospects/" + prospectId + "/responses";

    try {
      URL url = new URL(urlString);
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();

      connection.setRequestMethod("GET");
      connection.setRequestProperty("x-api-key", apiKey);

      int responseCode = connection.getResponseCode();
      System.out.println("Response Code: " + responseCode);

      if (responseCode == HttpURLConnection.HTTP_OK) {
        BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();

        while ((inputLine = in.readLine()) != null) {
          response.append(inputLine);
        }
        in.close();

        System.out.println("Response: " + response.toString());
      } else {
        System.out.println("GET request failed.");
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const apiKey = "YOUR_API_KEY";
const prospectId = "your_prospect_id";
const url = `https://api.woodpecker.co/rest/v2/prospects/${prospectId}/responses`;

fetch(url, {
  method: "GET",
  headers: {
    "x-api-key": apiKey,
  },
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then((data) => {
    console.log("Response:", data);
  })
  .catch((error) => {
    console.error("Error:", error);
  });

Response

Response examples

200

A list of responses from a specified prospect sorted by delivered ascending. If the prospect exists in your database but has not replied to an email, or if their response was deleted, the responses[] array will be empty

{
  "prospect_id": 123456789,
  "email": "jared.dunn@piedpiper.com",
  "responses": [
    {
      "response_id": 147258369,
      "campaign_id": 17654321,
      "step": 2,
      "campaign_email_sent": 2,
      "subject": "Re: What about Pied Piper?",
      "message": "<div>This is a reply in HTML format.</div>",
      "delivered": "2024-11-09T14:29:06",
      "secondary_prospect_email": "erlich@bachmanity.com"
    },
    {
      "response_id": 258369147,
      "campaign_id": 1957395,
      "step": 1,
      "campaign_email_sent": 1,
      "subject": "Re: Did you hear about world's best startup, Aviato?",
      "message": "<div>Yes and I would like to hear more!</div>",
      "delivered": "2024-12-03T07:29:06",
      "secondary_prospect_email": null
    }
  ]
}

Response body schema

Field	Type	Description
prospect_id	integer	Unique ID of the prospect
email	string	Email address of the prospect
responses	array	Array of email responses from the prospect
└─ response_id	integer	Unique ID of the response
└─ campaign_id	integer	ID of the campaign associated a response
└─ step	integer	Campaign step number that triggered the response
└─ campaign_email_sent	integer	Number of campaign emails sent before this response
└─ subject	string	Subject line of the response
└─ message	string	Body of the response email in HTML format
└─ delivered	datetime	Timestamp when the response was received. YYYY-MM-DDTHH:MM:SS Europe/Warsaw time
└─ secondary_prospect_email	string / null	Email address of the respondent if the response came from a different email address than the prospect's

400

Invalid request parameters or malformed request syntax

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Value of campaign_id is incorrect.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

401

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

404

1. Prospect ID doesn't exist in your database

   Status: 404
   Body: none

2. Incorrect URL

   {
     "title": "Not Found",
     "status": 404,
     "detail": "Requested resource does not exist",
     "timestamp": "2025-03-05 17:57:00"
   }

500

Unknown error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC