Custom Tag
/
Patch custom tag

API Explorer (2.0.0)

The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the ApiKeyAuth_token blue text.

Languages
Servers
Instantly API Server
https://api.instantly.ai/
Mock server
https://developer.instantly.ai/_mock/api/v2/

Analytics

Endpoints related to analytics

Operations

Account

An email account that can be used to send campaigns

Operations

Campaign

A campaign that can be sent to a list of recipients

Operations

Email

A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox

Operations

Email Verification

A single email verification

Operations

Lead List

A list used to store leads

Operations

Inbox Placement Test

An inbox placement test

Operations

Inbox Placement Analytics

Analytics data for individual emails in inbox placement tests

Operations

Inbox Placement Blacklist & SpamAssassin Report

Report data for an inbox placement test

Operations

API Key

API Key

Operations

Account Campaign Mapping

Account Campaign Mapping

Operations

Lead

A lead entity representing an individual lead

Operations

Background Job

A background job that can be used to perform long-running tasks

Operations

Custom Tag

A custom tag for organizing and categorizing items

Operations

Custom Tag

A custom tag for organizing and categorizing items

idstring(uuid)read-onlyrequired

Unique identifier for the custom tag

Example: "01959271-1f78-7928-9405-c525e3898835"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the custom tag was created

Example: "2025-03-14T02:17:22.040Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the custom tag was last updated

Example: "2025-03-14T02:17:22.040Z"
organization_idstring(uuid)read-onlyrequired

Organization ID that owns this custom tag

Example: "01959271-1f78-7928-9405-c526f300d9f9"
labelstringrequired

Display label for the custom tag

Example: "Important"
descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
{
  "id": "01959271-1f78-7928-9405-c525e3898835",
  "timestamp_created": "2025-03-14T02:17:22.040Z",
  "timestamp_updated": "2025-03-14T02:17:22.040Z",
  "organization_id": "01959271-1f78-7928-9405-c526f300d9f9",
  "label": "Important",
  "description": "Used for marking important items"
}

Create custom tag

Request

Requires one of the following scopes: custom_tags:create, custom_tags:all, all:create, all:all

Bodyapplication/jsonrequired

The Custom Tag to create

labelstringrequired

Display label for the custom tag

Example: "Important"
descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
curl -i -X POST \
  https://api.instantly.ai/api/v2/custom-tags \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Important"
  }'

Responses

The Custom Tag

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the custom tag

Example: "01959271-1f78-7928-9405-c525e3898835"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the custom tag was created

Example: "2025-03-14T02:17:22.040Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the custom tag was last updated

Example: "2025-03-14T02:17:22.040Z"
organization_idstring(uuid)read-onlyrequired

Organization ID that owns this custom tag

Example: "01959271-1f78-7928-9405-c526f300d9f9"
labelstringrequired

Display label for the custom tag

Example: "Important"
descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
Response
application/json
{
  "id": "01959271-1f78-7928-9405-c525e3898835",
  "timestamp_created": "2025-03-14T02:17:22.040Z",
  "timestamp_updated": "2025-03-14T02:17:22.040Z",
  "organization_id": "01959271-1f78-7928-9405-c526f300d9f9",
  "label": "Important",
  "description": "Used for marking important items"
}

List custom tag

Request

Requires one of the following scopes: custom_tags:read, custom_tags:all, all:read, all:all

Query
limitinteger[ 1 .. 100 ]

The number of items to return

Example: limit=10
starting_afterstring(uuid)

The ID of the last item in the previous page - used for pagination. You can use the value of the next_starting_after field from the previous response.

Example: starting_after=01956fbd-0eb1-72db-a565-82977a586084
searchstring
Example: search=Important
resource_idsstring
Example: resource_ids=id1,id2,id3
tag_idsstring
Example: tag_ids=id1,id2,id3
curl -i -X GET \
  'https://api.instantly.ai/api/v2/custom-tags?limit=10&resource_ids=id1%2Cid2%2Cid3&search=Important&starting_after=01956fbd-0eb1-72db-a565-82977a586084&tag_ids=id1%2Cid2%2Cid3' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of Custom Tag

Bodyapplication/json
itemsArray of objects(Custom Tag)required
items[].​idstring(uuid)read-onlyrequired

Unique identifier for the custom tag

Example: "01959271-1f78-7928-9405-c525e3898835"
items[].​timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the custom tag was created

Example: "2025-03-14T02:17:22.040Z"
items[].​timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the custom tag was last updated

Example: "2025-03-14T02:17:22.040Z"
items[].​organization_idstring(uuid)read-onlyrequired

Organization ID that owns this custom tag

Example: "01959271-1f78-7928-9405-c526f300d9f9"
items[].​labelstringrequired

Display label for the custom tag

Example: "Important"
items[].​descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
next_starting_afterstring

The filter for getting the next items after this one, this could either be a UUID, a MongoDB ID, a timestamp, on an email depending on the specific API

Example: "0000-0000-0000-0000"
Response
application/json
{
  "items": [
    { … }
  ],
  "next_starting_after": "0000-0000-0000-0000"
}

Get custom tag

Request

Requires one of the following scopes: custom_tags:read, custom_tags:all, all:read, all:all

