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}"

Python

import requests

def getProspectResponses(prospect_id):
  url = f"https://api.woodpecker.co/rest/v2/prospects/{prospect_id}/responses"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }

  response = requests.get(url, headers=headers)

  if response.status_code == 200:
    print("GET successful:", response.json())
  else:
    print("GET failed with status:", response.status_code)

if __name__ == "__main__":
  getProspectResponses(7890)  # Example prospect ID

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class WoodpeckerApiClient {
  private static final String API_KEY = "{YOUR_API_KEY}";

  public static void main(String[] args) {
    int prospectId = 7890; // Example prospect ID
    getProspectResponses(prospectId);
  }

  public static void getProspectResponses(int prospectId) {
    try {
      String url = "https://api.woodpecker.co/rest/v2/prospects/" + prospectId + "/responses";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(new URI(url))
        .header("x-api-key", API_KEY)
        .GET()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

      if (response.statusCode() == 200) {
        System.out.println("GET response: " + response.body());
      } else {
        System.err.println("GET request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require("axios");

async function getProspectResponses(prospectId) {
  const url = `https://api.woodpecker.co/rest/v2/prospects/${prospectId}/responses`;
  const headers = {
    "x-api-key": "{YOUR_API_KEY}"
  };

  try {
    const response = await axios.get(url, { headers: headers });

    if (response.status === 200) {
      console.log("GET successful:", response.data);
    } else {
      console.error("GET failed with status:", response.status);
    }
  } catch (error) {
    console.error("Request error:", error.response?.status || error.message);
  }
}

getProspectResponses(7890); // Example prospect ID

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 to 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