API – Managing prospects

With this document, you'll be able to browse the prospect database in all possible directions and get some additional information about them

API Key is a part of an API Key and Integrations add-on, click here to learn how to get it on Marketplace »

Browsing prospects

To get a list of all prospects added to your Woodpecker account, use the following request: 

GET /rest/v1/prospects

Sample response:

[ { 
    "id": 4804, 
    "email": "[email protected]", 
    "first_name": "Erlich", 
    "last_name": "Bachman", 
    "company": "Bachmanity", 
    "organization_id": 93784, 
    "industry": "Software as a Service", 
    "website": "http://www.bachmanity.com/", 
    "linkedin_url": "https://www.linkedin.com/in/erlich-bachman/", 
    "tags": "#VISIONEER #SECONDARYEMAIL", 
    "title": "VC Angel", 
    "phone": "", 
    "address": "221 Newell Rd ", 
    "city": "Palo Alto", 
    "state": "California", 
    "country": "USA", 
    "last_contacted": "2016-08-14T02:08:58+0200", 
    "last replied": "2016-08-19T02:08:58+0200", 
    "updated": "2016-09-03T15:02:57+0200", 
    "snippet1": "Pied Piper board member", 
    "snipet1": "Pied Piper board member", 
    "snippet2": "no longer codes", 
    "snippet3": "", 
    "snippet4": "", 
    "snippet5": "", 
    "snippet6": "", 
    "snippet7": "", 
    "snippet8": "", 
    "snipper9": "", 
    "snippet10": "", 
    "snippet11": "", 
    "snippet12": "", 
    "snippet13": "", 
    "snippet14": "", 
    "snippet15": "", 
    "status": "REPLIED", 
    }, 
    { 
    "id": 2974, 
    "email": "[email protected]", 
    "first_name": "Jared", 
    "last_name": "Dunn", 
    "company": "Pied Piper", 
    "organization_id": 72894, 
    "industry": "Software as a Service", 
    "website": "http://www.piedpiper.com/", 
    "linkedin_url": "https://www.linkedin.com/in/jared-dunn/", 
    "tags": "#PR #SECONDARYEMAIL", 
    "title": "PR specialist", 
    "phone": "", 
    "address": "221 Newell Rd ", 
    "city": "Palo Alto", 
    "state": "California", 
    "country": "USA", 
    "last_contacted": "2016-08-14T02:08:58+0200", 
    "last replied": "2016-08-19T02:08:58+0200", 
    "updated": "2016-09-03T15:02:57+0200", 
    "snippet1": "Pied Piper board member", 
    "snippet2": "", 
    "snippet3": "", 
    "snippet4": "", 
    "snippet5": "", 
    "snippet6": "", 
    "snippet7": "", 
    "snippet8": "", 
    "snipper9": "", 
    "snippet10": "", 
    "snippet11": "", 
    "snippet12": "", 
    "snippet13": "", 
    "snippet14": "", 
    "snippet15": "", 
    "status": "REPLIED" 
    } 
]

A detailed explanation for parameters can be found below.

Sorting, filtering and paging prospects

If you want to easily manage your results, you can either use sorting, filtering or paging.

Query Use Description
per_page number Defines a number of results per page.
page number Defines a page number you want access to.
sort +/- and parameter Defines the sort order, as well as the field on which sorting will be based.

Sample queries:

GET /rest/v1/prospects?per_page=2 
GET /rest/v1/prospects?page=10 
GET /rest/v1/prospects?sort=+id 
GET /rest/v1/prospects?status=RESPONDED&sort=+id

While sorting, use + for ascending order and – for descending order.

Remember to provide the field on which sorting will be based. We provide sorting for the following parameters:

Parameter Type Description
id number Prospect’s ID.
last_replied string Date of the most recent reply.
status string Prospect’s status saved on a Prospects list. Available statuses: ACTIVE, INVALID, BOUNCED, REPLIED, BLACKLIST.
updated string Date of the most recent update done on prospect’s details.
email string Prospect’s email address.
first_name string Prospect’s first name.
last_name string Prospect’s last name.
company string Name of the company prospect is assigned to.
industry string Type of industry prospect is working in.
website string Website address.
linkedin_url string An URL to the prospect’s Linkedin profile.
tags string Prospect’s tags.
title string Prospect’s job title.
phone string Prospect’s phone number.
address string Prospect’s address.
city string Prospect’s city.
state string Prospect’s state or another geographical region he’s living in.
country string Prospect’s country.
snippet string Any snippet provided for a prospect. Use snippet1, snippet2… snippet15 to sort prospects by chosen custom field.
activity string Defines prospect’s activity. Available
snippet string Any snippet provided for a prospect. Use snippet1, snippet2… snippet15 to sort prospects by chosen custom field.