Path
idstringrequired
curl -i -X GET \
  'https://api.instantly.ai/api/v2/custom-tags/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested Custom Tag

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the custom tag

Example: "01959271-1f78-7928-9405-c525e3898835"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the custom tag was created

Example: "2025-03-14T02:17:22.040Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the custom tag was last updated

Example: "2025-03-14T02:17:22.040Z"
organization_idstring(uuid)read-onlyrequired

Organization ID that owns this custom tag

Example: "01959271-1f78-7928-9405-c526f300d9f9"
labelstringrequired

Display label for the custom tag

Example: "Important"
descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
Response
application/json
{
  "id": "01959271-1f78-7928-9405-c525e3898835",
  "timestamp_created": "2025-03-14T02:17:22.040Z",
  "timestamp_updated": "2025-03-14T02:17:22.040Z",
  "organization_id": "01959271-1f78-7928-9405-c526f300d9f9",
  "label": "Important",
  "description": "Used for marking important items"
}

Patch custom tag

Request

Requires one of the following scopes: custom_tags:update, custom_tags:all, all:update, all:all

Path
idstringrequired
Bodyapplication/json
non-empty
labelstring

Display label for the custom tag

Example: "Important"
descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
curl -i -X PATCH \
  'https://api.instantly.ai/api/v2/custom-tags/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The updated Custom Tag

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the custom tag

Example: "01959271-1f78-7928-9405-c525e3898835"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the custom tag was created

Example: "2025-03-14T02:17:22.040Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the custom tag was last updated

Example: "2025-03-14T02:17:22.040Z"
organization_idstring(uuid)read-onlyrequired

Organization ID that owns this custom tag

Example: "01959271-1f78-7928-9405-c526f300d9f9"
labelstringrequired

Display label for the custom tag

Example: "Important"
descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
Response
application/json
{
  "id": "01959271-1f78-7928-9405-c525e3898835",
  "timestamp_created": "2025-03-14T02:17:22.040Z",
  "timestamp_updated": "2025-03-14T02:17:22.040Z",
  "organization_id": "01959271-1f78-7928-9405-c526f300d9f9",
  "label": "Important",
  "description": "Used for marking important items"
}

Delete custom tag

Request

Requires one of the following scopes: custom_tags:delete, custom_tags:all, all:delete, all:all

Path
idstringrequired
curl -i -X DELETE \
  'https://api.instantly.ai/api/v2/custom-tags/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The deleted Custom Tag

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the custom tag

Example: "01959271-1f78-7928-9405-c525e3898835"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the custom tag was created

Example: "2025-03-14T02:17:22.040Z"
timestamp_updatedstring(date-time)read-onlyrequired

Timestamp when the custom tag was last updated

Example: "2025-03-14T02:17:22.040Z"
organization_idstring(uuid)read-onlyrequired

Organization ID that owns this custom tag

Example: "01959271-1f78-7928-9405-c526f300d9f9"
labelstringrequired

Display label for the custom tag

Example: "Important"
descriptionstring

Detailed description of the custom tag purpose

Example: "Used for marking important items"
Response
application/json
{
  "id": "01959271-1f78-7928-9405-c525e3898835",
  "timestamp_created": "2025-03-14T02:17:22.040Z",
  "timestamp_updated": "2025-03-14T02:17:22.040Z",
  "organization_id": "01959271-1f78-7928-9405-c526f300d9f9",
  "label": "Important",
  "description": "Used for marking important items"
}

Assign or unassign tags to resources

Request

This can be used for both accounts and campaigns. Please check the resource_type field for more information.

Bodyapplication/jsonrequired
tag_idsArray of strings(uuid)required
Example: ["01959271-2fbb-7ede-a3a8-9626653063e3"]
resource_typenumberrequired

The resource type to assign or unassign the tags to

Enum ValueDescription
1

Account

2

Campaign

Example: 1
resource_idsArray of stringsrequired
Example: ["resource-1","resource-2"]
assignbooleanrequired
Example: true
selected_allboolean
Example: false
filterstring or object
One of:
string
Enum"ACC_FILTER_PAUSED""ACC_FILTER_ERROR""ACC_FILTER_NO_CTD""ACC_FILTER_PW_ACCOUNTS""ACC_FILTER_DFY""ACC_FILTER_W_ACTIVE""ACC_FILTER_W_PAUSED""ACC_FILTER_W_ERROR"
curl -i -X POST \
  https://api.instantly.ai/api/v2/custom-tags/toggle-resource \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tag_ids": [
      "01959271-2fbb-7ede-a3a8-9626653063e3"
    ],
    "resource_type": 1,
    "resource_ids": [
      "resource-1",
      "resource-2"
    ],
    "assign": true
  }'

Responses

Default Response

Bodyapplication/json
successboolean
Example: true
Response
application/json
{
  "success": true
}

Block List Entry

A blocked email or domain

Operations

Lead Label

A custom label for categorizing and managing leads

Operations

Workspace

A workspace entity representing a workspace

Operations

Workspace Group Member

A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.

Operations

Workspace Member

A member of a workspace with associated user details

Operations

Campaign Subsequence

A subsequence entity representing a follow-up sequence

Operations

Schemas