NAV
shell

Introduction

# API Endpoint
https://prospect.io/api/public/v1/

Welcome to the Prospect.io API! You can use our API to access Prospect.io API endpoints.

Our API follows the JSON API specification. You can view code examples in the dark area to the right.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://prospect.io/api/public/v1/XXX"
  -H "Authorization: your_api_key"

Make sure to replace your_api_key with your API key.

Prospect.io uses API keys to allow access to the API. You can get a new API key in your Prospect.io account.

Prospect.io expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: your_api_key

Sorting

# EXAMPLE
GET https://prospect.io/api/public/v1/prospects?sort=-created_at

Get prospects sorted by creation date DESC (most recents first)

Our APIs supports requests to sort resource collections according to one or more criteria usin a sort query parameter. The value for sort must represent the object attributes.

We support multiple sort attributes by using comma-separated “,” attributes. Sort attributes are applied in the order specified.

The sort order for each sort attributes is ascending by default unless it is prefixed with a minus “-”, in which case it is descending.

Pagination

{
  "data": [
    {
      ...
    }
  ],
  "links": {
    "self": "https://prospect.io/api/public/v1/prospects?page%5Bnumber%5D=2&page%5Bsize%5D=1",
    "first": "https://prospect.io/api/public/v1/prospects?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "prev": "https://prospect.io/api/public/v1/prospects?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "next": "https://prospect.io/api/public/v1/prospects?page%5Bnumber%5D=3&page%5Bsize%5D=1",
    "last": "https://prospect.io/api/public/v1/prospects?page%5Bnumber%5D=2203&page%5Bsize%5D=1"
  }
}

Collection APIs paginate their results. The first request returns up to 100 records. If the request returns more than 100 records and links will be include in the result. This object may contains the following keys:

Errors

# EXAMPLE OBJECT
## When trying to add a prospect with a duplicate email address
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/email"
      },
      "detail": "has already been taken"
    }
  ]
}
## Error on authentication
{
  "errors": [
    {
      "code": "unauthorized",
      "message": "Your API key is wrong. More information here https://prospect.io/docs/api#authentication"
    }
  ]
}

Prospect.io uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a prospect cannot be created, etc.), and codes in the 5xx range indicate an error with Prospect.io’s servers.

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The resource requested is hidden for administrators only
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The resource requested has been removed from our servers
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Main API

Account

The account object

# EXAMPLE OBJECT
{
  "data": {
    "id": "1",
    "type": "companies",
    "attributes": {
      "name": "Prospect.io",
      "website": "https://prospect.io",
      "phone_number": "",
      "billing_name": "Prospect.io SPRL",
      "address": "rue des Pères Blancs 4\r\n1040 Brussels",
      "country": "BE",
      "vat": "BE0645917753",
      "plan_name": "5K Credits",
      "plan_code": "monthly_credits_5k",
      "credits_per_month": 5000,
      "this_month_used_credits": 1608,
      "email_queries_used_this_period_count": 135,
      "messages_sent_this_period_count": 1473,
      "created_at": "2015-08-15T16:48:46+02:00",
      "updated_at": "2016-11-25T12:40:46+01:00"
    }
  }
}

Object attributes

Attribute Description
id integer
A unique identifier for the account
name string
The account’s name
website string
The account’s website
phone_number string
The account’s phone number
billing_name string
The account’s billing name (the name that will appear on invoices)
address string
The account’s address
country string
The account’s country code (ISO)
vat string
The account’s VAT number
plan_name string
The account’s plan
plan_code string
The account’s plan code
credits_per_month integer
The number of credits available per month
this_month_used_credits integer
The number of total credits used on the current billing period
email_queries_used_this_period_count integer
The number of total credits used for email queries on the current billing period
messages_sent_this_period_count integer
The number of total credits used for sending messages on the current billing period
created_at datetime
updated_at datetime

Retrieve your account

# DEFINITION
GET https://prospect.io/api/public/v1/account

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/account" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Parameters

none

Returns

Returns the account object.

Prospects

The prospect object

