Create a campaign | Swarmhit Developers

JavaScript SDK: swarmhit.campaigns.create(params?)

Creates a campaign (paused by default). You can set everything up front: the sender pool (linkedinAccountIds), the outreach sequence (its steps), the send schedule, aiInterestEnabled, the email unsubscribe line and tracking, the lead-exclusion rules (excludeListIds plus the exclude* flags), and the initial status. Anything omitted falls back to a sensible default (empty sequence, default 9-19 Mon-Fri schedule, paused). Then add leads with POST /campaigns/{id}/leads and set status to active. Created active, it needs a sequence with something to send in every step, or it is a 400 with code: empty-step, and its senders are checked as on activation (see PATCH /campaigns/{id}).

Sequence wiring: omit id/parent/branch on every step to have them auto-wired into a linear chain in array order (each step attaches to the previous step's natural continuation — the "yes" branch of a connection request or condition, but the "no"/still-no-reply branch after a message, voice note, InMail or email since their "yes"/Replied branch ends the sequence, otherwise its single child). To build a branching tree, give each step a stable id and set parent/branch. Once the lead is connected — the "yes" branch of a connection request (invite, "Accepted") or of an if_connected condition ("Connected") — the invite, inmail, if_connected and if_open_profile steps can't sit below it (the lead is already connected, so a connection request / InMail can't fire and a repeat connected / open-profile check is redundant). To send an InMail only when a request goes unanswered, wire it onto the invite's "no" (Still not accepted) branch, not the linear/"yes" continuation. The inmail step's config.whenUnable (auto | pause | skip, default auto) picks what happens when the InMail can't be sent (the sender has no premium LinkedIn plan, or it is out of InMail credits and cannot InMail this lead for free; only Sales Navigator and Recruiter senders InMail open profiles free): auto pauses the sender when out of credits and otherwise continues to the still-no-reply branch, pause always pauses the sender, skip always continues.

Authorization

bearerAuth

AuthorizationBearer <token>

An API key created on the Access tokens page.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

status?string

Initial status (default paused).

Value in

"draft"
"active"
"paused"
"finished"

linkedinAccountIds?array<string>

Sender pool — one or more LinkedIn sender account ids. Leads are spread evenly across them and stay with their sender once contacted. Every id must be a sender account in this workspace.

emailAccountIds?array<string>

Mailbox pool for email steps. Every id must be a mailbox in this workspace (see GET /email-accounts). Only needed when the sequence has email steps.

whatsappAccountIds?array<string>

WhatsApp number pool for WhatsApp steps. Every id must be a number in this workspace (see GET /whatsapp-accounts). Only needed when the sequence has WhatsApp steps.

senderIds?array<string>

Senders whose accounts fill the pools, on every channel the sequence uses (with no step yet, on the first of LinkedIn, email and WhatsApp they have an account on). A pool sent in the same request keeps exactly what it says. A sender with no account for the sequence is refused (code: sender-no-account), and so is one with none on the primary channel (sender-without-linkedin, sender-without-email or sender-without-whatsapp).

aiInterestEnabled?boolean

Label each reply with AI, at the Reply analysis price per reply read (Settings → Credits usage, for owners and admins). Off unless you pass true (a campaign created in the app starts with it on).

unsubscribe?

Either key alone updates just that key.

tracking?

Either key alone updates just that kind; mailbox goes back to the mailboxes' settings.

excludeListIds?array<string>

Lead list ids whose members are never contacted by this campaign. Every id must be a lead list in this workspace.

excludeOtherCampaigns?boolean

Skip leads any other campaign has already contacted (invited or messaged).

excludeOtherSenders?boolean

Skip leads already messaged by a different sender account.

excludeSameSenderOtherCampaigns?boolean

Skip leads the lead's assigned sender already contacted from another campaign.

companyLimit?|

At most max new people per company per day or week; null turns it off. Changing it lets the leads it holds go again at the next sending time, counted against the new limit.

pauseCompanyOnReply?boolean

A real reply pauses this campaign's other leads at the same company (pausedReason: company_replied). See Campaign.

outOfOffice?

Either key alone updates just that key.

matchEmailProvider?boolean

Provider matching ("Provider Matching" or "Email provider matchmaker" in other tools). A lead whose mail Google or Microsoft receives (read from its email domain's MX records; personal Outlook and Hotmail count as Microsoft) gets its emails from one of the campaign's mailboxes on the same provider when there is one, and waits for it when it is at its daily cap. A lead on another provider, or one the campaign has no mailbox for, uses any mailbox, and so does a lead whose domain hasn't been read yet when its first email is due. It can lower sending volume when most leads use a provider the campaign has few mailboxes for. Default false.

schedule?

Send-window schedule. Replaces the whole schedule — send every field you want to keep; omitted fields fall back to the defaults (Etc/GMT, 09:00-19:00, Mon-Fri). Rejected with 400 if the timezone is unknown, activeDays is empty, activeHours.from is not before to, or startDate is after endDate.

sequence?

Optional outreach sequence to create the campaign with. Omit to start from an empty sequence. See SequenceStepInput for linear vs. branching wiring.

Response Body

`application/json`

curl -X POST "https://example.com/campaigns" \  -H "Content-Type: application/json" \  -d '{    "name": "Q3 — Founders",    "linkedinAccountIds": [      "aCc123",      "aCc456"    ],    "schedule": {      "timezone": "America/New_York",      "activeHours": {        "from": "09:00",        "to": "17:00"      },      "activeDays": [        1,        2,        3,        4,        5      ]    },    "sequence": {      "steps": [        {          "type": "visit_profile",          "nextDelayHours": 24        },        {          "type": "invite",          "config": {            "note": "Hi {{firstName}}, came across your profile…",            "fallbackNote": "Hi there, came across your profile…",            "withdrawEnabled": true,            "withdrawDays": 25          },          "branchDelays": {            "no": 336          }        },        {          "type": "message",          "config": {            "text": "Thanks for connecting, {{firstName}}!"          }        }      ]    }  }'

{  "data": {    "id": "string",    "name": "string",    "status": "draft",    "stats": {      "total": 0,      "done": 0,      "failed": 0    },    "aiInterestEnabled": true,    "unsubscribe": {      "enabled": true,      "text": "string"    },    "tracking": {      "opens": "mailbox",      "clicks": "mailbox"    },    "linkedinAccountIds": [      "string"    ],    "emailAccountIds": [      "string"    ],    "whatsappAccountIds": [      "string"    ],    "senderIds": [      "string"    ],    "excludeListIds": [      "string"    ],    "listId": "string",    "excludeOtherCampaigns": true,    "excludeOtherSenders": true,    "excludeSameSenderOtherCampaigns": true,    "companyLimit": {      "max": 1,      "period": "day",      "scope": "campaign"    },    "pauseCompanyOnReply": true,    "outOfOffice": {      "enabled": true,      "fallbackDays": 7    },    "matchEmailProvider": true,    "schedule": {      "startDate": "2019-08-24T14:15:22Z",      "endDate": "2019-08-24T14:15:22Z",      "timezone": "string",      "activeHours": {        "from": "string",        "to": "string"      },      "activeDays": [        0      ]    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "sequence": {      "steps": [        {          "id": "string",          "type": "if_connected",          "parent": "string",          "branch": "yes",          "config": {},          "nextDelayHours": 0,          "branchDelays": {            "yes": 0,            "no": 0          }        }      ]    }  }}

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`