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:

• self: the current page of data
• first: the first page of data
• last: the last page of data
• prev: the previous page of data
• next: the next page of data

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

• valid: The email represents a real account / inbox available at the given domain
• invalid: Not a real email
• unknown: For some reason we cannot verify valid or invalid. Most of the time a domain did not respond quickly enough.
• accept_all: These are domains that respond to every verification request in the affirmative, and therefore cannot be fully verified.

Error Codes

• email_address_invalid: The email address is not formatted correctly
• email_domain_invalid: The domain does not exist or is not capable of receiving email
• email_account_invalid: The email account does not exist on the domain

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.