# EXAMPLE OBJECT
{
  "data": {
    "id": "1",
    "type": "prospects",
    "attributes": {
      "email": "vincenzo@prospect.io",
      "first_name": "Vincenzo",
      "last_name": "Ruggiero",
      "organisation_name": "Prospect.io",
      "description": null,
      "domain": "https://prospect.io",
      "jobtitle": "CEO",
      "linkedin_profile": "https://www.linkedin.com/in/vincenzor",
      "phone": "+32-481-754-301",
      "title": "Mr.",
      "country": "Belgium",
      "industry": "IT",
      "custom_field_a": "Hot lead",
      "custom_field_b": null,
      "custom_field_c": null,
      "custom_field_d": null,
      "custom_field_e": null,
      "created_from": "extension",
      "last_emailed_at": null,
      "converted": false,
      "converted_at": false,
      "qualified": true,
      "archived": false,
      "replied": false,
      "replied_at": false,
      "campaign_status": null,
      "url": "https://prospect.io/prospects/1",
      "list_name": "Sales Managers in UK",
      "created_at": "2015-08-15T16:48:46+02:00",
      "updated_at": "2016-11-25T12:40:46+01:00"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1",
          "type": "users"
        }
      },
      "responsible": {
        "data": {
          "id": "2",
          "type": "users"
        }
      },
      "list": {
        "data": {
          "id": "1",
          "type": "lists"
        }
      },
      "campaign": {
        "data": null
      },
      "current_campaign_subscription": {
        "data": null
      }
    }
  }
}

Object attributes

Attribute Description
id integer
A unique identifier for the prospect
email string
The prospect’s email address
first_name string
The prospect’s first name
last_name string
The prospect’s last name
organisation_name string
The prospect’s company name
description string
A text description of the prospect
domain string
The prospect’s website
jobtitle string
The prospect’s job title
linkedin_profile string
A link to the prospect’s LinkedIn profile
phone string
The prospect’s phone number
title string
The prospect’s title of civility
country string
The prospect’s country
industry string
The prospect’s industry
custom_field_[a..e] string
Five custom fields (custom_field_a, custom_field_b, …) that you can use freely
created_from string
The source of the prospect. Can be web, extension, api or import
last_emailed_at datetime
The date and time of the last email sent to this prospect in ISO 8601 format with timezone offset
converted boolean
Whether or not the prospect is marked as converted
converted_at datetime
The date and time when the prospect has been marked as converted
qualified boolean
Whether or not the prospect is marked as qualified
archived boolean
Whether or not the prospect is archived
replied boolean
Whether or not the prospect replied to any of your emails
replied_at datetime
The date and time when the prospect first replied
campaign_status string
If the prospect is currently in a campaign, this attribute contains the status of the campaign. Can be running, paused or scheduled
url string
The full URL to the prospect on Prospect.io
list_name string
The name of the list if the prospect is in a list
created_at datetime
updated_at datetime

Relationships

Object Description
creator The user who created the prospect
responsible The user responsible of the prospect
list Describe a list object if the prospect is in a list
campaign Describe a campaign object if the prospect is currently in a campaign. The campaign status is described in the campaign_status attribute
current_campaign_subscription Describe a campaign subscription if the prospect is currently in a campaign.

Create a prospect

# DEFINITION
POST https://prospect.io/api/public/v1/prospects

# EXAMPLE
curl -X POST "https://prospect.io/api/public/v1/prospects" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \
-d '{
  "data": {
    "type": "prospects",
    "attributes": {
      "email": "vincenzo@prospect.io",
      "first_name": "Vincenzo",
      "last_name": "Ruggiero"
    }
  }
}'

This will create a new prospect. If you don’t set the responsible_id parameter then the user who performed the action will be assigned as the responsible user.

Parameters

