API explorerChangelog
API explorer
Changelog

Theme switcher

Introduction

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Welcome to Instantly. Let’s get started with getting you authenticated and ready to build! 🛠️

Finding your API key 🗝️

1

Go to Instantly Dashboard

The first step to using the Instantly API platform is to find your API key.

2

Go to Settings → Integrations

To get to your API key, go to your: Instantly Dashboard → Settings → Integrations → API

https://app.instantly.ai/app/settings/integrations

3

Retrieve your API key

The API key helps authenticate your incoming requests and is unique per Instantly workspace.

You need to be on the Hypergrowth plan (or above) to be able to access the API key.

1 2 3 4 5 To get to your API key, go to your: Instantly Dashboard → Settings → Integrations → API https: //app.instantly.ai/app/settings/integrations

Campaign

The campaign endpoints allow you to interact with individual email campaigns, update their options, sending accounts, and status. See below for details.

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

GET
GET
GET
POST
GET
POST
POST
POST
POST
POST
POST

Analytics

The campaign endpoints allow you to interact with individual email campaigns, update their options, sending accounts, and status. See below for details.

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Base URL

Production:

https://api.instantly.ai/api

Lead

The lead endpoints allow you to interact with lead data in your workspace.

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Was this section helpful?

What made this section unhelpful for you?

Endpoints

POST
GET
POST
POST
POST
POST
POST
Was this section helpful?

What made this section unhelpful for you?

Add leads to a campaign

Send a list of lead objects to add to a campaign.

  • A maximum of 500 leads could be uploaded at the same time
  • Only the email field is required

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Your campaign's ID

skip_if_in_workspaceboolean

Skip lead if it exists in any campaigns in the workspace

skip_if_in_campaignboolean

Skip lead if it exists in a campaign

Empty value:
True
leadsarray

Show child attributes

Response

200
Object

Response Attributes

statusstring

Response status

total_sentnumber

Number of leads sent with the request

leads_uploadednumber

Number of uploaded leads

already_in_campaignnumber

Number of leads already in the campaign

invalid_email_countnumber

Number of invalid email addresses in the sent request

duplicate_email_countnumber

Number of duplicate emails in the sent request

remaining_in_plannumber

Remaining upload count for your workspace

Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/lead/add

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 curl --location 'https://api.instantly.ai/api/v1/lead/add' \ --data-raw '{ "api_key": "", "campaign_id": "00000000-0000-0000-0000-000000000000", "skip_if_in_workspace": false, "skip_if_in_campaign": true, "leads": [ { "email": "john@abc.com", "first_name": "John", "last_name": "Doe", "company_name": "Instantly", "personalization": "Loved your latest post", "phone": "123456789", "website": "instantly.ai", "custom_variables": { "favorite_restaurant": "Chipotle", "language": "English" } }, { "email": "jane@abc.com", "first_name": "Jane", "last_name": "Smith", "company_name": "Instantly", "personalization": "Will you be attending the conference in New York?", "phone": "123456789", "website": "instantly.ai", "custom_variables": { "favorite_restaurant": "Chipotle", "language": "English" } } ] }'

Response

{
  "status": "success",
  "total_sent": 2,
  "leads_uploaded": 2,
  "already_in_campaign": null,
  "invalid_email_count": null,
  "duplicate_email_count": null,
  "remaining_in_plan": 24984
}
Was this section helpful?

What made this section unhelpful for you?

Get or search for lead

This endpoint can also be used to search for a lead - if campaign_id is left blank, all leads matching email will be returned.

Query Parameters

api_keystring Required
campaign_idstring

Optional - campaign ID; if left blank, all leads matching the email will be returned

emailstring Required

Email address of the lead

Response

200
Object

Response Attributes

idstring

Lead's ID

timestamp_createdstring

Timestamp created

campaignstring

Campaign ID

statusnumber

Lead's status

contactstring

Lead's email

email_openedboolean

If the lead has opened an email

email_repliedboolean

If the lead has replied

lead_dataobject

Show child attributes

campaign_namestring

Name of the campaign

Was this section helpful?

What made this section unhelpful for you?

Language Box

GET

/v1/lead/get?api_key=API_KEY&campaign_id=00000000-0000-0000-0000-000000000000&email=abc@xyz.com

Select
1 curl --location 'https://api.instantly.ai/api/v1/lead/get?api_key=API_KEY&campaign_id=00000000-0000-0000-0000-000000000000&email=abc%40xyz.com' \

Response

[
  {
    "id": "00dd2f2a-e96b-41e3-b779-d88d91afcef5",
    "timestamp_created": "2023-02-24T07:15:39.370Z",
    "campaign": "00000000-0000-0000-0000-000000000000",
    "status": 1,
    "contact": "abc@xyz.com",
    "email_opened": true,
    "email_replied": false,
    "lead_data": {
      "email": "abc@xyz.com",
      "companyName": "Instantly"
    },
    "campaign_name": "My first campaign"
  }
]
Was this section helpful?

What made this section unhelpful for you?

Delete leads from a campaign

This section allows users to delete specific leads from a campaign. Users can remove leads by providing the campaign ID and other optional parameters, such as deleting leads with matching domains. The action helps users efficiently manage their campaign's lead database by removing unwanted entries.

Body Parameters

api_keystring Required

Your API key

campaign_idstring

Optional campaign id. if not provided, matching leads will be deleted across all campaigns.

delete_all_from_companyboolean

Set to true if you would like to remove all leads with matching domains

delete_listarray

Show child attributes

Response

200
Object

Response Attributes

statusstring
Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/lead/delete

