openapi: 3.2.0 info: title: Explorer Lead List API description: 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. version: 2.0.0 servers: - url: https://api.instantly.ai description: Instantly API Server security: - ApiKeyAuth: [] tags: - name: LeadList description: A list used to store leads x-group: Lead List paths: /api/v2/lead-lists: post: operationId: createLeadList summary: Create lead list tags: - LeadList description: 'Requires one of the following scopes: `lead_lists:create`, `lead_lists:all`, `all:create`, `all:all`' requestBody: content: application/json: schema: title: CreateLead List description: The Lead List to create type: object properties: has_enrichment_task: type: - boolean - 'null' description: Whether this list runs the enrichment process on every added lead or not example: false owned_by: type: - string - 'null' description: User ID of the owner of this lead list. Defaults to the user that created the list format: uuid example: 019ffad2-5c79-7b95-8be2-2dc717cc24c7 name: type: string description: Name of the lead list example: My Lead List required: - name additionalProperties: false required: true description: The Lead List to create responses: '200': description: The Lead List content: application/json: schema: $ref: '#/components/schemas/LeadList' '400': description: Invalid request body (e.g. missing required fields, or invalid field values) content: application/json: schema: type: object properties: statusCode: type: number enum: - 400 examples: - 400 example: 400 error: type: string enum: - Bad Request examples: - Bad Request example: Bad Request message: type: string examples: - body must have required property 'name' example: body must have required property 'name' required: - statusCode - error - message '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message get: operationId: listLeadList summary: List lead list tags: - LeadList description: 'Requires one of the following scopes: `lead_lists:read`, `lead_lists:all`, `all:read`, `all:all`' parameters: - schema: type: integer minimum: 1 maximum: 100 example: 10 example: 10 in: query name: limit required: false description: The number of items to return - schema: type: string example: '2025-03-07T00:00:00.000Z' example: '2025-03-07T00:00:00.000Z' in: query name: starting_after required: false description: The starting after timestamp to filter lead lists by. - schema: type: boolean example: true example: true in: query name: has_enrichment_task required: false description: Whether the list has an enrichment task. - schema: type: string example: Summer 2025 List example: Summer 2025 List in: query name: search required: false description: The search query to filter lead lists by. responses: '200': description: The list of Lead List content: application/json: schema: type: object properties: items: type: array description: The list of Lead List items: $ref: '#/components/schemas/LeadList' next_starting_after: type: string examples: - 019ffad2-9c3a-776c-8b48-37e10199c288 - '2026-08-13T11:12:14.394Z' description: The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API example: 019ffad2-9c3a-776c-8b48-37e10199c288 additionalProperties: false required: - items '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message /api/v2/lead-lists/{id}: get: operationId: getLeadList summary: Get lead list tags: - LeadList description: 'Requires one of the following scopes: `lead_lists:read`, `lead_lists:all`, `all:read`, `all:all`' parameters: - schema: type: string format: uuid example: 019ffad2-9c3b-7cc8-976d-4ad656e3bf47 example: 019ffad2-9c3b-7cc8-976d-4ad656e3bf47 in: path name: id required: true description: The ID of the requested item responses: '200': description: The requested Lead List content: application/json: schema: $ref: '#/components/schemas/LeadList' '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message patch: operationId: patchLeadList summary: Patch lead list tags: - LeadList description: 'Requires one of the following scopes: `lead_lists:update`, `lead_lists:all`, `all:update`, `all:all`' requestBody: content: application/json: schema: type: object properties: has_enrichment_task: type: - boolean - 'null' description: Whether this list runs the enrichment process on every added lead or not example: false owned_by: type: - string - 'null' description: User ID of the owner of this lead list. Defaults to the user that created the list format: uuid example: 019ffad2-5c79-7b95-8be2-2dc717cc24c7 name: type: string description: Name of the lead list example: My Lead List required: [] additionalProperties: false minProperties: 1 parameters: - schema: type: string format: uuid example: 019ffad2-9c3b-7cc8-976d-4ad7004c6ee4 example: 019ffad2-9c3b-7cc8-976d-4ad7004c6ee4 in: path name: id required: true description: The ID of the item to update responses: '200': description: The updated Lead List content: application/json: schema: $ref: '#/components/schemas/LeadList' '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message delete: operationId: deleteLeadList summary: Delete lead list tags: - LeadList description: 'Requires one of the following scopes: `lead_lists:delete`, `lead_lists:all`, `all:delete`, `all:all`' requestBody: content: application/json: schema: type: 'null' example: null parameters: - schema: type: string format: uuid example: 019ffad2-9c3c-7701-b23e-bcb362d6d1c6 example: 019ffad2-9c3c-7701-b23e-bcb362d6d1c6 in: path name: id required: true description: The ID of the item to delete responses: '200': description: The deleted Lead List content: application/json: schema: $ref: '#/components/schemas/LeadList' '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message /api/v2/lead-lists/{id}/verification-stats: get: operationId: getVerificationStats summary: Get verification statistics for a lead list tags: - LeadList description: Get verification statistics for a lead list parameters: - schema: type: string format: uuid example: 019ffad2-9c3c-7701-b23e-bcb4770f23b9 example: 019ffad2-9c3c-7701-b23e-bcb4770f23b9 in: path name: id required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: stats: type: object properties: verified: type: number description: Count of verified leads example: 150 invalid: type: number description: Count of invalid leads example: 25 risky: type: number description: Count of risky leads example: 10 catch_all: type: number description: Count of catch all leads example: 5 job_change: type: number description: Count of job change leads example: 2 verification_job_pending_leadfinder: type: number description: Count of verification job pending leads for leadfinder example: 11 verification_job_pending_user: type: number description: Count of verification job pending leads for user example: 12 description: Sums up the leads by their verification status example: verified: 150 invalid: 25 risky: 10 catch_all: 5 job_change: 2 verification_job_pending_leadfinder: 11 verification_job_pending_user: 12 total_leads: type: number description: Total number of leads in the list example: 203 required: - stats - total_leads '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message components: schemas: LeadList: title: Lead List description: A list used to store leads x-tags: - Schemas - LeadList type: object properties: id: type: string description: Unique identifier for the lead list readOnly: true format: uuid example: 019ffad2-5c79-7b95-8be2-2dc5f047c029 organization_id: type: string description: Organization ID that owns this lead list readOnly: true format: uuid example: 019ffad2-5c79-7b95-8be2-2dc6dc8d3540 has_enrichment_task: type: - 'null' - boolean description: Whether this list runs the enrichment process on every added lead or not example: false owned_by: type: - 'null' - string description: User ID of the owner of this lead list. Defaults to the user that created the list format: uuid example: 019ffad2-5c79-7b95-8be2-2dc717cc24c7 name: type: string description: Name of the lead list example: My Lead List timestamp_created: type: string description: Timestamp when the lead list was created readOnly: true format: date-time example: '2026-08-13T11:11:58.073Z' required: - id - organization_id - name - timestamp_created additionalProperties: false securitySchemes: ApiKeyAuth: type: http scheme: bearer