Parameter Default Description
email
required - string
/ The prospect’s email
first_name
string
NULL The prospect’s first name
last_name
string
NULL The prospect’s last name
organisation_name
string
NULL The prospect’s company name
description
string
NULL A text description of the prospect
domain
string
NULL The prospect’s website
jobtitle
string
NULL The prospect’s job title
linkedin_profile
string
NULL A link to the prospect’s LinkedIn profile
phone
string
NULL The prospect’s phone number
title
string
NULL The prospect’s title of civility
country
string
NULL The prospect’s country
industry
string
NULL The prospect’s industry
custom_field_[a..e]
string
NULL Five custom fields (custom_field_a, custom_field_b, …) that you can use freely
list_id
integer
NULL ID of the list where to save the prospect
responsible_id
integer
ID of the user who created the prospect The ID of the user responsible for this prospect

Returns

Returns the prospect object.

Retrieve a prospect

# DEFINITION
GET https://prospect.io/api/public/v1/prospects/{PROSPECT_ID}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/prospects/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Parameters

Parameter Description
id
required - integer
The ID of the prospect to retrieve

Returns

Returns the prospect object.

Update a prospect

# DEFINITION
PATCH https://prospect.io/api/public/v1/prospects/{PROSPECT_ID}

# EXAMPLE
curl -X PATCH "https://prospect.io/api/public/v1/prospects/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \
-d '{
  "data": {
    "type": "prospects",
    "attributes": {
      "first_name": "Vincent"
    }
  }
}'

Updates the specified prospect by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

Parameter Description
id
required - integer
The ID of the prospect to update
email
string
The prospect’s email
first_name
string
The prospect’s first name
last_name
string
The prospect’s last name
organisation_name
string
The prospect’s company name
description
string
A text description of the prospect
domain
string
The prospect’s website
jobtitle
string
The prospect’s job title
linkedin_profile
string
A link to the prospect’s LinkedIn profile
phone
string
The prospect’s phone number
title
string
The prospect’s title of civility
country
string
The prospect’s country
industry
string
The prospect’s industry
custom_field_[a..e]
string
list_id
integer
ID of the list where to save the prospect
responsible_id
integer
The ID of the user responsible for this prospect

Returns

Returns the prospect object.

Delete a prospect

# DEFINITION
DELETE https://prospect.io/api/public/v1/prospects/{PROSPECT_ID}

# EXAMPLE
curl -X DELETE "https://prospect.io/api/public/v1/prospects/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": {
    "id": "1",
    "type": "prospects"
  }
}

Permanently deletes a prospect. It cannot be undone.

Parameters

Parameter Required? Type Description
id yes integer The ID of the prospect to delete

Returns

Returns an object containing the prospect ID.

List prospects

# DEFINITION
GET https://prospect.io/api/public/v1/prospects

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/prospects" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "1",
      "type": "prospects",
      "attributes": {
        ...
      },
      "relationships": {
        "responsible": {
          "data": {
            ...
          }
        },
        "list": {
          "data": {
            ...
          }
        },
        "campaign": {
          "data": {
            ...
          }
        },
        "current_campaign_subscription": {
          "data": {
            ...
          }
        }
      }
    },
    {
      "id": "2",
      "type": "prospects",
      "attributes": {
        ...
      },
      "relationships": {
        "responsible": {
          "data": {
            ...
          }
        },
        "list": {
          "data": {
            ...
          }
        },
        "campaign": {
          "data": {
            ...
          }
        },
        "current_campaign_subscription": {
          "data": {
            ...
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://prospect.io/api/public/v1/prospects/?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "next": "https://prospect.io/api/public/v1/prospects/?page%5Bnumber%5D=2&page%5Bsize%5D=100",
    "last": "https://prospect.io/api/public/v1/prospects/?page%5Bnumber%5D=5&page%5Bsize%5D=100"
  }
}

Returns a list of prospects.

This list is paginate by 100 records and can also be sorted.

Lists

The list object

# EXAMPLE OBJECT
{
  "data": {
    "id": "1",
    "type": "lists",
    "attributes": {
      "name": "LinkedIn",
      "available": true,
      "created_at": "2015-08-15T16:48:46+02:00",
      "updated_at": "2016-11-25T12:40:46+01:00"
    }
  }
}

Object attributes

Attribute Description
id integer
A unique identifier for the list
name string
The list’s name
available boolean
Whether or not the list is available
created_at datetime
updated_at datetime

Create a list

# DEFINITION
POST https://prospect.io/api/public/v1/lists

# EXAMPLE
curl -X POST "https://prospect.io/api/public/v1/lists" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \
-d '{
  "data": {
    "type": "lists",
    "attributes": {
      "name": "A list name",
      "available": true
    }
  }
}'

This will create a new list.

Parameters

Parameter Default Description
name
required - string
/ The list’s name
available
boolean
true Whether or not the list is available

Returns

Returns the list object.

Retrieve a list

# DEFINITION
GET https://prospect.io/api/public/v1/lists/{LIST_ID}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/lists/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Parameters

Parameter Description
id
required - integer
The ID of the list to retrieve

Returns

Returns the list object.

Update a list

# DEFINITION
PATCH https://prospect.io/api/public/v1/lists/{LIST_ID}

# EXAMPLE
curl -X PATCH "https://prospect.io/api/public/v1/lists/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \
-d '{
  "data": {
    "type": "lists",
    "attributes": {
      "name": "LinkedIn bis"
    }
  }
}'