Select
1 2 3 4 5 6 7 8 9 10 curl --location 'https://api.instantly.ai/api/v1/lead/delete' \ --data-raw '{ "api_key": "", "campaign_id": "00000000-0000-0000-0000-000000000000", "delete_all_from_company": false, "delete_list": [ "abc@xyz.com", "123@abc.com" ] }'

Response

{
  "status": "success"
}
Was this section helpful?

What made this section unhelpful for you?

Update lead status

Possible values for new status

Basic types

  • Active
  • Completed
  • Unsubscribed

Additional types

Setting the status to one of these values will also mark the sequence as ‘Completed’ for the lead.

  • Interested
  • Meeting Booked
  • Meeting Completed
  • Closed
  • Out of Office
  • Not Interested
  • Wrong Person

You can similarly send the label text if you'd like to apply custom labels. For example, if you have a custom label called “My Label,” you can simply set the new_status parameter to “My Label”. Please note that this is case-insensitive so it will have the same effect if you send “my label” (instead of “My Label”).

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Campaign ID

emailstring Required

Email address of the lead

new_statusstring Required

New status for the lead, Basic types are active, completed, unsubscribed

Response

200
Object

Response Attributes

statusstring
Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/lead/update/status

Select
1 2 3 4 5 6 7 curl --location 'https://api.instantly.ai/api/v1/lead/update/status' \ --data-raw '{ "api_key": "", "campaign_id": "00000000-0000-0000-0000-000000000000", "email": "abc@xyz.com", "new_status": "Unsubscribed" }'

Response

{
  "status": "success"
}
Was this section helpful?

What made this section unhelpful for you?

Lead Variable | Update

When using this endpoint, all keys appearing in the variables property must already exist in the lead's data.

If you'd like add a new variable, skip to the next section.

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Campaign ID

emailstring Required

Email address of the lead

variablesobject

Show child attributes

Response

200
Object

Response Attributes

statusstring
Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/lead/data/update

Select
1 2 3 4 5 6 7 8 9 10 curl --location 'https://api.instantly.ai/api/v1/lead/data/update' \ --data-raw '{ "api_key": "", "campaign_id": "00000000-0000-0000-0000-000000000000", "email": "abc@xyz.com", "variables": { "firstName": "Doug", "lastName": "Smith" } }'

Response

{
  "status": "success"
}
Was this section helpful?

What made this section unhelpful for you?

Lead Variable | Set

The Lead Variable | Set section allows users to update and set custom variables for a lead within a specific campaign. By providing the email address of the lead and the desired variables, users can customize and enhance their lead data for targeted marketing efforts. This functionality enables users to dynamically adjust and personalize lead information to better engage with potential customers.

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Campaign ID

emailstring Required

Email address of the lead

variablesobject

Show child attributes

Response

200
Object

Response Attributes

statusstring
Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/lead/data/set

Select
1 2 3 4 5 6 7 8 9 10 curl --location 'https://api.instantly.ai/api/v1/lead/data/set' \ --data-raw '{ "api_key": "", "campaign_id": "00000000-0000-0000-0000-000000000000", "email": "abc@xyz.com", "variables": { "firstName": "Doug", "lastName": "Smith" } }'

Response

{
  "status": "success"
}
Was this section helpful?

What made this section unhelpful for you?

Lead Variable | Delete

Use this endpoint to remove attributes (variables) from a lead.

Set variables as a list of attributes you want to remove.

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Campaign ID

emailstring Required

Email address of the lead

variablesarray

Show child attributes

Response

200
Object

Response Attributes

statusstring
Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/lead/data/update

Select
1 2 3 4 5 6 7 8 9 curl --location 'https://api.instantly.ai/api/v1/lead/data/update' \ --data-raw '{ "api_key": "", "campaign_id": "00000000-0000-0000-0000-000000000000", "email": "abc@xyz.com", "variables": [ "favorite_restaurant" ] }'

Response

{
  "status": "success"
}
Was this section helpful?

What made this section unhelpful for you?

Blocklist

The blocklist endpoints allow you to interact with your campaign blocklist. See below for details.

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

POST
POST

Account

The account endpoints allow you to interact with your sending accounts. See below for details.

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

GET
POST
GET
POST
POST
POST
POST

Unibox

The account endpoints allow you to interact with the Instantly Unibox. See below for details.

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

GET
GET
POST
POST

Tags

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

The custom tag endpoints are a set of endpoints that allow you to manage custom tags and associate them with specific resources. Custom tags are labels or categories that you can assign to different entities, such as user accounts or campaigns, to organize and group them based on certain criteria.

Resource Type and Resource ID: The resource type and resource ID are used to uniquely identify a specific resource.

  • Resource Type: The resource type is a way to categorize different types of resources in your application. It helps distinguish between different entities that can have custom tags assigned to them. For example, you might have resource types such as "account" for user accounts and "campaign" for marketing campaigns.
  • Resource ID: The resource ID is a unique identifier for a specific resource within a resource type. It allows you to reference a particular resource when assigning or retrieving custom tags. For example, if you have a user account with an email address "johndoe@instantly.ai", the email address would be the resource ID for the "account" resource type.

Endpoints

POST
GET
GET
PATCH
DELETE
POST

Email Verification

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

The Verification endpoints allow you to verify emails, including those behind catch-all domains.

See below for details.

There are currently two categories of verification endpoints.

  1. Submitting a verification job
  2. Checking the status of a verification job

Endpoints

POST
GET

Custom Tracking Domain

The Custom Tracking Domain endpoints allow you to add, remove, or check status of custom tracking domains that are used for tracking campaign metrics such as opens, link clicks, etc.

Help article: https://help.instantly.ai/en/articles/6984188-custom-tracking-domain

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

POST
GET
DELETE