Company campaigns - Taptalent Partner API

Company campaigns are workspace-wide automation flows stored as flows with accessLevel: COMPANY. Use them for outbound calling workflows: scheduling, interviews, interest checks, assessment reminders, and similar global campaigns—with IVR or AI call scripts, defined call times, and optional SMS. Use these endpoints to create and update campaigns, inspect their public configuration, and add or remove leads (candidates on the campaign) using the same Bearer API key model as the rest of the Partner API. Base path: /v1/partner/campaigns
Company sites (needed to create a campaign): /v1/partner/company-sites
Authentication: Authorization: Bearer YOUR_API_KEY (same as API keys)

Set purposeType and related fields to match the kind of campaign you are building (same concepts as creating a global / company campaign in the TapTalent app). Optional GET /campaigns query parameters let you filter by status or purposeType.

Concepts

Term	Meaning
Campaign	A row in `client_flow_details` with `accessLevel: COMPANY` — what the product calls a global / company campaign.
Campaign id	Numeric `id` of the flow; use it as `:campaignId` in URLs.
Lead	A person on the campaign. The Partner API exposes `leadId`, which is the same `talentId` used in internal flow APIs (`client_flow_talents` / `client_flow_candidates`).
Response shape	Responses return the partner-facing campaign and lead fields documented in this page.

Typical integration flow

GET /v1/partner/company-sites → pick a companySiteId assigned to the API key user.
POST /v1/partner/campaigns → create a campaign with the appropriate purposeType and payload for that campaign.
POST /v1/partner/campaigns/:campaignId/leads → add one or many candidates.
GET /v1/partner/campaigns/:campaignId/leads → poll status labels until your automation is done.

List campaigns

`GET /campaigns`

Returns company-scoped campaigns (accessLevel: COMPANY) for the company tied to the API key. Results are ordered with newest campaign id first, then paginated. Query parameters

Parameter	Type	Description
`status`	string	Exact match on campaign `status` (e.g. `RUNNING`).
`purposeType`	string	Exact match on `purposeType` (e.g. `ASSESSMENT_REMINDER`, `SCHEDULE`).
`page`	integer	Page number, default `1`, minimum `1`.
`limit`	integer	Page size, default `20`, maximum `100`.

Example: filter by purpose and paginate

curl -s -X GET \
  "https://partner-api.taptalent.io/v1/partner/campaigns?purposeType=SCHEDULE&status=RUNNING&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Example response

