Skip to main content

Add prospects to a campaign

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 a campaign prospect list in a single request. Any prospect whose current global status is not ACTIVE (e.g., REPLIED, BOUNCED) will be automatically rejected unless overridden using the 'force' parameter. Duplicate records will return an appropriate message.

  • You can add an existing prospect from the global prospect list to a campaign without modifying their data (snippets). To update their information, see this guide
  • You can add a prospect directly to a campaign - this will also create a record in the global prospect list.

Request​

Endpoint​

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

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 and campaign.campaign_id fields are required, while all other fields are optional. If omitted, these fields will remain blank for new prospects. For existing prospects in your global database, their stored data (snippets) will be used.

info

You can add up to 20 000 prospects per request

{
  "campaign": {
    "campaign_id": 1234567,
    "send_after": "2025-04-01T00:01:01-0000"
  },
  "force": false,
  "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​

FieldTypeRequiredDescription
campaignobjectYesContains campaign data
  └─campaign_idintegerYesCampaign ID to which prospects will be added
  └─send_afterstringNoThe earliest date and time prospects can be contacted. Use %2B for + in the timezone (ISO 8601-like format)
forcebooleanNoUse with caution. Whether to add prospects to a campaign, even if their global status is other than ACTIVE. If true, prospects may be contacted again, even if they have responded in another campaign or opted out.
file_namestringNoName of the import batch, visible in the imported column
[].prospectsobjectYesContains prospect data, there can be multiple prospects
  └─ emailstringYesProspect's email address
  └─ statusstringNoProspect's status. By default the status is set to ACTIVE. Other available: PAUSED, TO-REVIEW, TO-CHECK; available with force: BLACKLIST, BOUNCED, INVALID, REPLIED
  └─ first_namestringNoProspect's first name
  └─ last_namestringNoProspect's last name
  └─ companystringNoProspect's company name
  └─ websitestringNoProspect's website URL
  └─ linkedin_urlstringNoProspect's LinkedIn profile URL
  └─ tagsstringNoTags associated with the prospect. Tags start with a # and are separated with a space
  └─ titlestringNoProspect's job title
  └─ phonestringNoProspect's phone number
  └─ addressstringNoProspect's address
  └─ citystringNoProspect's city
  └─ countrystringNoProspect's country
  └─ snippetstringNoProspect custom snippets. There are 15 snippet fields (snippet1 to snippet15)
  └─ industrystringNoProspect's industry
  └─ statestringNoProspect's state or region

Request sample​

Add prospects to campaign​

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

curl --request POST \
  --url "https://api.woodpecker.co/rest/v1/add_prospects_campaign" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "campaign": {
      "campaign_id": 1234567
    },
    "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"
      }
    ]
  }'

Response​

Response examples​

All prospects have been added to the campaign prospect list. The first prospect already existed in the global prospect list, while the second was newly added.

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

Body schema​

FieldData TypeDescription
prospectsarray[object]An array of prospects added to the campaign prospect list
  └─[].emailstringProspect's email
  └─[].idintegerUnique ID assigned to the prospect
  └─[].prospectstring/nullDUPLICATE. Indicates that the prospect already exists in the global prospect list but does not prevent them from being added to a campaign
statusobjectObject containing the status details of the request
  └─statusstringGeneral status message
  └─codestringCode indicating the error category
  └─msgstringError message