Updates the specified list by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

Parameter Description
id
required - integer
The ID of the list to update
name
string
/
available
boolean
true

Returns

Returns the list object.

Delete a list

# DEFINITION
DELETE https://prospect.io/api/public/v1/lists/{PROSPECT_ID}

# EXAMPLE
curl -X DELETE "https://prospect.io/api/public/v1/lists/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": {
    "id": "1",
    "type": "lists"
  }
}

Permanently deletes a list. It cannot be undone.

Parameters

Parameter Required? Type Description
id yes integer The ID of the list to delete

Returns

Returns an object containing the list ID.

List lists

# DEFINITION
GET https://prospect.io/api/public/v1/lists

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/lists" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "1",
      "type": "lists",
      "attributes": {
        ...
      }
    },
    {
      "id": "2",
      "type": "list",
      "attributes": {
        ...
      }
    }
  ],
  "links": {
    "self": "https://prospect.io/api/public/v1/lists/?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "next": "https://prospect.io/api/public/v1/lists/?page%5Bnumber%5D=2&page%5Bsize%5D=100",
    "last": "https://prospect.io/api/public/v1/lists/?page%5Bnumber%5D=5&page%5Bsize%5D=100"
  }
}

Returns a list of lists.

This list is paginate by 100 records and can also be sorted.

Campaigns

The campaign object

# EXAMPLE OBJECT
{
  "data": {
    "id": "1961",
    "type": "campaigns",
    "attributes": {
      "name": "Intro + 1 follow up",
      "available": false,
      "steps_count": 2,
      "sending_days": [
        "1",
        "2",
        "3",
        "4",
        "5"
      ],
      "stop_when": [
        "prospect.replied"
      ],
      "created_at": "2015-08-15T16:48:46+02:00",
      "updated_at": "2016-11-25T12:40:46+01:00"
    },
    "relationships": {
      "steps": {
        "data": [
          {
            "id": "3920",
            "type": "steps_prospect_email_steps"
          },
          {
            "id": "3922",
            "type": "steps_prospect_email_steps"
          }
        ]
      }
    }
  }
}

Object attributes

Attribute Description
id integer
A unique identifier for the campaign
name string
The campaign’s name
available boolean
Whether or not the campaign is available
steps_count integer
The number of steps in the campaign
sending_days array
An array containing the days of the week when the campaign will send. Monday is 1
stop_when array
An array containing the events that trigger the campaign to stops. Possible values are message.click, prospect.replied and prospect.convert
created_at datetime
updated_at datetime

Relationships

Object Description
steps The steps of the campaign. Can be a email to the prospect steps_prospect_email_steps or a team notification email steps_notification_email_steps.

Retrieve a campaign

# DEFINITION
GET https://prospect.io/api/public/v1/campaigns/{CAMPAIGN_ID}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/campaigns/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Parameters

Parameter Description
id
required - integer
The ID of the campaign to retrieve

