Hi {{firstName}},
I noticed you work in {{industry}}...
" type: type: string description: Type of sequence variant to create. enum: - email.scratch - linkedin.connect - linkedin.message - linkedin.inmail example: "email.scratch" responses: "200": description: Variant created successfully content: application/json: schema: type: object properties: status: type: string example: "success" message: type: string example: "Variant created successfully" data: type: object properties: variantLabel: type: string example: "B" variant: type: object properties: _id: type: string example: "695f4817767b0c15919ccba3" name: type: string example: "B" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/campaign/sequences: get: tags: [Campaigns] summary: List campaign sequences description: Get all sequences under a campaign, including sequence variants. operationId: getCampaignSequences parameters: - name: campaignId in: query required: true schema: type: string description: Campaign ID whose sequences should be fetched. example: "6836de752d99a2d041409812" - name: x-api-key in: header required: true schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" description: Your API key for authentication. responses: "200": description: Campaign sequences fetched successfully. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Campaign sequences fetched successfully" data: type: array items: type: object properties: _id: type: string example: "695f4817767b0c15919ccba2" step: type: number example: 1 waitDays: type: number example: 3 variants: type: array items: type: object properties: _id: type: string example: "695f4817767b0c15919ccba3" name: type: string example: "A" subject: type: string example: "Quick question" type: type: string example: "email.scratch" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/campaign/variants: get: tags: [Campaigns] summary: List sequence variants description: Get all variants under a campaign sequence. operationId: getSequenceVariants parameters: - name: sequenceId in: query required: true schema: type: string description: Sequence ID whose variants should be fetched. example: "695f4817767b0c15919ccba2" - name: x-api-key in: header required: true schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" description: Your API key for authentication. responses: "200": description: Sequence variants fetched successfully. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Sequence variants fetched successfully" data: type: array items: type: object properties: _id: type: string example: "695f4817767b0c15919ccba3" name: type: string example: "A" subject: type: string example: "Quick question" type: type: string example: "email.scratch" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/campaign/variants/{id}: put: tags: [Campaigns] summary: Update sequence variant description: Update subject, body, type, or active status for a sequence variant. operationId: updateVariant parameters: - name: id in: path required: true schema: type: string description: The variant ID to update. example: "695f4817767b0c15919ccba3" - name: x-api-key in: header required: true schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" description: Your API key for authentication. requestBody: required: true content: application/json: schema: type: object properties: subject: type: string description: Subject line for the variant. example: "Updated subject" body: type: string description: HTML content of the email or message body. example: "Updated message for {{firstName}}
" type: type: string enum: - email.scratch - linkedin.connect - linkedin.message - linkedin.inmail example: "email.scratch" isActive: type: boolean description: Enable or disable the variant. example: true responses: "200": description: Variant updated successfully. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Variant updated successfully" data: type: object properties: _id: type: string example: "695f4817767b0c15919ccba3" subject: type: string example: "Updated subject" type: type: string example: "email.scratch" isActive: type: boolean example: true "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/campaign/sequences/{id}: put: tags: [Campaigns] summary: Update campaign sequence wait days description: Update the wait days for a specific campaign sequence. operationId: updateSequence parameters: - name: id in: path required: true schema: type: string description: The sequence ID to update example: "695f4817767b0c15919ccba2" - name: x-api-key in: header required: true schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" description: Your API key for authentication. requestBody: required: true content: application/json: schema: type: object required: - waitDays properties: waitDays: type: integer description: Number of days to wait before sending this sequence step. minimum: 1 example: 5 responses: "200": description: Sequence updated successfully content: application/json: schema: type: object properties: status: type: string example: "success" message: type: string example: "Sequence updated successfully" data: type: object properties: _id: type: string example: "695f4817767b0c15919ccba2" waitDays: type: number example: 5 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/campaign/sequences-delete: delete: tags: [Campaigns] summary: Delete a campaign sequence description: Delete a specific campaign sequence along with all its variants. Remaining sequences will be automatically reordered. operationId: deleteSequence parameters: - name: x-api-key in: header required: true schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" description: Your API key for authentication. requestBody: required: true content: application/json: schema: type: object required: - sequenceId properties: sequenceId: type: string description: The sequence ID to delete example: "695f4817767b0c15919ccba2" responses: "200": description: Sequence deleted successfully content: application/json: schema: type: object properties: status: type: string example: "success" message: type: string example: "Step 2 sequence deleted along with 3 variant(s) and 2 sequence step(s) reordered." data: type: object properties: deletedVariantsCount: type: number example: 3 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/campaign/variants-delete: delete: tags: [Campaigns] summary: Delete a sequence variant description: Delete a specific variant from a sequence. Cannot delete the last remaining variant. operationId: deleteVariant parameters: - name: x-api-key in: header required: true schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" description: Your API key for authentication. requestBody: required: true content: application/json: schema: type: object required: - variantId properties: variantId: type: string description: The variant ID to delete example: "695f4817767b0c15919ccba3" responses: "200": description: Variant deleted successfully content: application/json: schema: type: object properties: status: type: string example: "success" message: type: string example: "Variant deleted successfully" data: type: object properties: remainingVariantsCount: type: number example: 2 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # ─── Accounts ─────────────────────────────────────────────────── /v2/account/list: get: tags: [Accounts] summary: List accounts description: This endpoint fetch a paginated list of accounts associated with the provided API key. operationId: getAccountsList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: skip in: query description: Used for pagination required: false schema: type: integer format: int32 example: 0 - name: limit in: query description: Used for pagination (max 50) required: false schema: type: integer format: int32 example: 10 responses: "200": description: A paginated list of accounts content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Accounts fetched successfully" data: type: array items: type: object properties: _id: type: string example: "6836e12d2d99a2d0416c0260" id: type: string example: "6836e12d2d99a2d0416c0260" emailEngineAccountId: type: string example: "a56f2139-30a7-4158-858f-a8e2543eff55" email: type: string example: "john.smith@example.com" provider: type: string example: "custom_imap_smtp" domain: type: string example: "example.com" status: type: string example: "connected" eEngineStatus: type: string example: "connected" isVerified: type: boolean example: true deleted: type: boolean example: false workspaceId: type: string example: "67502c0f567a5a46df3e7ec9" connectionWith: type: string example: "660bda6c35002ff627aaa3b8" unreadCount: type: integer example: 5 freeUserOtherAccounts: type: boolean example: false migrated: type: boolean example: true correctedTls: type: boolean example: false iFrame: type: boolean example: false eEngineDeletion: type: boolean example: false partnerAccountId: type: string nullable: true example: null accountError: type: string example: "" tags: type: array items: type: string example: [] createdAt: type: string format: date-time example: "2024-03-15T08:30:00.000Z" updatedAt: type: string format: date-time example: "2024-11-20T12:45:30.000Z" name: type: object properties: first: type: string example: "John" last: type: string example: "Smith" campaign: type: object properties: dailyLimit: type: integer example: 75 waitTime: type: integer example: 2 customDomain: type: object properties: isEnable: type: boolean example: false warmup: type: object properties: status: type: string example: "active" warmupDisable: type: boolean example: false softBounceCount: type: integer example: 0 warmupBounceCount: type: integer example: 0 warmupRejectTotal: type: integer example: 0 filterTag: type: string example: "B723G82E" basicSetting: type: object properties: increasePerDay: type: integer example: 2 slowWarmupDisabled: type: boolean example: false limitPerDay: type: integer example: 30 replyRate: type: integer example: 40 alertBlock: type: boolean example: true advanceSetting: type: object properties: weekdayOnly: type: boolean example: false readEmulation: type: boolean example: true customTrackingDomain: type: boolean example: false openRate: type: integer example: 100 spamProtectionRate: type: integer example: 100 markImportantRate: type: integer example: 100 deliveryTest: type: object properties: retry: type: integer example: 1 deliveryTestId: type: string example: "b35d880e-dd27-53fc-b6g9-83f2c49f135f" timeStamp: type: string format: date-time example: "2024-06-12T14:25:10.123Z" imap: type: object properties: username: type: string example: "john.smith@example.com" host: type: string example: "imap.example.com" port: type: integer example: 993 smtp: type: object properties: username: type: string example: "john.smith@example.com" host: type: string example: "smtp.example.com" port: type: integer example: 587 __v: type: integer example: 0 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/account/status: get: tags: [Accounts] summary: Get account status description: Fetch the current status, including the warm-up status, of an account by its email. operationId: getAccountStatus parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: email in: query description: The email of the account for which you want to retrieve the status. required: true schema: type: string example: "abc@xyz.com" responses: "200": description: Successfully retrieved the account status. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Accounts status fetched successfully" data: type: object properties: account: type: string example: "example@gmail.com" status: type: string enum: [connected, disconnected, active, inactive] example: "connected" warmupStatus: type: string enum: [enabled, disabled, paused] example: "enabled" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/account/vitals: post: tags: [Accounts] summary: Check account vitals description: This endpoint allows you to quickly check if the MX, SPF, DKIM, and DMARC records have been properly set for a list of domains. operationId: getAccountVitals parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - accounts properties: accounts: type: array description: List of account email addresses to retrieve vitals for items: type: string example: ["test@successai.com", "contact@company.com"] responses: "200": description: DNS Vitals of accounts retrieved successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Details fetched successfully" data: type: object properties: successList: type: array items: type: object properties: domain: type: string example: "example.com" mx: type: boolean example: true spf: type: boolean example: true dkim: type: string example: "google" dmarc: type: boolean example: true failureList: type: array items: type: object properties: domain: type: string example: "testdomain.org" mx: type: boolean example: false spf: type: boolean example: false dkim: type: string example: "N/A" dmarc: type: boolean example: false example: status: "success" success: true message: "Details fetched successfully" data: successList: - domain: "example.com" mx: true spf: true dkim: "google" dmarc: true failureList: - domain: "testdomain.org" mx: false spf: false dkim: "N/A" dmarc: false "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/account/warmup/enable: post: tags: [Accounts] summary: Enable warmup description: This endpoint enables the warmup process for the specified account. operationId: enableWarmup parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string description: Email address of the account to enable warmup for example: "abc@successai.com" responses: "200": description: Warmup enabled successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Warmup enabled successfully" data: type: object properties: _id: type: string example: "7a47f34g4f11c4f2638e1482" email: type: string example: "john.smith@example.com" warmup: type: object properties: status: type: string example: "enabled" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/account/warmup/pause: post: tags: [Accounts] summary: Pause warmup description: This endpoint pause the warmup process for the specified account. operationId: pauseWarmup parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string description: Email address of the account to pause warmup for example: "abc@successai.com" responses: "200": description: Warmup paused successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Warmup paused successfully" data: type: object properties: _id: type: string example: "8b58g45h5g22d5g3749f2593" email: type: string example: "jane.doe@company.com" warmup: type: object properties: status: type: string example: "paused" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/account/delete: delete: tags: [Accounts] summary: Delete account description: This endpoint delete the specified account. operationId: deleteAccount parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - emails properties: emails: type: array description: List of email addresses of the accounts to delete items: type: string example: ["test@successai.com", "test2@company.com"] responses: "200": description: Account deleted successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Accounts deleted successfully" data: type: "null" example: null example: status: "success" success: true message: "Accounts deleted successfully" data: null "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # ─── Analytics ────────────────────────────────────────────────── /v2/analytics/campaign/summary: get: tags: [Analytics] summary: Get campaign summary description: Retrieve the lead status summary and analytics data for a given campaign, including total leads, contacted status, engagement metrics, and completion rates. operationId: getCampaignSummary parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: campaignId in: query required: true description: The unique identifier of the campaign. schema: type: string example: "6836de752d99a2d041409812" responses: "200": description: Successfully retrieved campaign analytics summary. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Campaign analytics graph data fetched successfully" data: type: object properties: campaignId: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" campaignName: type: string description: The name of the campaign. example: "Update campaign name" totalLeads: type: integer description: Total number of leads in the campaign. example: 2 contacted: type: integer description: Number of leads that have been contacted. example: 0 notYetContacted: type: integer description: Number of leads not yet contacted. example: 0 leadsWhoRead: type: integer description: Number of leads who opened/read the email. example: 0 leadsWhoReplied: type: integer description: Number of leads who replied to the email. example: 0 bounced: type: integer description: Number of emails that bounced. example: 1 unsubscribed: type: integer description: Number of leads who unsubscribed. example: 0 completed: type: integer description: Number of leads who completed the campaign sequence. example: 1 example: status: "success" success: true message: "Campaign analytics graph data fetched successfully" data: campaignId: "6836de752d99a2d041409812" campaignName: "Update campaign name" totalLeads: 2 contacted: 0 notYetContacted: 0 leadsWhoRead: 0 leadsWhoReplied: 0 bounced: 1 unsubscribed: 0 completed: 1 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v2/analytics/campaign/count: get: tags: [Analytics] summary: Get campaign count description: Retrieve email engagement count data for a specific campaign within a date range, including emails sent, read, leads contacted, and replies received. operationId: getCampaignCount parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: campaignId in: query required: true description: The unique identifier of the campaign. schema: type: string example: "6836de752d99a2d041409812" - name: startDate in: query required: true description: The start date for the data in format MM-DD-YYYY. schema: type: string format: MM-DD-YYYY example: "01-01-2027" - name: endDate in: query required: false description: The end date for the data in format MM-DD-YYYY. If not provided, data will be retrieved up to the current date. schema: type: string format: MM-DD-YYYY example: "01-31-2027" responses: "200": description: Successfully retrieved campaign count data. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Campaign count data fetched successfully" data: type: object properties: campaignId: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" campaignName: type: string description: The name of the campaign. example: "Update campaign name" emailsRead: type: integer description: Number of emails that were opened/read. example: 0 leadsReplied: type: integer description: Number of leads who replied to emails. example: 0 newLeadsContacted: type: integer description: Number of new leads contacted during the date range. example: 2 emailsSent: type: integer description: Total number of emails sent during the date range. example: 2 example: status: "success" success: true message: "Campaign count data fetched successfully" data: campaignId: "6836de752d99a2d041409812" campaignName: "Update campaign name" emailsRead: 0 leadsReplied: 0 newLeadsContacted: 2 emailsSent: 2 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v2/analytics/account/warmup/summary: get: tags: [Analytics] summary: Get account warmup summary data description: Retrieve warmup summary data for an email account within a date range, separating outbound sent placement from inbound spam rescue counts. operationId: getAccountWarmupSummary parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: email in: query required: true description: The email address of the account. schema: type: string example: "user@example.com" - name: startDate in: query required: true description: The start date for the data in format MM-DD-YYYY. schema: type: string format: MM-DD-YYYY example: "01-01-2027" - name: endDate in: query required: false description: The end date for the data in format MM-DD-YYYY. If not provided, data will be retrieved up to the current date. schema: type: string format: MM-DD-YYYY example: "01-31-2027" responses: "200": description: Successfully retrieved account warmup summary data. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Account summary data fetched successfully" data: type: object properties: inboxCount: type: integer description: Number of emails in the inbox during the date range. example: 0 receivedCount: type: integer description: Total number of emails received during the date range. example: 0 sentCount: type: integer description: Total number of emails sent during the date range. example: 0 spamCount: type: integer description: Number of sent warmup emails that landed in spam during the date range. example: 0 spamRescuedCount: type: integer description: Number of received warmup emails rescued from spam during the date range. example: 0 example: status: "success" success: true message: "Account summary data fetched successfully" data: inboxCount: 0 receivedCount: 0 sentCount: 0 spamCount: 0 spamRescuedCount: 0 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" /v2/analytics/account/campaign/count: get: tags: [Analytics] summary: Get email campaign stats for the current day description: Retrieve email engagement statistics for the current day, including sent, opened, replied, and clicked counts. If an email is provided, it returns stats for that specific account; otherwise, it returns stats for all accounts in the workspace. operationId: getAccountCampaignCount parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: email in: query required: false description: The email address for which you want to retrieve stats. If not provided, stats for all accounts will be returned. schema: type: string example: "john@example.com" responses: "200": description: Successfully retrieved current day email campaign stats. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Campaign emails sent today fetched successfully" data: type: array items: type: object properties: accountId: type: string description: The unique identifier of the email account. example: "6836e12d2d99a2d0416c0260" email: type: string description: The email address of the account. example: "john@example.com" sent: type: integer description: Number of emails sent today. example: 0 open: type: integer description: Number of emails opened today. example: 0 reply: type: integer description: Number of email replies received today. example: 0 click: type: integer description: Number of email link clicks today. example: 0 example: status: "success" success: true message: "Campaign emails sent today fetched successfully" data: - accountId: "6836e12d2d99a2d0416c0260" email: "john@example.com" sent: 0 open: 0 reply: 0 click: 0 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "500": $ref: "#/components/responses/InternalError" # ─── Contacts ────────────────────────────────────────────────── /v2/contact/add: post: tags: [Contacts] summary: Add contacts to a campaign description: | Upload a list of contact objects to add to a campaign. - **A maximum of 500 contacts can be uploaded at once.** - **Only the `email` field is required.** operationId: addContacts parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - campaignId - contacts properties: campaignId: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" contacts: type: array description: List of contact objects to add to the campaign (max 500). maxItems: 500 items: type: object required: - email properties: email: type: string format: email description: The email address of the contact. example: "john.doe@company.com" firstName: type: string description: The first name of the contact. example: "John" lastName: type: string description: The last name of the contact. example: "Doe" companyName: type: string description: The company name of the contact. example: "Tech Solutions Inc" location: type: string description: The location of the contact. example: "San Francisco, CA" iceBreaker: type: string description: An icebreaker for initiating conversation with the contact. example: "I noticed your recent article on AI trends" website: type: string description: The website of the contact or their company. example: "techsolutions.com" customVariables: type: object description: Custom variables that can be used in email templates. additionalProperties: type: string example: favoriteRestaurant: "The Local Bistro" language: "English" example: campaignId: "6836de752d99a2d041409812" contacts: - email: "john.doe@company.com" firstName: "John" lastName: "Doe" companyName: "Tech Solutions Inc" location: "San Francisco, CA" iceBreaker: "I noticed your recent article on AI trends" website: "techsolutions.com" customVariables: favoriteRestaurant: "The Local Bistro" language: "English" - email: "jane.smith@startup.io" firstName: "Jane" lastName: "Smith" companyName: "Innovation Startup" location: "Austin, TX" iceBreaker: "Congratulations on your recent funding round" website: "startup.io" customVariables: favoriteRestaurant: "Farm to Table" language: "English" responses: "200": description: Successfully added contacts to the campaign. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "V2 - Contacts added to campaign successfully" data: type: object properties: totalSent: type: integer description: Total number of contacts sent in the request. example: 2 contactsUploaded: type: integer description: Number of contacts successfully uploaded to the campaign. example: 2 alreadyInCampaign: type: integer description: Number of contacts already in the campaign (skipped). example: 1 invalidEmailCount: type: integer description: Number of contacts with invalid email addresses. example: 0 duplicateEmailCount: type: integer description: Number of duplicate email addresses found in the request. example: 0 remainingInPlan: type: integer description: Remaining contact quota in your current plan. example: 17816 example: status: "success" success: true message: "V2 - Contacts added to campaign successfully" data: totalSent: 2 contactsUploaded: 2 alreadyInCampaign: 1 invalidEmailCount: 0 duplicateEmailCount: 0 remainingInPlan: 17816 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/contact/get: get: tags: [Contacts] summary: Get or search for a contact description: Retrieve contact details by email address. If `campaignId` is provided, returns the contact from that specific campaign. If left blank, returns the contact data from all campaigns matching the email. operationId: getContact parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: email in: query required: true schema: type: string format: email description: The email address to search for. example: "john.doe@company.com" - name: campaignId in: query required: false schema: type: string description: Optional - campaign ID to filter results. example: "6836de752d99a2d041409812" responses: "200": description: Successfully retrieved contact information. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Lead fetched successfully" data: type: object properties: _id: type: string example: "696a10276ba5be8ce45e09f9" email: type: string format: email example: "jane.smith@company.com" firstName: type: string example: "Jane" lastName: type: string example: "Smith" companyName: type: string example: "Tech Innovations Inc" location: type: string example: "Seattle, WA" city: type: string example: "" state: type: string example: "" country: type: string example: "" industry: type: string example: "" iceBreaker: type: string example: "I saw your recent post about cloud architecture" website: type: string example: "techinnovations.com" status: type: string enum: [ not contacted, contacted, replied, bounced, unsubscribed, completed, ] example: "not contacted" interest_status: type: boolean example: false linkedinStatus: type: array items: type: string example: [] isRead: type: boolean example: false test: type: boolean example: false open: type: boolean example: false variables: type: array items: type: object properties: variableTitle: type: string example: "favoriteProduct" variableValue: type: string example: "Cloud Platform" _id: type: string example: "696a10276ba5be8ce45e09fa" campaign: type: string example: "6836de752d99a2d041409812" createdBy: type: string example: "67502c0f567a5a46df3e7eb8" workspaceId: type: string example: "67502c0f567a5a46df3e7ec9" createdAt: type: string format: date-time example: "2026-01-16T10:17:11.299Z" updatedAt: type: string format: date-time example: "2026-01-16T10:17:11.299Z" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/contact/delete: post: tags: [Contacts] summary: Delete contacts from a campaign description: Delete specific contacts from a campaign by providing a list of email addresses. operationId: deleteContacts parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - campaignId - deleteList properties: campaignId: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" deleteList: type: array items: type: string format: email description: List of email addresses to be deleted from the campaign. example: ["john.doe@company.com", "jane.smith@startup.io"] example: campaignId: "6836de752d99a2d041409812" deleteList: - "john.doe@company.com" - "jane.smith@startup.io" responses: "200": description: Successfully deleted contacts from the campaign. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "V2 - Contacts deleted from campaign successfully" data: type: object example: {} "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/contact/update/status: post: tags: [Contacts] summary: Update contact status description: | Update the status of a specific contact within a campaign. **Possible values for newStatus:** **Basic types:** - `Active` - `Completed` - `Unsubscribed` **Additional types (marks sequence as Completed):** - `Interested` - `Meeting Booked` - `Meeting Completed` - `Closed` - `Out of Office` - `Not Interested` - `Wrong Person` You can also send custom label text (case-insensitive). operationId: updateContactStatus parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - campaign_id - email - new_status properties: campaign_id: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" email: type: string format: email description: The email address of the contact. example: "john.doe@company.com" new_status: type: string description: The new status to assign to the contact. example: "Interested" example: campaign_id: "6836de752d99a2d041409812" email: "john.doe@company.com" new_status: "Interested" responses: "200": description: Successfully updated contact status. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Lead status updated successfully" data: type: object properties: _id: type: string example: "6836ded42d99a2d04146d880" email: type: string example: "jane.smith@startup.io" status: type: string example: "interested" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/contact/data/update: post: tags: [Contacts] summary: Contact Variable | Update description: Update existing variables for a contact in a campaign. All keys must already exist. operationId: updateContactVariables parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - campaignId - email - variables properties: campaignId: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" email: type: string format: email description: The email address of the contact. example: "john.doe@company.com" variables: type: object description: Key-value pairs of variables to update (must exist). additionalProperties: type: string example: firstName: "Jonathan" lastName: "Anderson" example: campaignId: "6836de752d99a2d041409812" email: "john.doe@company.com" variables: firstName: "Jonathan" lastName: "Anderson" responses: "200": description: Successfully updated contact variables. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Lead variables updated successfully" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/contact/data/set: post: tags: [Contacts] summary: Contact Variable | Set description: Set or add custom variables for a contact. Can create new variables that don't exist. operationId: setContactVariables parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - campaignId - email - variables properties: campaignId: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" email: type: string format: email description: The email address of the contact. example: "john.doe@company.com" variables: type: object description: Key-value pairs of variables to set (can be new). additionalProperties: type: string example: firstName: "Michael" lastName: "Johnson" customField: "Premium Customer" example: campaignId: "6836de752d99a2d041409812" email: "john.doe@company.com" variables: firstName: "Michael" lastName: "Johnson" customField: "Premium Customer" responses: "200": description: Successfully set contact variables. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Lead variables set successfully" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/contact/data/remove: post: tags: [Contacts] summary: Contact Variable | Delete description: Remove specific custom variables from a contact. operationId: removeContactVariables parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - campaignId - email - variables properties: campaignId: type: string description: The unique identifier of the campaign. example: "6836de752d99a2d041409812" email: type: string format: email description: The email address of the contact. example: "john.doe@company.com" variables: type: array description: Array of variable names to remove. items: type: string example: ["customField", "tempVariable"] example: campaignId: "6836de752d99a2d041409812" email: "john.doe@company.com" variables: - "customField" - "tempVariable" responses: "200": description: Successfully deleted contact variables. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Lead variables deleted successfully" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # ─── Contacts API─────────────────────────────────────────────── /v2/mixed_people/search: post: tags: [Contacts API] summary: People Search description: | This endpoint searches for People and returns fields based on the requested data options. If dataOptions is omitted or no reveal option is enabled, workEmailReveal is applied by default. Credit charges per returned lead: - workEmailReveal: 1 credit - fullContactAndCompany: 4 credits. This includes workEmailReveal. - mobilePhoneReveal: 8 credits operationId: searchPeople parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - searchParams properties: searchParams: type: object required: - page - perPage properties: name: type: string description: Full name of the people for exact match or fuzzy search example: "John Smith" locations: type: array items: type: string description: List of countries to include default: [] example: ["United States", "Germany"] excludeLocations: type: array items: type: string description: Countries to exclude from results default: [] cities: type: array items: type: string description: List of specific cities default: [] example: ["San Francisco", "Berlin"] excludeCity: type: array items: type: string description: Cities to exclude default: [] states: type: array items: type: string description: List of specific states or provinces default: [] example: ["California", "Bavaria"] excludeStates: type: array items: type: string description: States to exclude default: [] titles: type: array items: type: string description: Job titles to include default: [] example: ["Software Engineer", "Product Manager"] excludeTitles: type: array items: type: string description: Job titles to exclude default: [] industries: type: array items: type: string description: Industry categories to include default: [] example: ["Fintech", "Renewable Energy"] excludeIndustries: type: array items: type: string description: Industry categories to exclude default: [] technologies: type: array items: type: string description: Technologies/tools the people is associated with default: [] example: ["TypeScript", "AWS", "React"] companyDomains: type: array items: type: string description: Company domain names to include default: [] example: ["google.com", "microsoft.com"] linkedinUrl: type: array items: type: string description: LinkedIn profile URLs default: [] excludeDomain: type: array items: type: string description: Company domains to exclude default: [] employeeCount: type: array items: type: string description: Company size ranges default: [] example: ["1,10", "50,100"] annualRevenue: type: array items: type: string description: Filter by company's estimated annual revenue (in USD) default: [] totalFunding: type: array items: type: string description: Total company funding received (in USD) default: [] keywords: type: array items: type: string description: Relevant keywords default: [] example: ["blockchain", "AI"] excludeKeywords: type: array items: type: string description: Keywords to exclude default: [] intents: type: array items: type: string description: Buyer intent categories default: [] intentTopics: type: array items: type: string description: Subtopics within an intent category default: [] intentScores: type: array items: type: string description: Intent level (high, medium, low) default: [] example: ["high", "medium"] matchMode: type: string description: Controls how filters are applied (all or any) default: "all" enum: [all, any] example: "all" page: type: integer description: Page number for pagination example: 1 perPage: type: integer description: Number of results per page (1-100) minimum: 1 maximum: 100 example: 25 dataOptions: type: object description: Controls which people data is returned and how many credits are charged per returned lead. Multiple options can be true. If omitted or no data option is true, workEmailReveal defaults to true. properties: workEmailReveal: type: boolean description: Reveals work email. Costs 1 credit per returned lead. default: true example: true fullContactAndCompany: type: boolean description: Returns full contact and company data except mobile phone numbers. Costs 4 credits per returned lead and includes workEmailReveal. default: false example: false mobilePhoneReveal: type: boolean description: Reveals mobile phone numbers. Costs 8 credits per returned lead and returns only leads with phone data. default: false example: false example: searchParams: name: "" locations: [] cities: [] states: [] titles: [] industries: [] technologies: [] companyDomains: [] keywords: [] matchMode: "all" page: 1 perPage: 25 dataOptions: workEmailReveal: true fullContactAndCompany: false mobilePhoneReveal: false responses: "200": description: Successfully retrieved people search results. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "People data fetched successfully" data: type: object properties: data: type: array items: type: object description: | Lead fields vary by dataOptions: - workEmailReveal only, or omitted dataOptions: id, name, first_name, last_name, email, title, location, country, state, city, company, industry, company_location, profile_pic, linkedin_url. - mobilePhoneReveal only: id, name, first_name, last_name, masked email, email_status, phone_numbers, title, location, country, state, city, company, industry, company_location, profile_pic, linkedin_url. - fullContactAndCompany: all available contact and company fields except mobile phone fields unless mobilePhoneReveal is also true. additionalProperties: true properties: id: type: string example: "68f932bdb26348d792d36587" name: type: string example: "Cheryl Govender" first_name: type: string example: "Cheryl" last_name: type: string example: "Govender" email: type: string example: "cgovender@siu.org.za" description: Revealed for workEmailReveal/fullContactAndCompany; masked when only mobilePhoneReveal is true. email_status: type: string example: "verified" description: Returned with mobilePhoneReveal or when available in full contact data. phone_numbers: description: Returned only when mobilePhoneReveal is true. example: [{ sanitized_number: "+15551234567", raw_number: "+1 555 123 4567" }] title: type: string example: "Forensic Investigator" location: type: string example: "Washington, District Of Columbia, United States" country: type: string example: "United States" state: type: string example: "District Of Columbia" city: type: string example: "Washington" company: type: string example: "Special Investigating Unit" industry: type: string example: "Government Administration" company_location: type: string example: "Pretoria, South Africa" profile_pic: type: string example: "https://example.com/profile.jpg" linkedin_url: type: string example: "linkedin.com/in/cheryl-govender-88390646" company_id: type: string example: "siu.org.za" totalRecords: type: integer example: 63668231 currentPage: type: integer example: 0 credits: type: number example: 25 dataOptions: type: object properties: workEmailReveal: type: boolean example: true fullContactAndCompany: type: boolean example: false mobilePhoneReveal: type: boolean example: false perPage: type: integer example: 25 examples: noneSelectedDefaultsToWorkEmailReveal: summary: No data option selected / workEmailReveal response value: status: success success: true message: People data fetched successfully data: data: - id: "68f932bdb26348d792d36587" name: "Cheryl Govender" first_name: "Cheryl" last_name: "Govender" email: "cgovender@siu.org.za" title: "Forensic Investigator" location: "Washington, District Of Columbia, United States" country: "United States" state: "District Of Columbia" city: "Washington" company: "Special Investigating Unit" industry: "Government Administration" company_location: "Pretoria, South Africa" profile_pic: "https://example.com/profile.jpg" linkedin_url: "linkedin.com/in/cheryl-govender-88390646" totalRecords: 63668231 currentPage: 1 credits: 25 dataOptions: workEmailReveal: true fullContactAndCompany: false mobilePhoneReveal: false perPage: 25 mobilePhoneReveal: summary: Mobile phone reveal response value: status: success success: true message: People data fetched successfully data: data: - id: "68f932bdb26348d792d36587" name: "Cheryl Govender" first_name: "Cheryl" last_name: "Govender" email: "c****@s****.za" email_status: "verified" phone_numbers: - sanitized_number: "+15551234567" raw_number: "+1 555 123 4567" title: "Forensic Investigator" location: "Washington, District Of Columbia, United States" country: "United States" state: "District Of Columbia" city: "Washington" company: "Special Investigating Unit" industry: "Government Administration" company_location: "Pretoria, South Africa" profile_pic: "https://example.com/profile.jpg" linkedin_url: "linkedin.com/in/cheryl-govender-88390646" totalRecords: 63668231 currentPage: 1 credits: 200 dataOptions: workEmailReveal: false fullContactAndCompany: false mobilePhoneReveal: true perPage: 25 fullContactAndCompany: summary: Full contact and company response value: status: success success: true message: People data fetched successfully data: data: - id: "68f932bdb26348d792d36587" name: "Cheryl Govender" first_name: "Cheryl" last_name: "Govender" email: "cgovender@siu.org.za" email_status: "verified" title: "Forensic Investigator" seniority: "manager" location: "Washington, District Of Columbia, United States" country: "United States" state: "District Of Columbia" city: "Washington" company: "Special Investigating Unit" companyName: "Special Investigating Unit" domain: "siu.org.za" industry: "Government Administration" company_location: "Pretoria, South Africa" employee_count: 1200 linkedin_url: "linkedin.com/in/cheryl-govender-88390646" totalRecords: 63668231 currentPage: 1 credits: 100 dataOptions: workEmailReveal: true fullContactAndCompany: true mobilePhoneReveal: false perPage: 25 fullContactCompanyAndMobilePhone: summary: Full contact and company with mobile phone response value: status: success success: true message: People data fetched successfully data: data: - id: "68f932bdb26348d792d36587" name: "Cheryl Govender" first_name: "Cheryl" last_name: "Govender" email: "cgovender@siu.org.za" email_status: "verified" phone_numbers: - sanitized_number: "+15551234567" raw_number: "+1 555 123 4567" title: "Forensic Investigator" seniority: "manager" location: "Washington, District Of Columbia, United States" country: "United States" state: "District Of Columbia" city: "Washington" company: "Special Investigating Unit" companyName: "Special Investigating Unit" domain: "siu.org.za" industry: "Government Administration" company_location: "Pretoria, South Africa" employee_count: 1200 linkedin_url: "linkedin.com/in/cheryl-govender-88390646" totalRecords: 63668231 currentPage: 1 credits: 300 dataOptions: workEmailReveal: true fullContactAndCompany: true mobilePhoneReveal: true perPage: 25 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/company/find: post: tags: [Contacts API] summary: Company Search description: | This endpoint searches for organizations and returns fields based on the requested data option. Exactly one company data option is required. Credit charges per returned company: - basic: 1 credit. Returns full_contact_company_enrichment, id, name, company, companyName, domain, linkedin_url, industry, raw_address, country, state, city, and employee_count. - full: 4 credits. Returns all company fields. operationId: searchCompany parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: - searchParams - dataOptions properties: searchParams: type: object properties: locations: type: array items: type: string description: List of countries or regions default: [] companyKeywords: type: array items: type: string description: Keywords for company search default: [] domainNames: type: array items: type: string description: Company domain names to filter by default: [] technologies: type: array items: type: string description: Technologies used by the company default: [] industryNames: type: array items: type: string description: Industry names to filter by default: [] annualRevenue: type: array items: type: number description: Annual revenue range default: [] linkedinUrl: type: array items: type: string description: Company LinkedIn profile URLs default: [] employees: type: array items: type: string description: Employee count range default: ["", ""] orgName: type: string description: Company name for search default: "" startFrom: type: integer minimum: 1 default: 1 description: Page number for pagination perPage: type: integer minimum: 1 maximum: 100 default: 25 description: Number of results per page dataOptions: type: object description: Select exactly one company data option. Set either basic or full to true, not both. properties: basic: type: boolean description: Returns the basic company field set. Costs 1 credit per returned company. default: true example: true full: type: boolean description: Returns all company fields. Costs 4 credits per returned company. default: false example: false example: searchParams: locations: [] companyKeywords: [] domainNames: [] technologies: [] industryNames: [] annualRevenue: [] employees: ["", ""] orgName: "" startFrom: 1 perPage: 25 dataOptions: basic: true full: false responses: "200": description: Successfully retrieved company search results. content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Company data fetched successfully" data: type: object properties: data: type: array items: type: object description: | Company fields vary by dataOptions: - basic: full_contact_company_enrichment, id, name, company, companyName, domain, linkedin_url, industry, raw_address, country, state, city, employee_count. - full: all available company fields. additionalProperties: true properties: full_contact_company_enrichment: type: boolean example: true id: type: string example: "68f9974bb26348d79236cf21" name: type: string example: "Ruby Tuesday" company: type: string example: "Ruby Tuesday" companyName: type: string example: "Ruby Tuesday" domain: type: string example: "rubytuesday.com" linkedin_url: type: string example: "linkedin.com/company/ruby-tuesday" industry: type: string example: "Restaurants" raw_address: type: string example: "216 E Church Ave, Maryville, TN, United States" country: type: string example: "United States" state: type: string example: "Tennessee" city: type: string example: "Maryville" employee_count: type: integer example: 5000 totalRecords: type: integer example: 120440607 currentPage: type: integer example: 1 credits: type: number example: 25 dataOptions: type: object properties: basic: type: boolean example: true full: type: boolean example: false perPage: type: integer example: 25 examples: basic: summary: Basic company response value: status: success success: true message: Company data fetched successfully data: data: - full_contact_company_enrichment: true id: "68f9974bb26348d79236cf21" name: "Ruby Tuesday" company: "Ruby Tuesday" companyName: "Ruby Tuesday" domain: "rubytuesday.com" linkedin_url: "linkedin.com/company/ruby-tuesday" industry: "Restaurants" raw_address: "216 E Church Ave, Maryville, TN, United States" country: "United States" state: "Tennessee" city: "Maryville" employee_count: 5000 totalRecords: 120440607 currentPage: 1 credits: 25 dataOptions: basic: true full: false perPage: 25 full: summary: Full company response value: status: success success: true message: Company data fetched successfully data: data: - full_contact_company_enrichment: true id: "68f9974bb26348d79236cf21" name: "Ruby Tuesday" company: "Ruby Tuesday" companyName: "Ruby Tuesday" domain: "rubytuesday.com" linkedin_url: "linkedin.com/company/ruby-tuesday" industry: "Restaurants" raw_address: "216 E Church Ave, Maryville, TN, United States" country: "United States" state: "Tennessee" city: "Maryville" employee_count: 5000 annual_revenue: 1200000000 technologies: ["Salesforce", "Google Analytics"] founded_year: 1972 totalRecords: 120440607 currentPage: 1 credits: 100 dataOptions: basic: false full: true perPage: 25 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/people_verification/verify/batch: post: tags: [Contacts API] summary: People Verification description: Submit a batch of email addresses for people verification. operationId: verifyPeopleBatch parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: [emails] properties: emails: description: Email addresses to validate. Maximum 10,000 emails per batch. oneOf: - type: array minItems: 1 maxItems: 10000 uniqueItems: true items: type: string format: email - type: string example: ["first@example.com", "second@example.com"] name: type: string maxLength: 50 example: "August verification batch" responses: "201": description: Successfully created a people verification batch. content: application/json: schema: type: object properties: status: type: string example: success success: type: boolean example: true message: type: string example: People verification batch created successfully data: type: object properties: batchId: type: string example: BATCH-ABC123 status: type: string example: processing creditsDeducted: type: number example: 1.5 validatedEmails: type: number example: 2 savedValidatedLeads: type: number example: 2 remainingCreditBalance: type: number example: 98.5 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "402": description: Insufficient credits or subscription paused. "500": $ref: "#/components/responses/InternalError" get: tags: [Contacts API] summary: List People Verification Batches description: List all people verification batches saved for the authenticated workspace. operationId: listPeopleVerificationBatches parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: page in: query schema: type: integer minimum: 1 default: 1 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 responses: "200": description: Successfully fetched people verification batches. content: application/json: schema: type: object properties: status: type: string example: success success: type: boolean example: true message: type: string example: People verification batches fetched successfully data: type: object properties: page: type: integer example: 1 limit: type: integer example: 20 totalItems: type: integer example: 1 totalPages: type: integer example: 1 items: type: array items: type: object properties: batch_id: type: string example: BATCH-ABC123 status: type: string example: completed attempts: type: number example: 2 source: type: string example: successai created_at: type: string format: date-time "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v2/people_verification/verify/batch/download: get: tags: [Contacts API] summary: Download People Verification Report description: Download a CSV report for all people verification batches or a single batch when batchId is provided. operationId: downloadPeopleVerificationBatchReport parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" - name: batchId in: query required: false schema: type: string example: BATCH-ABC123 responses: "200": description: CSV report. content: text/csv: schema: type: string format: binary "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/people_enrichment/peopleEnrichment: post: tags: [Contacts API] summary: People Enrichment description: | Retrieve enriched data for people using email addresses or LinkedIn profile URLs. Credits are charged per eligible returned record: work email reveal costs 1 credit, full contact and company reveal costs 4 credits, and mobile phone reveal costs 8 credits. operationId: enrichPeople parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string example: "acf9b9d9fe52ecf8b0ec8ac88" requestBody: required: true content: application/json: schema: type: object required: [leadIds, type, dataOptions] properties: leadIds: type: array minItems: 1 maxItems: 1000 items: { type: string } description: Email addresses or LinkedIn profile URLs to enrich. example: ["john.doe@company.com"] type: type: string enum: [email, linkedin] description: Identifies whether leadIds contains email addresses or LinkedIn profile URLs. example: email dataOptions: type: object description: Select which enrichment data to reveal. At least one option must be true. properties: workEmailReveal: type: boolean default: true description: Reveal work email data. Costs 1 credit per eligible returned record. fullContactAndCompany: type: boolean default: false description: Reveal full contact and company data. Costs 4 credits per eligible returned record. mobilePhoneReveal: type: boolean default: false description: Reveal mobile phone data. Costs 8 credits per eligible returned record. example: workEmailReveal: true fullContactAndCompany: false mobilePhoneReveal: false responses: "200": description: Successfully retrieved enriched people data. "400": { $ref: "#/components/responses/BadRequest" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } "500": { $ref: "#/components/responses/InternalError" } /v2/domain/search: get: tags: [Domain] summary: Search available domains description: "Search for available non-premium domains. Pricing: domain $13/year plus $1.50 setup, mailbox $3.50/year plus $1 setup." operationId: searchDomainSubscriptionDomains parameters: - name: x-api-key in: header required: true schema: { type: string } - name: keyword in: query required: true schema: { type: string, example: "acme" } - name: provider in: query schema: { type: string, enum: [google, microsoft] } - name: tlds in: query description: "Comma-separated TLDs. Allowed values: .com, .co, .net, .org, .shop, .info." schema: type: string example: ".com,.co" - name: skip in: query schema: { type: integer, minimum: 0, example: 0 } description: Number of records to skip. - name: limit in: query schema: { type: integer, minimum: 1, maximum: 25, example: 10 } description: Number of records to return. Maximum 25. responses: "200": description: Domains fetched successfully content: application/json: example: success: true message: Domains fetched successfully data: - domain: "acme.com" "400": { $ref: "#/components/responses/BadRequest" } "401": { $ref: "#/components/responses/Unauthorized" } "429": { $ref: "#/components/responses/RateLimitExceeded" } /v2/domain/mailboxes: get: tags: [Domain] summary: List mailboxes under a domain description: | Return the mailboxes associated with a domain order item by domain id or domain name. Domain `status` values: `pending`, `new_order`, `active`, `suspended`, `renewal_required`, `expired`, `cancelled`. Mailbox `status` values: `pending`, `new_order`, `purchased`, `setup_complete`, `need_to_cancel`, `ready`, `cancelled`, `failed`, `expired`. operationId: getDomainSubscriptionMailboxes parameters: - name: x-api-key in: header required: true schema: { type: string } - name: domainId in: query required: false schema: { type: string, example: "66f000000000000000000002" } - name: domain in: query required: false schema: { type: string, example: "acme.com" } description: Use either domainId or domain. responses: "200": description: Domain mailboxes fetched successfully content: application/json: example: success: true data: domainId: "66f000000000000000000002" domain: "acme.com" status: "pending" fallbackDomains: [] mailboxes: - firstName: "Jane" lastName: "Doe" email: "jane@acme.com" status: "pending" isAdmin: false "400": { $ref: "#/components/responses/BadRequest" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/RateLimitExceeded" } /v2/domain/mailboxes/cancel: post: tags: [Domain] summary: Cancel mailboxes under a domain order description: | Cancel one or more mailboxes from a single owned domain order. Pass either mailbox table ids in `mailboxIds` or mailbox emails in `mailboxes`. All selected mailboxes must belong to the same order. If an admin mailbox is selected, all mailboxes under that admin mailbox's domain are cancelled. If only non-admin mailboxes are selected, only those selected mailboxes are cancelled. Cancelled mailbox `status` values: `pending`, `new_order`, `purchased`, `setup_complete`, `need_to_cancel`, `ready`, `cancelled`, `failed`, `expired`. operationId: cancelDomainSubscriptionMailboxes parameters: - name: x-api-key in: header required: true schema: { type: string } requestBody: required: true content: application/json: schema: type: object description: Exactly one of mailboxIds or mailboxes is required. oneOf: - required: [mailboxIds] - required: [mailboxes] properties: mailboxIds: type: array description: Mailbox table _ids to cancel. Use either mailboxIds or mailboxes. minItems: 1 items: type: string example: "66f000000000000000000003" mailboxes: type: array description: Mailbox email addresses to cancel. Use either mailboxIds or mailboxes. minItems: 1 items: type: string format: email example: "jane@acme.com" examples: byMultipleMailboxIds: summary: Cancel multiple mailbox table ids value: mailboxIds: - "66f000000000000000000003" - "66f000000000000000000004" byEmail: summary: Cancel by mailbox emails value: mailboxes: - "jane@acme.com" - "john@acme.com" responses: "200": description: Mailboxes cancelled successfully content: application/json: example: success: true message: Mailboxes cancelled successfully data: orderId: "66f000000000000000000001" cancelledCount: 2 remainingMailboxes: 3 adminMailboxTriggered: false cancelledMailboxes: - id: "66f000000000000000000003" domainId: "66f000000000000000000002" firstName: "Jane" lastName: "Doe" email: "jane@acme.com" status: "cancelled" isAdmin: false "400": { $ref: "#/components/responses/BadRequest" } "401": { $ref: "#/components/responses/Unauthorized" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/RateLimitExceeded" } /v2/domain/orders: get: tags: [Domain] summary: List domain subscription orders description: | List domain and mailbox orders for the API key workspace. Order `status` values: `pending`, `new_order`, `purchased`, `setup_complete`, `ready`, `need_to_cancel`, `cancelled`, `failed`. Order `paymentStatus` values: `paid`, `pending`, `failed`. Domain `status` values: `pending`, `new_order`, `active`, `suspended`, `renewal_required`, `expired`, `cancelled`. Mailbox `status` values: `pending`, `new_order`, `purchased`, `setup_complete`, `need_to_cancel`, `ready`, `cancelled`, `failed`, `expired`. operationId: listDomainSubscriptionOrders parameters: - name: x-api-key in: header required: true schema: { type: string } - name: skip in: query schema: { type: integer, minimum: 0, example: 0 } description: Number of records to skip. - name: limit in: query schema: { type: integer, minimum: 1, maximum: 25, example: 10 } description: Number of records to return. Maximum 25. - name: search in: query schema: { type: string, example: "acme.com" } responses: "200": description: Orders fetched successfully content: application/json: example: status: true total: 1 data: - orderId: "66f000000000000000000001" userEmail: "owner@example.com" status: "pending" paymentStatus: "pending" invoiceUrl: "https://invoice.stripe.com/i/acct_..." fallbackDomains: [] domains: - domainId: "66f000000000000000000002" domain: "acme.com" status: "pending" fallbackDomains: [] mailboxes: - email: "jane@acme.com" firstName: "Jane" lastName: "Doe" status: "pending" isAdmin: false "400": { $ref: "#/components/responses/BadRequest" } "401": { $ref: "#/components/responses/Unauthorized" } "429": { $ref: "#/components/responses/RateLimitExceeded" } /v2/domain/order/place: post: tags: [Domain] summary: Create a domain and mailbox order description: Create a domain and mailbox order. Domain availability is rechecked before the order and invoice are created. Each domain must include 1 to 5 mailboxes. operationId: placeDomainSubscriptionOrder parameters: - name: x-api-key in: header required: true schema: { type: string } requestBody: required: true content: application/json: schema: type: object required: [type, domains] properties: type: type: string enum: [google, microsoft] example: "google" description: Mailbox provider for the whole order. Must be either google or microsoft. domains: type: array items: type: object required: [domain, contactDetails] properties: domain: { type: string, example: "acme.com" } forwardDomain: { type: string, example: "example.com" } contactDetails: type: array description: Mailboxes to create under this domain. Minimum 1 and maximum 5. minItems: 1 maxItems: 5 items: type: object required: [firstName, lastName, email] properties: firstName: { type: string, example: "Jane" } lastName: { type: string, example: "Doe" } email: type: string format: email example: "jane@acme.com" example: type: "google" domains: - domain: "acme.com" contactDetails: - firstName: "Jane" lastName: "Doe" email: "jane@acme.com" responses: "201": description: Domain subscription invoice created successfully content: application/json: example: success: true message: Domain subscription invoice created successfully data: orderId: "66f000000000000000000001" userEmail: "owner@example.com" invoiceEmail: "owner@example.com" invoiceUrl: "https://invoice.stripe.com/i/acct_..." fallbackDomains: [] domains: - domain: "acme.com" fallbackDomains: [] mailboxes: - firstName: "Jane" lastName: "Doe" email: "jane@acme.com" isAdmin: false pricing: currency: "USD" domain: { quantity: 1, unitAmount: 13, setupAmount: 1.5, total: 13, setupTotal: 1.5 } mailbox: { quantity: 1, unitAmount: 3.5, setupAmount: 1, total: 3.5, setupTotal: 1 } total: 19 "400": { $ref: "#/components/responses/BadRequest" } "401": { $ref: "#/components/responses/Unauthorized" } "409": description: Domain already purchased "429": { $ref: "#/components/responses/RateLimitExceeded" } /v2/whitelabel/register: post: tags: [Whitelabel] x-scalar-ignore: true summary: Register a new user description: Register a new user under a white-labeled partner account operationId: whiteLabelRegister parameters: - name: x-api-key in: header required: true description: Your API key schema: type: string requestBody: required: true content: application/json: schema: type: object required: - partnerAccountId - name - email - password properties: partnerAccountId: type: string example: "6854f2642787818e48489903" name: type: object properties: first: type: string example: "user" last: type: string example: "one" email: type: string format: email example: "expose.user.one@yopmail.com" password: type: string example: "User@123" responses: "200": description: Successfully registered content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Successfully Registered" data: type: object properties: authToken: type: string description: JWT token for authenticated user example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." stripeCustomerId: type: string description: Stripe customer ID example: "cus_SXOtXNlchRnPJo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v2/whitelabel/add-plan: post: tags: [Whitelabel] x-scalar-ignore: true summary: Create a custom plan description: Add a new custom plan for a white-labeled partner operationId: createCustomPlan parameters: - name: x-api-key in: header required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - planName properties: planName: type: string example: "bronzePlan" buyerIntendData: type: boolean advancedFilters: type: boolean abTesting: type: boolean aiFilters: type: boolean mailboxConnection: type: boolean customDomainTracking: type: boolean globalBlocklist: type: boolean emailWarmup: type: boolean multiChannelLinkedinOutreach: type: boolean unibox: type: boolean aiAutoReplies: type: boolean zapierIntegration: type: boolean hubspotIntegration: type: boolean salesforceIntegration: type: boolean pipedriveIntegration: type: boolean webhookIntegration: type: boolean advancedApis: type: boolean activeLeads: type: integer monthlyEmails: type: integer aiWriterCredits: type: integer leadsCredits: type: integer linkedinCredits: type: integer emailAccountsLimit: type: integer bounceCredit: type: integer dealPipeline: type: integer buyerIntendDataTopiscs: type: integer responses: "200": description: Custom plan created successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Custom Plan Created Successfully." data: type: object properties: _id: type: string example: "685649675329319ccd278e99" createdBy: type: string example: "68393952174c182e3c2f3505" planName: type: string example: "bronzePlan" activeLeads: type: integer example: 100 monthlyEmails: type: integer example: 100 aiWriterCredits: type: integer example: 100 leadsCredits: type: integer example: 100 linkedinCredits: type: integer example: 100 emailAccountsLimit: type: integer example: 100 bounceCredit: type: integer example: 100 dealPipeline: type: integer example: 100 buyerIntendDataTopiscs: type: integer example: 1 buyerIntendData: type: boolean example: false advancedFilters: type: boolean abTesting: type: boolean aiFilters: type: boolean mailboxConnection: type: boolean customDomainTracking: type: boolean globalBlocklist: type: boolean emailWarmup: type: boolean multiChannelLinkedinOutreach: type: boolean unibox: type: boolean aiAutoReplies: type: boolean zapierIntegration: type: boolean hubspotIntegration: type: boolean salesforceIntegration: type: boolean pipedriveIntegration: type: boolean webhookIntegration: type: boolean advancedApis: type: boolean createdAt: type: string format: date-time example: "2025-06-21T05:55:51.199Z" updatedAt: type: string format: date-time example: "2025-06-21T05:55:51.199Z" __v: type: integer example: 0 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "500": $ref: "#/components/responses/InternalError" /v2/whitelabel/user/{subUserId}/assign-plan/{planId}: post: tags: [Whitelabel] x-scalar-ignore: true summary: Assign a plan to a user description: Assign a custom plan to a white-labeled sub-user operationId: assignPlan parameters: - name: x-api-key in: header required: true schema: type: string - name: subUserId in: path required: true schema: type: string - name: planId in: path required: true schema: type: string responses: "200": description: Plan assigned successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Plan assigned successfully" data: type: object description: Empty object example: {} "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/whitelabel/get-plan: get: tags: [Whitelabel] x-scalar-ignore: true summary: Get custom plan description: Retrieve the custom plan associated with the authenticated white-label partner operationId: getCustomPlan parameters: - name: x-api-key in: header required: true schema: type: string responses: "200": description: Custom plan fetched successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "Custom Plan Fetch Successfully." data: type: object properties: _id: type: string example: "6854f49864f669668f82aecd" createdBy: type: string example: "6854f2642787818e48489903" planName: type: string example: "bronzePlan" activeLeads: type: integer example: 100 monthlyEmails: type: integer example: 100 aiWriterCredits: type: integer example: 100 leadsCredits: type: integer example: 100 linkedinCredits: type: integer example: 100 emailAccountsLimit: type: integer example: 100 bounceCredit: type: integer example: 100 dealPipeline: type: integer example: 100 buyerIntendDataTopiscs: type: integer example: 100 buyerIntendData: type: boolean example: false advancedFilters: type: boolean abTesting: type: boolean aiFilters: type: boolean mailboxConnection: type: boolean customDomainTracking: type: boolean globalBlocklist: type: boolean emailWarmup: type: boolean multiChannelLinkedinOutreach: type: boolean unibox: type: boolean aiAutoReplies: type: boolean zapierIntegration: type: boolean hubspotIntegration: type: boolean salesforceIntegration: type: boolean pipedriveIntegration: type: boolean webhookIntegration: type: boolean advancedApis: type: boolean createdAt: type: string format: date-time example: "2025-06-20T05:41:44.295Z" updatedAt: type: string format: date-time example: "2025-06-20T05:41:44.295Z" __v: type: integer example: 0 "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /v2/whitelabel/user/{email}: get: tags: [Whitelabel] x-scalar-ignore: true summary: Get user details description: Fetch user details by email address within the current workspace operationId: getUserByEmail parameters: - name: x-api-key in: header required: true schema: type: string - name: email in: path required: true schema: type: string format: email responses: "200": description: User fetched successfully content: application/json: schema: type: object properties: status: type: string example: "success" success: type: boolean example: true message: type: string example: "User fetched successfully" data: type: object properties: name: type: object properties: first: type: string example: "User" last: type: string example: "One" _id: type: string example: "6854f5203c10395bf9b0c445" email: type: string example: "expose.user.one@mail.com" emailVerified: type: boolean example: true searchVerification: type: boolean example: false warmupTag: type: string example: "58113F09" lastLogout: type: string format: date-time example: "2025-06-20T05:44:00.765Z" lastLogin: type: string format: date-time example: "2025-06-20T05:44:00.765Z" assignedPlan: type: string nullable: true example: null isAppSumoRefund: type: boolean example: false twofaEnabled: type: boolean example: false firstLogin: type: boolean example: false isEarlyBirdAccessUser: type: boolean example: false isSummerDealUser: type: boolean example: false isEarlyBirdDealRefund: type: boolean example: false EarlyBirdPlan: type: string nullable: true example: null isTrackedByGoogleAds: type: boolean example: false isPartner: type: boolean example: false partnerAccountId: type: string example: "6854f2642787818e48489903" isTeamMember: type: boolean example: false isDeleted: type: boolean example: false deletedAt: type: string nullable: true example: null createdAt: type: string format: date-time example: "2025-06-20T05:44:00.770Z" updatedAt: type: string format: date-time example: "2025-06-20T05:44:04.979Z" __v: type: integer example: 0 currentWorkspace: type: string example: "6854f5203c10395bf9b0c449" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" # ─── Data License ────────────────────────────────────────────── /v2/datalicense: get: tags: [Data License] x-scalar-ignore: true summary: Data License Overview description: | **Data License Overview** At **Success.ai**, we provide massive people and company datasets, as well as intent, job postings and IP web traffic de-anonymization data through **various licenses**. Whether you need our entire dataset or a custom subset, we can tailor a solution to meet your specific needs. To learn more, speak with one of our **Data Consultants**. **The Value of a Success.ai License** 1. **On-Premise Data Access**: During the license period, you have the right to use the data on your premises in any way, as long as it complies with our **Terms and Conditions**. 2. **Fastest Refresh Rate in the Industry**: We refresh our people and company data **continuously**, ensuring you always have the most up-to-date information. Updated files are delivered within a **maximum range of 4 to 8 weeks**, so your data stays current and actionable. 3. **Unmatched Data Coverage**: Our dataset offers the largest **global coverage** with a focus on **accuracy, depth, and relevance**. 4. **Dedicated Customer Success Team**: Our Data-feed and API customers receive dedicated support, including **Email support** on weekdays from **9:00 AM – 5:00 PM Eastern Time**, excluding holidays. 5. **Unlimited Access at Scale**: Unlike search and matching APIs that become costly at scale, **Success.ai** provides **unlimited access** to high-quality data at a fraction of the price, making it ideal for **large-scale projects**. 6. **Flexible Licensing Options**: We allow you to **customize the data** to ensure you only receive—and pay for—the profiles that matter most to your business. **Tailored Delivery Solutions** We offer a variety of delivery options to suit your needs, including **Cloud Platforms**: Deliveries via **S3, Snowflake**, flat files and more. **Why Choose Success.ai?** ✅ **Fastest Refresh Rate**: Stay ahead with data updated **continuously**. 🌍 **Global Reach**: Access to **millions of verified profiles worldwide**. 💰 **Cost-Effective**: Unlimited access at the market's most **competitive price**. 🔍 **Tailored Solutions**: Custom datasets to fit your **unique requirements**. 💡 **Exceptional Support**: Dedicated **customer success team** to ensure your success. **Overview** This documentation provides comprehensive information about Success.ai's B2B contact and company datasets available on data.success.ai as well as Snowflake Marketplace. It outlines our data sources, collection methodology, data processing techniques, quality assurance procedures, update frequency, and technical specifications to help users understand, evaluate, and effectively utilize our datasets. operationId: getDataLicenseOverview responses: "200": description: Success - Data license information content: application/json: schema: type: object properties: message: type: string description: Status message example: "Data license information retrieved successfully" licenseInfo: type: object description: License information "401": $ref: "#/components/responses/Unauthorized" "429": description: Rate limit exceeded /v2/datasources: get: tags: [Data License] x-scalar-ignore: true summary: Data Sources description: | **Data Sources** **Primary Sources** Our dataset is compiled from multiple sources to ensure comprehensive coverage and accuracy: - Publicly Available Business Information - Professional networking platforms, like LinkedIn - Company websites and directories - Business social media profiles - Public business registries and databases **Web Data Collection** - Structured data from public web sources - Manifestly public data as defined under GDPR Article 9.2(e) **Third-Party Data Providers** - Partnerships with reputable data aggregators - Business information services **User-Contributed Data** - Opt-in business contact information - Professional information shared within our platform responses: 200: description: Success - Data sources information content: application/json: schema: type: object properties: message: type: string description: Status message example: "Data sources information retrieved successfully" sourcesInfo: type: object description: Sources information 401: description: Unauthorized - Invalid API key 429: description: Rate limit exceeded /v2/dataprocessing: get: tags: [Data License] x-scalar-ignore: true summary: Data Processing Methodology description: | **Data Processing Methodology** **Data Extraction and Standardization** - Automated tools for public web data collection - API-based extraction from partner platforms - Bulk imports from data partnerships **Standardization Procedures** - Field normalization across sources - Country-specific formatting standardization - Company and industry classification mapping - Job title normalization and hierarchy classification **Data Enrichment** - Entity Resolution and Matching - Identify and merge duplicate records - Cross-validation across sources - Probabilistic and deterministic matching - Data Augmentation - Bespoke algorithms for enrichment - Company hierarchy mapping - Contact role and seniority classification - Technology stack enrichment responses: 200: description: Success - Data processing methodology information content: application/json: schema: type: object properties: message: type: string example: "Data processing methodology information retrieved successfully" dataProcessing: type: object description: Data processing methodology details "401": $ref: "#/components/responses/Unauthorized" "429": description: Rate limit exceeded /v2/dataupdates: get: tags: [Data License] x-scalar-ignore: true summary: Data Updates and Maintenance description: | **Data Updates and Maintenance** **Refresh Frequency** - Continuous, Daily refresh - Updates every 4-8 weeks **Update Methodology** - Continuous monitoring - Delta detection - Event-triggered updates **Historical Versioning** - Point-in-time recovery - Change history tracking - Audit trails operationId: getDataUpdates responses: "200": description: Success - Data updates and maintenance information content: application/json: schema: type: object properties: message: type: string description: Status message example: "Data updates and maintenance information retrieved successfully" updatesInfo: type: object description: Updates and maintenance information "401": $ref: "#/components/responses/Unauthorized" "429": description: Rate limit exceeded /v2/datasecurity: get: tags: [Data License] x-scalar-ignore: true summary: Data Security and Compliance description: | **Data Security and Compliance** **Privacy Compliance** * **GDPR Compliance** * Processing based on legitimate interests (GDPR Article 6.1(f)) * Processing of manifestly public data (GDPR Article 9.2(e)) * Data subject rights honored (access, erasure, rectification, portability) * **CCPA Compliance** * Consumer rights honored * Disclosure of collection practices * Opt-out mechanisms **Data Security Measures** * **Storage Security** * Data encryption at rest and in transit * Secure cloud platforms (Azure) * Compliance with industry-leading security standards * **Access Controls** * IP restriction for server access * Web application firewalls * Secure authentication practices **Technical Specifications** **Data Schema** | **Field Category** | **Example Fields** | **Description** | |-------------------|-------------------|-----------------| | Identity | Full Name, Email, Phone | Contact identification information | | Professional | Job Title, Department, Seniority | Professional role information | | Company | Company Name, Industry, Size | Organizational details | | Location | Country, City, Region | Geographic information | | Social | LinkedIn URL, Twitter Handle | Professional social profiles | | Technology | Tech Stack, Tools Used | Technology usage information | | Custom | Custom Fields as Required | Customer-specific data points | **File Formats** * CSV * JSON * Parquet * Other formats available upon request **Delivery Methods** * Snowflake * Amazon S3 * API Access * Other cloud platforms as needed **Data License Information** **License Terms** * **License Type**: Custom licenses; one-time purchase, monthly/quarterly/yearly subscription * **Usage Rights**: On-premise data usage subject to Terms and Conditions * **Customization**: Tailored subsets available based on customer requirements **Support and Services** * **Customer Support**: Email support available weekdays (9:00 AM – 5:00 PM Eastern Time) * **Dedicated Success Team**: For Data-feed and API customers * **Custom Delivery Options**: Available upon request **Contact Information** For questions about our dataset, methodology, or licensing: * **General Support**: support@success.ai * **General product demo**: [Book A Demo](https://calendly.com/viktor-success/dataset-data-needs-discussion-success-ai?month=2025-04) * **Enterprise datasets or high-limit API access**: [Schedule a free consultation](https://calendly.com/viktor-success/dataset-data-needs-discussion-success-ai?month=2025-04) * **Website**: www.success.ai **Additional Resources** * Success.ai [Privacy Policy](https://www.success.ai/privacy-policy) * Success.ai [Terms & Conditions](https://www.success.ai/terms-and-condition) operationId: getDataSecurity responses: "200": description: Success - Data security and compliance information content: application/json: schema: type: object properties: message: type: string example: "Data security and compliance information retrieved successfully" dataSecurity: type: object description: Data security and compliance details "401": $ref: "#/components/responses/Unauthorized" "429": description: Rate limit exceeded # ─── Lists ───────────────────────────────────────────────────── /v2/list/create/people: post: tags: [Lists] summary: Create a people list description: Create a new list to store individual contacts (people). Each workspace can have multiple people lists. operationId: createPeopleList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Name of the list (3–150 characters, must be unique in workspace) example: "Q1 2024 Prospects" responses: "200": description: People list created successfully content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "People list created successfully" } data: type: object properties: listId: { type: string, example: "696a18d4a0ed66cb0bf78b26" } name: { type: string, example: "Q1 2024 Prospects" } listType: { type: string, example: "people" } createdAt: type: string format: date-time example: "2026-01-16T10:54:12.624Z" "400": description: Bad request – validation error or duplicate list name content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List name already exists" "401": { $ref: "#/components/responses/Unauthorized" } "500": { $ref: "#/components/responses/InternalError" } /v2/list/create/company: post: tags: [Lists] summary: Create a company list description: Create a new list to store company information. Each workspace can have multiple company lists. operationId: createCompanyList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Name of the list (3–150 characters, must be unique in workspace) example: "Tech Companies 2024" responses: "200": description: Company list created successfully content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Company list created successfully" } data: type: object properties: listId: { type: string, example: "696a18e8a0ed66cb0bf78b2e" } name: { type: string, example: "Tech Companies 2024" } listType: { type: string, example: "company" } createdAt: type: string format: date-time example: "2026-01-16T10:54:32.801Z" "400": description: Bad request – validation error or duplicate list name content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List name already exists" "401": { $ref: "#/components/responses/Unauthorized" } "500": { $ref: "#/components/responses/InternalError" } /v2/list/delete/people: post: tags: [Lists] summary: Delete a people list description: | Delete a people list and all its contacts. This action cannot be undone. Master lists (default lists created for each workspace) cannot be deleted. operationId: deletePeopleList parameters: - name: x-api-key in: header required: true description: Your API key schema: type: string requestBody: required: true content: application/json: schema: type: object required: - listId properties: listId: type: string description: ID of the people list to delete example: "507f1f77bcf86cd799439011" responses: "200": description: People list deleted successfully content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "People list deleted successfully" } data: type: object properties: deletedCount: type: integer description: Number of contacts deleted with the list example: 0 "400": description: Bad request – validation error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid listId" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: List not found or cannot be deleted content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Master list cannot be deleted" "500": { $ref: "#/components/responses/InternalError" } /v2/list/delete/company: post: tags: [Lists] summary: Delete a company list description: | Delete a company list and all its entries. This action cannot be undone. Master lists (default lists created for each workspace) cannot be deleted. operationId: deleteCompanyList parameters: - name: x-api-key in: header required: true description: Your API key schema: type: string requestBody: required: true content: application/json: schema: type: object required: - listId properties: listId: type: string description: ID of the company list to delete example: "507f1f77bcf86cd799439011" responses: "200": description: Company list deleted successfully content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Company list deleted successfully" } data: type: object properties: deletedCount: type: integer description: Number of company records deleted with the list example: 0 "400": description: Bad request – validation error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid listId" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: List not found or cannot be deleted content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Master list cannot be deleted" "500": { $ref: "#/components/responses/InternalError" } /v2/list/get: get: tags: [Lists] summary: Get list details description: Retrieve detailed information about a specific list including its type, contact count, and timestamps. operationId: getListDetails parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string - name: listId in: query required: true description: The unique identifier of the list. schema: type: string example: "696a18e8a0ed66cb0bf78b2e" responses: "200": description: Successfully retrieved list details. content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "List details fetched successfully" } data: type: object properties: listId: { type: string, example: "696a18e8a0ed66cb0bf78b2e" } name: { type: string, example: "Tech Companies 2024" } listType: type: string enum: [people, company] example: "company" count: { type: integer, example: 0 } createdAt: type: string format: date-time example: "2026-01-16T10:54:32.801Z" updatedAt: type: string format: date-time example: "2026-01-16T10:54:32.801Z" isMasterList: { type: boolean, example: false } "400": description: Bad Request - Missing or invalid listId parameter. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid list ID" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: Not Found - List not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/all: get: tags: [Lists] summary: List all lists description: | Retrieve a paginated list of all lists in your workspace. You can filter by list type (people or companies) and search by name. operationId: getAllLists parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string - name: alignment in: query required: false description: Filter by list type schema: type: string enum: [people, companies] example: "people" - name: search in: query required: false description: Search lists by name schema: type: string example: "Q1 2024" - name: skip in: query required: false description: Number of lists to skip (for pagination) schema: type: integer default: 0 example: 0 - name: limit in: query required: false description: Maximum number of lists to return (max 50) schema: type: integer default: 50 maximum: 50 example: 50 responses: "200": description: Successfully retrieved all lists. content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "All lists fetched successfully" } data: type: object properties: lists: type: array description: Array of lists in the workspace. items: type: object properties: listId: { type: string, example: "673271d82448246e6de67307" } name: { type: string, example: "People_List" } listType: type: string enum: [people, company] example: "people" count: { type: integer, example: 5 } createdAt: type: string format: date-time example: "2024-11-11T21:06:32.061Z" updatedAt: type: string format: date-time example: "2025-04-16T09:55:33.294Z" pagination: type: object description: Pagination metadata. properties: total: { type: integer, example: 5 } limit: { type: integer, example: 50 } skip: { type: integer, example: 0 } page: { type: integer, example: 1 } totalPages: { type: integer, example: 1 } hasMore: { type: boolean, example: false } "400": description: Bad Request - Validation error or invalid parameters. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid parameters" "401": { $ref: "#/components/responses/Unauthorized" } "500": { $ref: "#/components/responses/InternalError" } /v2/list/leads: get: tags: [Lists] summary: Get leads from a people list description: | Retrieve contacts from a people list with pagination support. You can search and filter contacts within the list. This endpoint returns detailed contact information including emails, names, titles, companies, and other profile data. **Features:** - Pagination with customizable offset and limit - Search across email, name, company, and title fields operationId: getLeadsFromList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string - name: listId in: query required: true description: The unique identifier of the people list. schema: type: string example: "68495d8e589099bd50f501ad" - name: offset in: query required: false description: Number of contacts to skip (for pagination). schema: type: integer default: 0 example: 0 - name: limit in: query required: false description: Maximum number of contacts to return (max 1000). schema: type: integer default: 50 maximum: 1000 example: 50 - name: search in: query required: false description: Search term to filter contacts by email, name, company, or title. schema: type: string example: "manager" responses: "200": description: Successfully retrieved contacts from the list. content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Leads fetched from list successfully" } data: type: object properties: contacts: type: array description: Array of contacts from the list. items: type: object properties: _id: { type: string, example: "695762cdc8baa98925f6ca46" } id: { type: string, example: "68f93815b26348d792357772" } name: { type: string, example: "Sarah Johnson" } first_name: { type: string, example: "Sarah" } last_name: { type: string, example: "Johnson" } email: type: string format: email example: "sarah.johnson@techcorp.com" email_status: { type: string, example: "Valid (Esp)" } validation_status: type: string enum: [VALIDATING, DELIVERABLE, UNDELIVERABLE, RISKY, UNKNOWN] example: "DELIVERABLE" phone_numbers: { type: string, example: "+1-555-123-4567" } title: { type: string, example: "Senior Product Manager" } company: { type: string, example: "TechCorp Solutions" } industry: { type: string, example: "Technology" } website: { type: string, example: "techcorp.com" } location: { type: string, example: "San Francisco, CA" } country: { type: string, example: "United States" } state: { type: string, example: "California" } city: { type: string, example: "San Francisco" } company_location: { type: string, example: "San Francisco" } linkedin_url: { type: string, example: "linkedin.com/in/sarah-johnson-123" } profile_pic: { type: string, example: "https://example.com/photo.jpg" } recordType: { type: string, example: "person" } list: { type: string, example: "68495d8e589099bd50f501ad" } workspaceId: { type: string, example: "67502c0f567a5a46df3e7ec9" } batchId: { type: string, example: "695762c8e0d7e5cced42064e" } csvId: { type: string, example: "695762c8e0d7e5cced42064e" } queryHash: { type: string, example: "c667f5cb21befc2a0793fb020fc96059" } deleted: { type: boolean, example: false } createdAt: type: string format: date-time example: "2026-01-02T06:16:45.373Z" updatedAt: type: string format: date-time example: "2026-01-02T06:16:45.373Z" __v: { type: integer, example: 0 } pagination: type: object description: Pagination metadata. properties: total: { type: integer, example: 2099 } offset: { type: integer, example: 0 } limit: { type: integer, example: 1 } hasMore: { type: boolean, example: true } listType: type: string enum: [people, company] example: "people" "400": description: Bad Request - Missing or invalid parameters. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid list ID" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: Not Found - List not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/companies: get: tags: [Lists] summary: Get companies from a company list description: | Retrieve company records from a company list with pagination support. You can search and filter companies within the list. This endpoint returns detailed company information including names, domains, industries, locations, and other company data. **Features:** - Pagination with customizable offset and limit - Search across name, domain, website, industry, and location fields operationId: getCompaniesFromList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string - name: listId in: query required: true description: The unique identifier of the company list. schema: type: string example: "683d7d2293a39ee1c6651588" - name: offset in: query required: false description: Number of companies to skip (for pagination). schema: type: integer default: 0 example: 0 - name: limit in: query required: false description: Maximum number of companies to return (max 1000). schema: type: integer default: 50 maximum: 1000 example: 50 - name: search in: query required: false description: Search term to filter companies by name, domain, website, industry, or location. schema: type: string example: "technology" responses: "200": description: Successfully retrieved companies from the list. content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Companies fetched from list successfully" } data: type: object properties: contacts: type: array description: Array of company records from the list. items: type: object properties: _id: { type: string, example: "696a2424cf11fd0217574000" } id: { type: string, example: "696a2424cf11fd0217574000" } name: { type: string, example: "TechCorp Solutions" } domain: { type: string, example: "techcorp.com" } website: { type: string, example: "techcorp.com" } linkedin_url: { type: string, example: "linkedin.com/company/techcorp" } industry: { type: string, example: "Technology" } country: { type: string, example: "US" } state: { type: string, example: "CA" } city: { type: string, example: "San Francisco" } recordType: { type: string, example: "company" } savedContactsCount: { type: integer, example: 0 } list: { type: string, example: "683d7d2293a39ee1c6651588" } workspaceId: { type: string, example: "67502c0f567a5a46df3e7ec9" } batchId: { type: string, example: "a6316e79-95e2-4983-b3e1-ec23ea1ee2c6" } csvId: { type: string, example: "696a2424a0ed66cb0bf78e8e" } queryHash: { type: string, example: "d33803629a13fd75b07397b944e5ff69" } source: { type: string, example: "LEAD_FINDER" } deleted: { type: boolean, example: false } createdAt: type: string format: date-time example: "2026-01-16T11:42:28.825Z" updatedAt: type: string format: date-time example: "2026-01-16T11:42:28.825Z" __v: { type: integer, example: 0 } pagination: type: object description: Pagination metadata. properties: total: { type: integer, example: 4 } offset: { type: integer, example: 0 } limit: { type: integer, example: 1 } hasMore: { type: boolean, example: true } listType: type: string enum: [people, company] example: "company" "400": description: Bad Request - Missing or invalid parameters. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid list ID" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: Not Found - List not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/add/leads: post: tags: [Lists] summary: Add leads to a people list description: | Add individual contacts (leads) to a people list. You can add up to 500 contacts at once. Duplicate detection is enabled by default based on email addresses. **Note:** Each list can contain a maximum of 10,000 contacts. operationId: addLeadsToList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - listId - contacts properties: listId: type: string description: The unique identifier of the people list. example: "68495d8e589099bd50f501ad" skipDuplicates: type: boolean description: Skip contacts that already exist in the list (default true). default: true example: true contacts: type: array description: Array of contact objects to add (max 500). maxItems: 500 items: type: object properties: id: { type: string, description: "Contact ID (optional)." } email: type: string format: email description: Email address of the contact. first_name: { type: string, description: "First name of the contact." } last_name: { type: string, description: "Last name of the contact." } title: { type: string, description: "Job title of the contact." } company: { type: string, description: "Company name." } location: { type: string, description: "Location of the contact." } phone_numbers: { type: string, description: "Phone number(s)." } linkedin_url: { type: string, description: "LinkedIn profile URL." } profile_pic: { type: string, description: "URL to profile picture." } example: listId: "68495d8e589099bd50f501ad" skipDuplicates: true contacts: - email: "sarah.johnson@techcorp.com" first_name: "Sarah" last_name: "Johnson" title: "Product Manager" company: "TechCorp Solutions" location: "San Francisco, CA" - email: "michael.chen@startup.io" first_name: "Michael" last_name: "Chen" title: "Engineering Lead" company: "StartupIO" location: "Austin, TX" responses: "200": description: Successfully added contacts to the list. content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Leads added to list successfully" } data: type: object properties: added: type: integer description: Number of contacts successfully added to the list. example: 2 duplicates: type: integer description: Number of duplicate contacts that were skipped. example: 0 total: type: integer description: Total number of contacts now in the list. example: 2 "400": description: Bad Request - Validation error or list limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List limit exceeded. Maximum 10,000 contacts allowed." "401": { $ref: "#/components/responses/Unauthorized" } "404": description: Not Found - List not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/add/companies: post: tags: [Lists] summary: Add companies to a company list description: | Add company records to a company list. You can add up to 500 companies at once. Duplicate detection is enabled by default based on company domain or name. **Note:** Each list can contain a maximum of 10,000 companies. operationId: addCompaniesToList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - listId - contacts properties: listId: type: string description: The unique identifier of the company list. example: "683d7d2293a39ee1c6651588" skipDuplicates: type: boolean description: Skip companies that already exist in the list (default true). default: true example: true contacts: type: array description: Array of company objects (max 500). maxItems: 500 items: type: object properties: id: { type: string, description: "Company ID (optional)." } name: { type: string, description: "Company name.", example: "TechCorp Solutions" } domain: { type: string, description: "Company domain.", example: "techcorp.com" } website: { type: string, description: "Company website URL.", example: "https://techcorp.com" } industry: { type: string, description: "Industry category.", example: "Technology" } location: { type: string, description: "Company location.", example: "San Francisco, CA" } linkedin_url: { type: string, description: "LinkedIn company page URL.", example: "https://linkedin.com/company/techcorp" } example: listId: "683d7d2293a39ee1c6651588" skipDuplicates: true contacts: - name: "TechCorp Solutions" domain: "techcorp.com" website: "https://techcorp.com" industry: "Technology" location: "San Francisco, CA" linkedin_url: "https://linkedin.com/company/techcorp" - name: "Innovation Labs" domain: "innovationlabs.io" website: "https://innovationlabs.io" industry: "Software" location: "Austin, TX" linkedin_url: "https://linkedin.com/company/innovation-labs" responses: "200": description: Successfully added companies to the list. content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Companies added to list successfully" } data: type: object properties: added: type: integer description: Number of companies successfully added to the list. example: 2 duplicates: type: integer description: Number of companies that were duplicates and skipped. example: 0 total: type: integer description: Total number of companies now in the list. example: 3 "400": description: Bad Request - Validation error or list limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List limit exceeded. Maximum 10,000 companies allowed per list" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: Not Found - List not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/remove/leads: post: tags: [Lists] summary: Remove leads from a people list description: | Remove specific contacts from a people list by their contact IDs. This is a soft delete operation - the contacts are marked as deleted but not permanently removed. operationId: removeLeadsFromList parameters: - name: x-api-key in: header required: true description: Your API key. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - listId - contactIds properties: listId: type: string description: The unique identifier of the people list. example: "68495d8e589099bd50f501ad" contactIds: type: array description: Array of contact IDs to remove from the list. items: type: string example: ["695762cdc8baa98925f6ca46", "695762cdc8baa98925f6ca47"] example: listId: "68495d8e589099bd50f501ad" contactIds: - "695762cdc8baa98925f6ca46" - "695762cdc8baa98925f6ca47" responses: "200": description: Successfully removed contacts from the list. content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Leads removed from list successfully" } data: type: object properties: removed: type: integer description: Number of contacts successfully removed from the list. example: 1 remaining: type: integer description: Number of contacts remaining in the list. example: 1 "400": description: Bad Request - Missing or invalid parameters. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid contact IDs" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: Not Found - List not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/remove/companies: post: tags: [Lists] summary: Remove companies from a company list description: | Remove specific companies from a company list by their company IDs. This is a soft delete operation — the companies are marked as deleted but not permanently removed from the database. operationId: removeCompaniesFromList parameters: - name: x-api-key in: header required: true description: Your API key schema: type: string requestBody: required: true content: application/json: schema: type: object required: - listId - contactIds properties: listId: type: string description: ID of the company list example: "507f1f77bcf86cd799439012" contactIds: type: array description: Array of company IDs to remove from the list items: type: string example: - "507f1f77bcf86cd799439015" - "507f1f77bcf86cd799439016" responses: "200": description: Companies removed from list successfully content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "Companies removed from list successfully" } data: type: object properties: removed: type: integer description: Number of companies removed from the list example: 0 remaining: type: integer description: Number of companies remaining in the list example: 3 "400": description: Bad request – validation error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid contactIds" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: List not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/send-to-campaign: post: tags: [Lists] summary: Send leads from a list to a campaign description: | Add contacts from a list directly to a campaign. This operation is asynchronous — contacts are queued and processed in the background. **Range Selection Options (choose one approach):** - `offset` + `limit` → pagination-style selection - `start` + `end` → specific row range (1-based index) **Filtering & Controls:** - `search` → filter contacts by name, email, company, etc. - `queryHash` → filter using a saved query identifier - `skipDuplicates` → skip contacts already added to the campaign - `bounceCheck` → verify email deliverability before adding operationId: sendListToCampaign parameters: - name: x-api-key in: header required: true description: Your API key schema: type: string requestBody: required: true content: application/json: schema: type: object required: - listId - campaignId properties: listId: type: string description: ID of the source list example: "507f1f77bcf86cd799439011" campaignId: type: string description: ID of the destination campaign example: "507f1f77bcf86cd799439020" skipDuplicates: type: boolean description: Skip contacts already in the campaign default: true bounceCheck: type: boolean description: Verify email deliverability before adding default: true offset: type: integer description: Number of contacts to skip (used with limit) default: 0 limit: type: integer description: Maximum number of contacts to add (max 10,000) default: 1000 start: type: integer description: Starting row number (1-based, use with end) end: type: integer description: Ending row number (1-based, use with start) search: type: string description: Search term to filter contacts queryHash: type: string description: Query hash to filter specific results example: listId: "507f1f77bcf86cd799439011" campaignId: "507f1f77bcf86cd799439020" skipDuplicates: true bounceCheck: true limit: 500 responses: "200": description: Contacts from the list have been queued for addition to the campaign content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "List sent to campaign successfully" } data: type: object description: Empty object (processing happens asynchronously) example: {} "400": description: Bad request – validation error or invalid range selection content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid range selection" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: List or campaign not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Campaign not found" "500": { $ref: "#/components/responses/InternalError" } /v2/list/export: get: tags: [Lists] summary: Export list description: | Export contacts from a list in JSON or CSV format. **Supported Formats:** - `json` → Structured JSON response with metadata - `csv` → Downloadable CSV file **Range Selection (choose one approach):** - `offset` + `limit` → pagination-style export - `start` + `end` → specific row range (1-based index) **Limits:** - Maximum 10,000 records per request - For larger lists, use multiple requests with pagination operationId: exportList parameters: - name: x-api-key in: header required: true description: Your API key schema: type: string - name: listId in: query required: true description: ID of the list to export schema: type: string example: "507f1f77bcf86cd799439011" - name: format in: query required: false description: Export format schema: type: string enum: [json, csv] default: json - name: offset in: query required: false description: Number of records to skip (used with limit) schema: type: integer default: 0 - name: limit in: query required: false description: Maximum number of records to export schema: type: integer default: 1000 maximum: 10000 - name: start in: query required: false description: Starting row number (1-based, use with end) schema: type: integer - name: end in: query required: false description: Ending row number (1-based, use with start) schema: type: integer responses: "200": description: Export successful content: application/json: schema: type: object properties: status: { type: string, example: "success" } success: { type: boolean, example: true } message: { type: string, example: "List exported successfully" } data: type: object properties: data: type: array items: type: object additionalProperties: true metadata: type: object properties: total: { type: integer, example: 2100 } offset: { type: integer, example: 0 } limit: { type: integer, example: 1 } returned: { type: integer, example: 1 } hasMore: { type: boolean, example: true } listType: { type: string, example: "people" } text/csv: schema: type: string format: binary "400": description: Bad request – validation error or invalid range selection content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "Invalid range selection" "401": { $ref: "#/components/responses/Unauthorized" } "404": description: List not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: status: "error" success: false message: "List not found" "500": { $ref: "#/components/responses/InternalError" }