Prospect’s details

If you want to check the campaign details for a specific prospect, use the following request:

GET /rest/v1/prospects?id=num&campaigns_details=true

where id stands for prospect’s ID. You can easily use parameters other than prospect’s ID. just remember to add campaigns_details to your request to get more detailed information.

Sample response:

[ { 
    "id": 4804, 
    "email": "[email protected]", 
    "first_name": "Erlich", 
    "last_name": "Bachman", 
    "company": "Bachmanity", 
    "organization_id": 93784, 
    "industry": "Software as a Service", 
    "website": "http://www.bachmanity.com/", 
    "linkedin_url": "https://www.linkedin.com/in/erlich-bachman/", 
    "tags": "#VISIONEER #SECONDARYEMAIL", 
    "title": "VC Angel", 
    "phone": "", 
    "address": "221 Newell Rd ", 
    "city": "Palo Alto", 
    "state": "California", 
    "country": "USA", 
    "last_contacted": "2016-08-14T02:08:58+0200", 
    "last replied": "2016-08-19T02:08:58+0200", 
    "updated": "2016-09-03T15:02:57+0200", 
    "snippet1": "Pied Piper board member", 
    "snipet1": "Pied Piper board member", 
    "snippet2": "no longer codes", 
    "snippet3": "", 
    "snippet4": "", 
    "snippet5": "", 
    "snippet6": "", 
    "snippet7": "", 
    "snippet8": "", 
    "snipper9": "", 
    "snippet10": "", 
    "snippet11": "", 
    "snippet12": "", 
    "snippet13": "", 
    "snippet14": "", 
    "snippet15": "", 
    "status": "REPLIED", 
    }, 
    { 
    "id": 2974, 
    "email": "[email protected]", 
    "first_name": "Jared", 
    "last_name": "Dunn", 
    "company": "Pied Piper", 
    "organization_id": 72894, 
    "industry": "Software as a Service", 
    "website": "http://www.piedpiper.com/", 
    "linkedin_url": "https://www.linkedin.com/in/jared-dunn/", 
    "tags": "#PR #SECONDARYEMAIL", 
    "title": "PR specialist", 
    "phone": "", 
    "address": "221 Newell Rd ", 
    "city": "Palo Alto", 
    "state": "California", 
    "country": "USA", 
    "last_contacted": "2016-08-14T02:08:58+0200", 
    "last replied": "2016-08-19T02:08:58+0200", 
    "updated": "2016-09-03T15:02:57+0200", 
    "snippet1": "Pied Piper board member", 
    "snippet2": "", 
    "snippet3": "", 
    "snippet4": "", 
    "snippet5": "", 
    "snippet6": "", 
    "snippet7": "", 
    "snippet8": "", 
    "snipper9": "", 
    "snippet10": "", 
    "snippet11": "", 
    "snippet12": "", 
    "snippet13": "", 
    "snippet14": "", 
    "snippet15": "", 
    "status": "REPLIED" 
    "campaigns_details": [ 
        { 
            "campaign_id": 96937, 
            "campaign_name": "Pied Piper for Hooli", 
            "campaign_status": "COMPLETED", 
            "campaign_prospect_status": "REPLIED", 
            "interested": "INTERESTED", }, 
        { 
            "campaign_id": 64218, 
            "campaign_name": "Pied Piper joins Raviga", 
            "campaign_status": "COMPLETED", 
            "campaign_prospect_status": "REPLIED", 
            "interested": "NOT_MARKED", 
        } 
     ]
 }

If you need more details about those campaigns, use the campaign related endpoints. Detailed documentation can be found here.

Parameter Type Description
campaigns_details JSON object Detailed information about campaigns in which was or currently is a specific prospect.
campaign_id number Campaign ID.
campaign_prospect_status string Prospect’s status saved on a campaign level. Available statuses: ACTIVE, INVALID, BOUNCED, BLACKLIST, REPLIED, PAUSED.
interested string Prospect’s interest level in a specific campaign. Available Options: INTERESTED, NOT INTERESTED, MAYBE LATER.

Adding prospects to the prospect list

Adding prospects to the global prospects list is available with the POST method. Use the following endpoint and provide the prospect’s details in the payload body. You can add multiple prospects in one request.

POST /rest/v1/add_prospects_list

Sample body:

{
    "update": "true",
    "prospects": [
        {
            "email": "[email protected]", 
            "first_name": "Erlich", 
            "last_name": "Bachman", 
            "company": "Bachmanity", 
            "organization_id": 93784, 
            "industry": "Software as a Service", 
            "website": "http://www.bachmanity.com/", 
            "linkedin_url": "https://www.linkedin.com/in/erlich-bachman/", 
            "tags": "#VISIONEER #SECONDARYEMAIL", 
            "title": "VC Angel", 
            "phone": "", 
            "address": "221 Newell Rd ", 
            "city": "Palo Alto", 
            "state": "California", 
            "country": "USA", 
            "snippet1": "Pied Piper board member", 
            "snipet1": "Pied Piper board member", 
            "snippet2": "no longer codes", 
            "snippet3": "", 
            "snippet4": "", 
            "snippet5": "", 
            "snippet6": "", 
            "snippet7": "", 
            "snippet8": "", 
            "snipper9": "", 
            "snippet10": "", 
            "snippet11": "", 
            "snippet12": "", 
            "snippet13": "", 
            "snippet14": "", 
            "snippet15": "" 

    },
    {
            "email": "[email protected]", 
            "first_name": "Jared", 
            "last_name": "Dunn", 
            "company": "Pied Piper", 
            "organization_id": 72894, 
            "industry": "Software as a Service", 
            "website": "http://www.piedpiper.com/", 
            "linkedin_url": "https://www.linkedin.com/in/jared-dunn/", 
            "tags": "#PR #SECONDARYEMAIL", 
            "title": "PR specialist", 
            "phone": "", 
            "address": "221 Newell Rd ", 
            "city": "Palo Alto", 
            "state": "California", 
            "country": "USA", 
            "snippet1": "Pied Piper board member", 
            "snippet2": "", 
            "snippet3": "", 
            "snippet4": "", 
            "snippet5": "", 
            "snippet6": "", 
            "snippet7": "", 
            "snippet8": "", 
            "snipper9": "", 
            "snippet10": "", 
            "snippet11": "", 
            "snippet12": "", 
            "snippet13": "", 
            "snippet14": "", 
            "snippet15": ""
     }
   ]
}

Sample response:

{
    "prospects": [
        {
             "email": "[email protected]"
        },
        {
             "email: "[email protected]"
        }
    ],
    "status": {
         "status": "OK",
         "code": "OK",
         "msg": "OK"
    }
}

Adding prospects to the campaign

You can also add prospects to the specific campaign with the POST method. Use the following endpoint and provide the prospect’s details in the payload body. You can add multiple prospects in one request.

POST /rest/v1/add_prospects_campaign

Sample body:

{ 
    "campaign":{ 
        "campaign_id": 4539 
    }, 
    "update": "true", 
    "prospects": [ 
        { 
            "email": "[email protected]", 
            "first_name": "John", 
            "last_name": "Doe", 
            "status": "ACTIVE", 
            "tags": "#tags", 
            "company": "company", 
            "industry": "industry", 
            "linkedin_url": "https://www.linkedin.com/in/john-doe/", 
            "title": "title", 
            "phone": "+123 456 789", 
            "address": "address", 
            "city": "city", 
            "state": "state", 
            "country": "country", 
            "website": "website", 
            "snippet1": "snippet1", 
            "snippet2": "snippet2", 
            "snippet3": "snippet3", 
            (...) 
            "snippet15": "snippet15" 
        } 
    ] 
}

Sample response:

{
    "prospects": [
        {
             "email": "[email protected]"
             "id": 47356575
        },
    ],
    "status": {
         "status": "OK",
         "code": "OK",
         "msg": "OK"
    }
}

If by mistake you’ll add a duplicated prospect to the campaign, you’ll receive a proper server response. Full error code list is available here.

{
    "prospects": [
        {
             "email": "[email protected]"
             "id": 47356575,
             "prospects": "DUPLICATE"
        },
    ],
    "status": {
         "status": "OK",
         "code": "OK",
         "msg": "OK"
    }
}

Updating prospects data

Some prospect’s details are outdated? No worries, you can always update them. Simply provide the prospect’s ID in the payload. Remember, all fields mentioned in the request will be updated.

Sample request:

POST /rest/v1/add_prospects_list
{
    "update": "true",
    "prospects": [
        {
             "id": 47356575,
             "email": "[email protected]"
             "first_name": "Eddy"
        }
   ]
}

Sample response:

{
    "prospects": [
        {
             "email": "[email protected]"
             "id": 47356575,
        },
    ],
    "status": {
         "status": "OK",
         "code": "OK",
         "msg": "OK"
    }
}

Delete prospects data

If you no longer want to contact some of your prospects, delete them from a specific campaign or entire database.

DELETE /rest/v1/prospects?id=1 
DELETE /rest/v1/prospects?id=1&campaigns_id=1

Sample response:

200 OK

Turn knowledge into results

Send follow-ups that make a business thrive

We use cookies for your best browsing experience, site traffic analysis, and targeted advertisement management. Using this site, you consent to our use of cookies. If you don't accept our Cookies Policy, close this page.