{
  "campaigns": [
    {
      "id": 101,
      "title": "Assessment reminders — Q2",
      "status": "RUNNING",
      "purposeType": "ASSESSMENT_REMINDER",
      "timezone": "America/New_York",
      "companySiteId": 12,
      "accessLevel": "COMPANY",
      "createdAt": "2025-04-01T12:00:00.000Z",
      "updatedAt": "2025-04-10T09:30:00.000Z",
      "callSettings": { "callType": "IVR" },
      "assessment": {
        "assessmentTestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "assessmentName": "Technical screen",
        "jobTitle": "Senior Engineer",
        "autoAddInvitedCandidates": false,
        "assessmentFirstReminderDelayHours": 24
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Depending on purposeType, optional blocks such as assessment may appear in list items; callSettings and core fields are included when present in the mapped summary.

Get one campaign

`GET /campaigns/:campaignId`

Returns a campaign detail object with high-level schedule, IVR/AI call settings, opening/closing messages, and purpose-specific blocks when applicable (for example an assessment object for assessment-related campaigns).

404 if the id is invalid, deleted, not in the API key’s company, or not a company (COMPANY) campaign — this avoids leaking whether an id exists in another workspace.

Example request

curl -s -X GET \
  "https://partner-api.taptalent.io/v1/partner/campaigns/101" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (truncated)

{
  "campaign": {
    "id": 101,
    "title": "Assessment reminders — Q2",
    "status": "RUNNING",
    "purposeType": "ASSESSMENT_REMINDER",
    "timezone": "America/New_York",
    "companySiteId": 12,
    "createdAt": "2025-04-01T12:00:00.000Z",
    "updatedAt": "2025-04-10T09:30:00.000Z",
    "callSettings": {
      "callType": "IVR",
      "aiCallScript": ""
    },
    "schedule": {
      "callTimeDisplay": "Apr 15, 2025 10:00 AM",
      "callSchedule": {
        "timeBasis": "UTC",
        "startTimeLocal": null,
        "startTimeUtc": "2025-04-15T14:00:00.000Z"
      },
      "followUpRetries": [
        { "time": "2025-04-16T14:00:00.000Z", "delayDays": 1 }
      ]
    },
    "messages": {
      "openingMessage": "Hi, this is a reminder from Acme about your assessment.",
      "closingMessage": "Thank you. Goodbye."
    },
    "assessment": {
      "assessmentTestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "assessmentName": "Technical screen",
      "jobTitle": "Senior Engineer",
      "autoAddInvitedCandidates": false,
      "assessmentReminderSmsTemplate": "Reminder: complete your assessment.",
      "assessmentPostCallSmsTemplate": "Thanks for taking the call.",
      "assessmentFirstReminderDelayHours": 24
    }
  }
}

Create campaign

`POST /campaigns`

Creates a new company campaign. The request body is validated with strict keys (stripUnknown: true); extra properties are rejected. Rules

purposeType identifies which campaign you are creating (for example scheduling, virtual interviews, interest checks, or assessment reminders). Payload requirements depend on the purpose—mirror the same fields you would use when creating that campaign type in the app (global / company campaign).
Partner API allowlist: by default, only ASSESSMENT_REMINDER is accepted for POST /campaigns (and related updates). Your workspace may support additional purposeType values when configured server-side. The tables below describe payload expectations for each campaign kind (same as the in-app global campaign creator), even if a given type is not yet enabled for your API key.
companySiteId must be a site linked to the API key user (use GET /company-sites first). The server applies the same checks as the in-app global campaign creator.
phoneNumber must be a verified outbound number on the company (present in your company caller ID settings with status VERIFIED). If the number is missing or not verified, the API returns a 400 with a clear message.
Schedule: for campaign types that use bulk calling, supply enough data for a valid first-call schedule. Common patterns:
- UTC-based: callStartTimeUtc (and optionally retryScheduleUtc) or
- Local display + retries: callTime and/or followUpRetries (timezone-aware scheduling, same behavior as in the app).
Follow-up retries (auto-fill): If you omit followUpRetries (local schedule) or retryScheduleUtc (UTC schedule), the server fills four retry slots using the same rules as the TapTalent app: offsets +60, +90, +90, and +90 minutes after the previous slot, with calls constrained to 9:00 AM–9:00 PM (if a slot would fall after 9:00 PM, it moves to 9:00 AM on a later day, matching the product UI).
Assessment reminder job title: For ASSESSMENT_REMINDER, if jobDetails.jobTitle is omitted or empty, the server uses jobDetails.assessmentName, then the campaign title, in that order. At least one of these must yield a non-empty label.

Common body fields (always review validation responses for your chosen purposeType; required flags vary by type.)

Field	Required	Description
`title`	Yes	Campaign name (1–500 characters).
`timezone`	Yes	IANA timezone string (e.g. `America/Chicago`).
`companySiteId`	Yes	Integer or string; from `GET /company-sites`.
`phoneNumber`	Yes	Outbound caller ID; must be a verified number on the company (same rules as product).
`openingMessage`	Yes	IVR opening script (non-empty).
`closingMessage`	Yes	IVR closing script (non-empty).
`purposeType`	Yes	Campaign purpose (e.g. `SCHEDULE`, `ONLINE_INTERVIEW`, `INTEREST_CHECK`, `ASSESSMENT_REMINDER`).
`jobDetails`	Varies	Object whose fields depend on `purposeType` (job copy, assessment ids, interview slots, meeting URLs, etc.—same as the in-app global campaign creator).
`callTime`	Optional	Human-oriented call time string when using local schedule building.
`followUpRetries`	Optional	Array of `{ "time": "<iso or display string>", "delayDays": 0 }` objects.
`callStartTimeUtc`	Optional	ISO UTC string for UTC-basis schedules.
`retryScheduleUtc`	Optional	Optional array for UTC retry slots.
`callType`	Optional	`IVR` or `AICall` (case-insensitive accepted).
`aiCallScript`	Optional	Used when using AI call mode.
`questions`	Optional	Optional IVR question list (array).
`status`	Optional	Flow status if you need a non-default initial value.

For campaign types that use bulk calling, include enough schedule data that a first execution time can be computed (typically callTime / followUpRetries and/or callStartTimeUtc / retryScheduleUtc, depending on how you configure the campaign—same rules as in the app). jobDetails is required when the chosen purposeType expects it.

Required fields by `purposeType` (reference)

These mirror the global / company campaign creator in the app. Fields marked “bulk schedule” apply to the first call and retries (callTime / followUpRetries or callStartTimeUtc / retryScheduleUtc).

`purposeType`	Core requirements
`SCHEDULE`	`jobDetails`: at least `title` (job title). Interview: at least one entry in `interviewSlots` (date + start/end times). Bulk schedule + verified `phoneNumber`.
`ONLINE_INTERVIEW`	Same as scheduling, plus `jobDetails.virtualPlatform`, `virtualMeetingUrl`, and `virtualAdditionalInstructions` (all non-empty strings).
`INTEREST_CHECK`	`jobDetails.interestItemDescription` (non-empty). No interview slots required. Bulk schedule + verified `phoneNumber`.
`ASSESSMENT_REMINDER`	`jobDetails.assessmentTestId`. Job label: `jobTitle` or auto-filled from `assessmentName` or campaign `title`. No interview slots. Bulk schedule + verified `phoneNumber`. Optional SMS templates, `autoAddInvitedCandidates`, `assessmentFirstReminderDelayHours`.

Example jobDetails fields (assessment-oriented campaigns) When purposeType is ASSESSMENT_REMINDER, jobDetails typically includes:

Field	Required	Description
`assessmentTestId`	Yes	Quiz / assessment test identifier (string or number).
`jobTitle`	No*	Role label shown in messaging. *If omitted, the API uses `assessmentName`, then campaign `title`.
`assessmentName`	No	Friendly assessment name (also used as a fallback for job title).
`assessmentReminderSmsTemplate`	No	Max 300 characters.
`assessmentPostCallSmsTemplate`	No	Max 300 characters.
`autoAddInvitedCandidates`	No	Boolean.
`assessmentFirstReminderDelayHours`	No	0–168 (hours).

You may also set assessmentTestId, SMS templates, autoAddInvitedCandidates, and assessmentFirstReminderDelayHours at the top level of the body (duplicates for convenience); jobDetails remains the canonical nested block for that shape. Example: UTC-scheduled creation (ASSESSMENT_REMINDER)

curl -s -X POST "https://partner-api.taptalent.io/v1/partner/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q2 eng assessment reminders",
    "timezone": "America/New_York",
    "companySiteId": 12,
    "phoneNumber": "+15551234567",
    "purposeType": "ASSESSMENT_REMINDER",
    "callType": "IVR",
    "openingMessage": "Hi, this is Acme recruiting about your pending technical assessment.",
    "closingMessage": "Thank you. You will receive a text with the link shortly. Goodbye.",
    "callStartTimeUtc": "2025-06-01T15:00:00.000Z",
    "jobDetails": {
      "assessmentTestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "jobTitle": "Software Engineer",
      "assessmentName": "Technical screen",
      "assessmentFirstReminderDelayHours": 48,
      "assessmentReminderSmsTemplate": "Reminder: your assessment link is ready.",
      "autoAddInvitedCandidates": false
    }
  }'

Example: 201 response

{
  "campaign": {
    "id": 5501,
    "title": "Q2 eng assessment reminders",
    "status": "RUNNING",
    "purposeType": "ASSESSMENT_REMINDER",
    "timezone": "America/New_York",
    "companySiteId": 12,
    "callSettings": { "callType": "IVR", "aiCallScript": "" },
    "schedule": {
      "callTimeDisplay": "Jun 01, 2025 11:00 AM",
      "callSchedule": {
        "timeBasis": "UTC",
        "startTimeUtc": "2025-06-01T15:00:00.000Z"
      },
      "followUpRetries": [
        { "time": "16:00", "delayDays": 0 },
        { "time": "17:30", "delayDays": 0 },
        { "time": "19:00", "delayDays": 0 },
        { "time": "20:30", "delayDays": 0 }
      ]
    },
    "messages": {
      "openingMessage": "Hi, this is Acme recruiting about your pending technical assessment.",
      "closingMessage": "Thank you. You will receive a text with the link shortly. Goodbye."
    },
    "assessment": {
      "assessmentTestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "assessmentName": "Technical screen",
      "jobTitle": "Software Engineer",
      "autoAddInvitedCandidates": false,
      "assessmentReminderSmsTemplate": "Reminder: your assessment link is ready.",
      "assessmentPostCallSmsTemplate": "",
      "assessmentFirstReminderDelayHours": 48
    }
  }
}

Update campaign

`PATCH /campaigns/:campaignId`

Updates editable fields for the campaign: title/name, job title, SMS templates, delay, verified phone number, call schedule (until first call starts), opening/closing messages, and call type / AI script—which fields apply depends on the campaign’s purpose and current state.

The campaign must belong to the company and be a company campaign (404 otherwise).

Common body fields (all optional; only send what changes)

Field	Description
`title` / `campaignName` / `header.title`	Rename the campaign (aliases supported).
`jobName` / `jobTitle`	Updates the job title on the flow where applicable.
`assessmentReminderSmsTemplate` / `assessmentPostCallSmsTemplate`	Max 300 chars each.
`assessmentFirstReminderDelayHours`	Non-negative number.
`phoneNumber`	Must exist and be VERIFIED on the company.
`callTime` / `followUpRetries`	Cannot change after the first outbound call attempt has started (server error).
`openingMessage` / `closingMessage`	Also accepted as `startMessage` / `endMessage`.
`callType` / `aiCallScript`	IVR vs AI call configuration.

Example

curl -s -X PATCH "https://partner-api.taptalent.io/v1/partner/campaigns/5501" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q2 eng reminders (updated)",
    "assessmentReminderSmsTemplate": "Acme: finish your tech screen today.",
    "openingMessage": "Hi, calling from Acme about your assessment."
  }'

Example response

{
  "status": "success",
  "flowId": 5501,
  "campaign": {
    "id": 5501,
    "title": "Q2 eng reminders (updated)",
    "status": "RUNNING",
    "purposeType": "ASSESSMENT_REMINDER",
    "timezone": "America/New_York",
    "companySiteId": 12,
    "callSettings": { "callType": "IVR", "aiCallScript": "" },
    "schedule": { "callTimeDisplay": "...", "callSchedule": null, "followUpRetries": [] },
    "messages": {
      "openingMessage": "Hi, calling from Acme about your assessment.",
      "closingMessage": "Thank you. Goodbye."
    },
    "assessment": {
      "assessmentTestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "jobTitle": "Software Engineer",
      "assessmentReminderSmsTemplate": "Acme: finish your tech screen today.",
      "assessmentPostCallSmsTemplate": "",
      "assessmentFirstReminderDelayHours": 48
    }
  }
}

The campaign object follows the same partner response shape as Get one campaign, including createdAt / updatedAt when present.

Company sites

`GET /company-sites`

Returns sites the API key user may use when creating campaigns. Each entry includes companySiteId and optional site metadata (name, address, region). Example response

{
  "companySites": [
    {
      "companySiteId": 12,
      "isPrimary": true,
      "site": {
        "id": 12,
        "name": "HQ — New York",
        "address": "1 Example Plaza",
        "city": "New York",
        "state": "NY",
        "country": "US"
      }
    }
  ]
}

Leads

`GET /campaigns/:campaignId/leads`

Lists campaign participants with partner-facing lead fields. Query parameters

Parameter	Description
`search`	Case-insensitive substring match on first name, last name, or email.
`status`	UI-oriented bucket: `Interested`, `NotInterested`, `NoAnswer`, `Pending` (maps internal execution statuses).
`page`, `limit`	Same semantics as list campaigns (`limit` max `100`).

Example

curl -s -G "https://partner-api.taptalent.io/v1/partner/campaigns/5501/leads" \
  --data-urlencode "search=ada" \
  --data-urlencode "status=Pending" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example row

{
  "leads": [
    {
      "leadId": 987654,
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phone": "+15559876543",
      "status": "Pending",
      "flowStatus": "Pending",
      "assessmentSubmitted": "Not submitted",
      "addedAt": "2025-06-02T10:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

For campaigns that track assessment submission, assessmentSubmitted is Submitted or Not submitted; flowStatus may show Completed when the lead row completes even if the last dial outcome was pending/no-answer.

`POST /campaigns/:campaignId/leads`

Adds one or many leads in a single request. Only the simple candidate path is supported (no AI search or marketplace bulk import). Body

Field	Type	Description
`leads`	array	Min length 1. Each item must include `email`.

Each lead

Field	Required	Description
`email`	Yes	Valid email; primary dedupe key with internal rules.
`firstName`, `lastName`	No	Empty string allowed.
`phoneNumber`	No	E.164 or local format per company rules.
`linkedin`	No	Profile URL or handle string.

Idempotency: the API does not guarantee idempotent adds. Re-posting the same email may return skipped counts if the candidate is already on the flow or blocked by duplicate/contact rules. Treat added / skipped as best-effort telemetry and reconcile with GET .../leads if needed. Example

curl -s -X POST "https://partner-api.taptalent.io/v1/partner/campaigns/5501/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "email": "ada@example.com",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "phoneNumber": "+15559876543",
        "linkedin": "https://www.linkedin.com/in/example"
      },
      {
        "email": "grace@example.com",
        "firstName": "Grace",
        "lastName": "Hopper"
      }
    ]
  }'

Example response

{
  "added": 2,
  "skipped": 0
}

skipped increments when a row is not added because of duplicates, prior contact, or internal eligibility checks.

`DELETE /campaigns/:campaignId/leads/:leadId`

Removes a lead from the campaign. leadId is the leadId returned by the list endpoint (internal talentId).

curl -s -X DELETE \
  "https://partner-api.taptalent.io/v1/partner/campaigns/5501/leads/987654" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "status": "success",
  "leadId": 987654
}

Webhooks (campaign completion)

When a lead reaches a terminal campaign outcome, TapTalent sends a webhook event:

Event: candidate.flow_completed
When sent: after a lead reaches a terminal status such as completed or terminated
Scope: company-level webhook URL configured in your Partner API settings

Example payload

{
  "event": "candidate.flow_completed",
  "timestamp": "2026-04-20T10:15:30.000Z",
  "companyId": "12345",
  "data": {
    "flowId": 5501,
    "talentId": 987654,
    "flowStatus": "COMPLETED",
    "source": "campaign_execution",
    "reason": null,
    "completedAt": "2026-04-20T10:15:30.000Z",
    "flow": {
      "name": "Q2 eng assessment reminders",
      "purposeType": "ASSESSMENT_REMINDER"
    },
    "candidate": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phoneNumber": "+15559876543"
    }
  }
}