Returns

Returns the campaign object.

List campaigns

# DEFINITION
GET https://prospect.io/api/public/v1/campaigns

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/campaigns" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "1",
      "type": "campaigns",
      "attributes": {
        ...
      },
      "relationships": {
        "steps": {
          "data": [
            ...
          ]
        }
      }
    },
    {
      "id": "2",
      "type": "campaigns",
      "attributes": {
        ...
      },
      "relationships": {
        "steps": {
          "data": [
            ...
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://prospect.io/api/public/v1/campaigns/?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "next": "https://prospect.io/api/public/v1/campaigns/?page%5Bnumber%5D=2&page%5Bsize%5D=100",
    "last": "https://prospect.io/api/public/v1/campaigns/?page%5Bnumber%5D=5&page%5Bsize%5D=100"
  }
}

Returns a list of campaigns.

This list is paginate by 100 records and can also be sorted.

Campaign Steps

The campaign step object

# EXAMPLE OBJECT
{
  "data": [
    {
      "id": "3920",
      "type": "steps_prospect_email_steps",
      "attributes": {
        "subject": "Introduction {{company_name}}",
        "content": "<div>Hi {{prospect_firstname | default: 'there'}},<br /><br /></div>\r\n<div>My name is {{user_name}} and I'm the founder of&nbsp;<a href=\"https://prospect.io\">{{company_name}}</a>. Our product is already used by hundred of organizations like {{prospect_company_name | default: 'yours'}} to improve their sales prospecting and cold emailing.<br /><br /></div>\r\n<div>Could you direct me to the right person to talk about this so we can explore if this would be something valuable for you?<a href=\"https://prospect.io\"><br /></a></div>\r\n<div>Thanks for your time,</div>",
        "offset": 0,
        "position": 1,
        "recipient": "",
        "schedule_time": null,
        "created_at": "2015-08-15T16:48:46+02:00",
        "updated_at": "2016-11-25T12:40:46+01:00"
      },
      "relationships": {
        "campaign": {
          "data": {
            "id": "1961",
            "type": "campaigns"
          }
        }
      }
    }
  ]
}

Object attributes

Attribute Description
id integer
A unique identifier for the campaign step
type string
The type of step. Can be a email to the prospect steps_prospect_email_steps or a team notification email steps_notification_email_steps
subject string
The subject of the email
content string
The HTML content of the email
offset integer
The number of days the step will be sent after the previous step
position integer
The order position in the list
recipient string
The recipient email for step of type steps_notification_email_steps
schedule_time datetime
Time of day for this step to send in ISO 8601 format with timezone offset
created_at datetime
updated_at datetime

Relationships

Object Description
campaign The parent campaign

Retrieve a campaign step

# DEFINITION
GET https://prospect.io/api/public/v1/campaigns/{CAMPAIGN_ID}/steps/{STEP_ID}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/campaigns/1/steps/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Parameters

Parameter Description
campaign_id
required - integer
The ID of the campaign
id
required - integer
The ID of the campaign step to retrieve

Returns

Returns the campaign step object.

List campaigns steps

# DEFINITION
GET https://prospect.io/api/public/v1/campaigns/{CAMPAIGN_ID}/steps

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/campaigns/1/steps" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "3920",
      "type": "steps_prospect_email_steps",
      "attributes": {
        ...
      },
      "relationships": {
        "campaign": {
          "data": {
            "id": "1961",
            "type": "campaigns"
          }
        }
      }
    },
    {
      "id": "3922",
      "type": "steps_prospect_email_steps",
      "attributes": {
        ...
      },
      "relationships": {
        "campaign": {
          "data": {
            "id": "1961",
            "type": "campaigns"
          }
        }
      }
    },
    {
      "id": "20837",
      "type": "steps_notification_email_steps",
      "attributes": {
        ...
      },
      "relationships": {
        "campaign": {
          "data": {
            "id": "1961",
            "type": "campaigns"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://prospect.io/api/public/v1/campaigns/1/steps?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "next": "https://prospect.io/api/public/v1/campaigns/1/steps?page%5Bnumber%5D=2&page%5Bsize%5D=100",
    "last": "https://prospect.io/api/public/v1/campaigns/1/steps?page%5Bnumber%5D=5&page%5Bsize%5D=100"
  }
}

Returns a list of campaigns steps.

This list is paginate by 100 records and can also be sorted.

Subscriptions

The subscription object

To start sending a campaign to a prospect you have to create a subscription. The subscription is then used to described the current status of the campaign for the prospect.

You can take manual actions on a subscription to pause, resume or stop a campaign for a specific prospect.

A subscription can also be automatically completed after the last campaign step is sent. A subscription can laos be automatically stopped if we register one of the campaigns.stop_when events.

# EXAMPLE OBJECT
{
  "data": {
    "id": "1",
    "type": "campaign_deliveries",
    "attributes": {
      "prospect_id": 2,
      "current_step": 0,
      "started_at": "2016-11-19T09:18:44.276Z",
      "completed_at": null,
      "stopped_at": null,
      "stop_reason": null,
      "start_at": "2016-11-19T09:18:44.190Z",
      "send_next_step_at": "2016-11-19T09:18:00.000Z",
      "paused_at": null,
      "pause_reason": null,
      "created_at": "2015-08-15T16:48:46+02:00",
      "updated_at": "2016-11-25T12:40:46+01:00"
    },
    "relationships": {
      "sender": {
        "data": {
          "id": "1",
          "type": "users"
        }
      },
      "creator": {
        "data": {
          "id": "1",
          "type": "users"
        }
      },
      "campaign": {
        "data": {
          "id": "6367",
          "type": "campaigns"
        }
      },
      "prospect": {
        "data": {
          "id": "2",
          "type": "prospects"
        }
      }
    }
  }
}

Object attributes

Attribute Description
id integer
A unique identifier for the subscription
prospect_id integer
The prospect’s ID this subscription is associated to
current_step integer
Define the last sent step (starts at 0)
started_at datetime
The date and time when the campaign has been started in ISO 8601 format with timezone
started_at datetime
The date and time when the campaign has been completed in ISO 8601 format with timezone. Completed means that we sent the last step of the campaign
stopped_at datetime
The date and time when the campaign has been stopped in ISO 8601 format with timezone. Stopped means that we encountered a campaigns.stop_when event or that the campaign has been manually stopped
stop_reason string
The reason why the campaign has been stopped. Can be a campaigns.stop_when event or manual
start_at datetime
If the campaign is scheduled , the date and time when the campaign will start sending the first step
send_next_step_at datetime
The date and time the next step is scheduled to be sent in ISO 8601 format with timezone
paused_at datetime
The date and time when the campaign has been paused in ISO 8601 format with timezone
pause_reason string
The reason why the campaign has been paused
created_at datetime
updated_at datetime

Relationships

Object Description
sender The user that send the emails
creator The user who created the subscription
campaign Describe a campaign object
prospect Describe a prospect object

Create a subscription

# DEFINITION
POST https://prospect.io/api/public/v1/campaigns/{{CAMPAIGN_ID}}/subscriptions

# EXAMPLE
curl -X POST "https://prospect.io/api/public/v1/campaigns/1/subscriptions" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \
-d '{
  "data": {
    "type": "subscriptions",
    "attributes": {
      "prospect_id": 1,
      "user_id": 1
    }
  }
}'

This will create a new subscription.

Parameters

Parameter Default Description
prospect_id
required - integer
/ The prospect’s ID
user_id
required - integer
/ The sender’s ID

Returns

Returns the subscription object.

Pause a subscription

# DEFINITION
POST https://prospect.io/api/public/v1/campaigns/{{CAMPAIGN_ID}}/subscriptions/{{SUBSCRIPTION_ID}}/pause

# EXAMPLE
curl -X DELETE "https://prospect.io/api/public/v1/campaigns/1/subscriptions/1/pause" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

This will pause a subscription.

Parameters

Parameter Required? Type Description
id yes integer The ID of the subscription to pause

Returns

Returns the subscription object.

Resume a subscription

# DEFINITION
POST https://prospect.io/api/public/v1/campaigns/{{CAMPAIGN_ID}}/subscriptions/{{SUBSCRIPTION_ID}}/resume

# EXAMPLE
curl -X DELETE "https://prospect.io/api/public/v1/campaigns/1/subscriptions/1/resume" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

This will resume a subscription.

Parameters

Parameter Required? Type Description
id yes integer The ID of the subscription to resume

Returns

Returns the subscription object.

Stop a subscription

# DEFINITION
DELETE https://prospect.io/api/public/v1/campaigns/{{CAMPAIGN_ID}}/subscriptions/{{SUBSCRIPTION_ID}}

# EXAMPLE
curl -X DELETE "https://prospect.io/api/public/v1/campaigns/1/subscriptions/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": {
    "id": "1",
    "type": "campaign_deliveries"
  }
}

This will stop a subscription.

Parameters

Parameter Required? Type Description
id yes integer The ID of the subscription to stop

Returns

Returns the subscription object.

Retrieve a subscription

# DEFINITION
GET https://prospect.io/api/public/v1/campaigns/{{CAMPAIGN_ID}}/subscriptions/{{SUBSCRIPTION_ID}}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/campaigns/1/subscriptions/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Parameters

Parameter Description
id
required - integer
The ID of the subscription to retrieve

Returns

Returns the subscription object.

Users

The user object

# EXAMPLE OBJECT
{
  "data": {
    "id": "11",
    "type": "users",
    "attributes": {
      "name": "Vincenzo Ruggiero",
      "email": "vincenzo@prospect.io",
      "role": "admin",
      "phone_number": "",
      "skype": "ruggiero.vincenzo",
      "signature": "<p class=\"p1\"><span class=\"s1\">--&nbsp;<br /></span><span class=\"s1\"><strong>Vincenzo Ruggiero<br /></strong></span><span class=\"s1\">Founder<br /></span><span class=\"s2\"><a href=\"https://prospect.io/\"><strong>Prospect.io</strong><br /></a></span><span class=\"s2\"><a href=\"mailto:vincenzo@prospect.io\">vincenzo@prospect.io</a></span></p>",
      "disabled": false,
      "from_name": "Vincenzo Ruggiero",
      "timezone": "Brussels",
      "created_at": "2015-08-15T16:48:46+02:00",
      "updated_at": "2016-11-25T12:40:46+01:00"
    },
    "relationships": {
      "company": {
        "data": {
          "id": "5",
          "type": "companies"
        }
      }
    }
  }
}

Object attributes

Attribute Description
id integer
A unique identifier for the user
name string
The user’s name
email string
The user’s email address
role string
The user’s role. Can be admin or user
phone_number string
The user’s phone number
skype string
The user’s Skype username
signature string
The user’s HTML signature
disabled boolean
Whether or not the user is disabled or not
from_name string
The name we put in the email from field
timezone string
The user’s time zone
created_at datetime
updated_at datetime

Relationships

Object Description
company The user’s company

Retrieve a user

# DEFINITION
GET https://prospect.io/api/public/v1/users/{USER_ID}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/users/1" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Parameters

Parameter Description
id
required - integer
The ID of the user to retrieve

Returns

Returns the user object.

Me

# DEFINITION
GET https://prospect.io/api/public/v1/me

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/me" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

You can call this endpoint to retrive your personnal information.

Parameters

none

Returns

Returns your user object.

List users

# DEFINITION
GET https://prospect.io/api/public/v1/users

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/users" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8" \

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "11",
      "type": "users",
      "attributes": {
        ...
      }
    },
    {
      "id": "38",
      "type": "users",
      "attributes": {
        ...
      }
    },
  ],
  "links": {
    "self": "https://prospect.io/api/public/v1/users?page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "next": "https://prospect.io/api/public/v1/users?page%5Bnumber%5D=2&page%5Bsize%5D=100",
    "last": "https://prospect.io/api/public/v1/users?page%5Bnumber%5D=5&page%5Bsize%5D=100"
  }
}