See Webhooks overview and Webhook event types for delivery headers, verification, retries, and handler best practices.

Errors

Partner routes normalize failures to JSON:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "jobDetails.jobTitle": "\"jobTitle\" is required"
    }
  }
}

HTTP	`code`	When
400	`INVALID_REQUEST`	Invalid body fields; see `message` and per-field `details`.
400	`PURPOSE_NOT_ALLOWED_FOR_PARTNER`	The operation is not allowed for this campaign’s purpose or current configuration; see `message`.
404	`NOT_FOUND`	Campaign missing, wrong company, or not a company campaign.
403	`FORBIDDEN`	Client profile / company mismatch for the key (rare on create).
500	`INTERNAL_ERROR`	Unexpected server-side failure. The response uses a generic message only.

Debugging failed requests

If you see a generic error or 500 in your API client:

For INVALID_REQUEST, read error.message (and details when present). For INTERNAL_ERROR, review your request payload and retry; if the issue persists, contact your workspace owner/support with the request context.
Check the terminal where the Partner API (Node) is running. Failed creates are logged as [POST /v1/partner/campaigns] with the underlying exception (operators only).
Confirm companySiteId appears in GET /v1/partner/company-sites for the same API key user, and that phoneNumber is a verified company number (same rules as the in-app global campaign creator).
Confirm your API key’s user has access to the assessment assessmentTestId you pass in jobDetails.

Operational notes

Rate limiting: follows the same limits as other Partner API routes for your workspace.
Voice (IVR): creating or updating IVR messages may trigger text-to-speech generation in the background, as in the product. Administrative or system-only operations are not exposed on the Partner API.

​Concepts

​List campaigns

​GET /campaigns

​Get one campaign

​GET /campaigns/:campaignId

​Create campaign

​POST /campaigns

​Required fields by purposeType (reference)

​Update campaign

​PATCH /campaigns/:campaignId

​Company sites

​GET /company-sites

​Leads

​GET /campaigns/:campaignId/leads

​POST /campaigns/:campaignId/leads

​DELETE /campaigns/:campaignId/leads/:leadId

​Webhooks (campaign completion)

​Errors

​Debugging failed requests

​Operational notes

Concepts

List campaigns

`GET /campaigns`

Get one campaign

`GET /campaigns/:campaignId`

Create campaign

`POST /campaigns`

Required fields by `purposeType` (reference)

Update campaign

`PATCH /campaigns/:campaignId`

Company sites

`GET /company-sites`

Leads

`GET /campaigns/:campaignId/leads`

`POST /campaigns/:campaignId/leads`

`DELETE /campaigns/:campaignId/leads/:leadId`

Webhooks (campaign completion)

Errors

Debugging failed requests

Operational notes