Returns a list of users.

This list is paginate by 100 records and can also be sorted.

Emails API

Search

The Emails Search API lets you find email addresses associated with a company or a domain name.

The search result object

# EXAMPLE OBJECT
{
  "data": [
    {
      "id": "72947",
      "type": "emails",
      "attributes": {
        "value": "vincenzo@prospect.io",
        "type": "personal",
        "confidence": "98",
        "first_name": "Vincenzo",
        "last_name": "Ruggiero",
        "job_title": "Founder, CEO",
        "job_title": "Prospect.io",
        "phone": "555-12545474",
        "twitter": "VincenzoR",
        "linkedin_url": "https://www.linkedin.com/in/vincenzor",
        "angellist_url": "https://angel.co/vincenzo",
      },
      "relationships": {
        "domain": {
          "data": {
            "id": "1",
            "type": "domains"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "1",
      "type": "domains",
      "attributes": {
        "name": "prospect.io",
        "pattern": "{first}",
        "company_name": "Prospect.io"
      }
    }
  ]
}

Search result object attributes

Attribute Description
id integer
A unique identifier for the email
value string
The email address
type string
Can be personal for personal email addresses or generic for email addresses like support@ or contact@
confidence integer
Our estimation between 0 and 100 of the probability the email address returned is correct. It depends on several criteria such as the number and quality of sources
first_name string
First name of the person
last_name string
Last name of the person
job_title string
Job title of the person
company string
Company name of the person
phone string
Phone number of the person
twitter string
Twitter handle of the person
linkedin_url string
Full LinkedIn profile URL of the person
angellist_url string
Full AngelList profile URL of the person

Relationships

Object Description
domain The domain (company) information

Domain object attributes

Attribute Description
id integer
A unique identifier for the domain
name string
The domain name
pattern string
The pattern used in this companies for emails. Common values are: {first}, {first}.{last}, {f}.{last}, …
company_name string
Name of the company associated to the domain name

Search for emails

# DEFINITION
GET https://prospect.io/api/public/v1/emails/search?domain={{DOMAIN}}&first_name={{FIRST_NAME}}&last_name={{LAST_NAME}}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/emails/search?domain=prospect.io&first_name=Vincenzo&last_name=Ruggiero" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Every call returning at least 1 email address go against your quota and will cost you 1 credit.

Parameters

Parameter Description
domain
required - string
Domain name from which you want to find the email addresses. For example, “prospect.io”.
first_name
string
The person’s first name
last_name
string
The person’s last name
type
string
Only return emails of this type. Possible values are personal or generic.

Returns

Returns the email search object.

Verify

The Emails Verify API lets you check in real time the deliverability (how likely it is to bounce or not from the mail server) of any email address without sending an email.

The verify result object

# EXAMPLE OBJECT
{
  "data": [],
  "meta": {
    "email": "vincenzo@prospect.io",
    "status": "valid",
    "disposable": false,
    "role_address": false,
    "error_code": null
  }
}

Verify result object attributes

Attribute Description
email string
The email address verified
status string
The status of the email. Can be valid, invalid, unknown or accept_all.
disposable boolean
Is the email a temporary or “disposable” email address
role_address boolean
Is the email a “role” email address (like postmaster@, sales@, admin@, info@, webmaster@, etc. )
error_code string
An error code if the email is invalid. Can be email_address_invalid, email_domain_invalid or email_account_invalid.

Statuses

Error Codes

Verify an email

# DEFINITION
GET https://prospect.io/api/public/v1/emails/verify?email={{EMAIL_ADDRESS}}

# EXAMPLE
curl -X GET "https://prospect.io/api/public/v1/emails/verify?email=vincenzo@prospect.io" \
-H "Authorization: your_api_key" \
-H "Content-Type: application/vnd.api+json; charset=utf-8"

Every call will go against your quota and will cost you 1 credit.

Parameters

Parameter Description
email
required - string
The email addresses to verify. For example, “vincenzo@prospect.io”.

Returns

Returns the verify result object.