Skip to navigation
HeyReach APICampaigns

CreateV2

View as Markdown

Creates a campaign in DRAFT status, with an optional sequence that may include voice notes.

The v2 version of Create. It takes the same body, except that sequence is a PublicSequenceNodeDtoV2: a MESSAGE node carries messageVersions (text and voice versions) instead of messages. Use it instead of Create whenever the new campaign has a voice step. The node, MESSAGE payload and message version fields, and the voice rules that return 400, are described on UpdateSequenceV2 and apply here unchanged - except that a DYNAMIC script with fewer than 3 spoken words is always refused here, since nothing is stored yet.

After the campaign is configured, call StartCampaign (POST /api/public/campaign/StartCampaign?campaignId=) to activate it. A campaign cannot be started without a sequence; if you omit sequence, add one with UpdateSequenceV2 first. When the sequence has a DYNAMIC voice version, every sender needs a voice assigned (SetSenderVoice), or StartCampaign returns 400 SENDER_VOICE_MISSING.

Body Parameters

  • name (string, required): The campaign name. 1-50 characters.

  • linkedInUserListId (long, required): ID of the lead list. Must exist and be of type USER_LIST.

  • linkedInAccountIds (int[], required): Sender LinkedIn account IDs. 1-100 items. All accounts must exist and be connected.

  • excludeContactedFromOtherCampaigns (bool, optional): Skip leads already in any other campaign. Default false.

  • excludeHasOtherAccConversations (bool, optional): Skip leads that already have conversations with other sender accounts. Default false.

  • excludeContactedFromSenderInOtherCampaign (bool, optional): Skip leads the sender accounts have already contacted in other campaigns. Default false.

  • excludeListId (long, optional): A separate list of leads to always exclude. Must not equal linkedInUserListId.

  • excludeFromLeadBlacklist (bool, optional): Skip leads on the workspace’s lead blacklist. Default true; send false to opt out.

  • excludeFromCompanyBlacklist (bool, optional): Skip leads whose company is on the workspace’s company blacklist. Default true; send false to opt out.

  • schedule (CampaignScheduleApiDto, optional): When the campaign runs. See UpdateSchedule for the object shape. If omitted, defaults to Mon-Fri 09:00-17:00 UTC.

  • sequence (PublicSequenceNodeDtoV2, optional): The automation workflow. The START node is implicit - do not include it - and every path must end with an END node.

Errors

Every { "errorMessage": "..." } error body carries an errorCode; branch on the code, not on the message. Request-validation 400s (for example a missing name, or an empty linkedInAccountIds) use the standard problem-details shape instead.

  • 400 LEAD_LIST_NOT_FOUND, LEAD_LIST_TYPE_INVALID, EXCLUDE_LIST_SAME_AS_LEAD_LIST, LINKEDIN_ACCOUNT_NOT_FOUND, LINKEDIN_ACCOUNT_AUTH_INVALID (a sender is disconnected), CAMPAIGN_SCHEDULE_INVALID, CAMPAIGN_TIMEZONE_INVALID, or one of the sequence codes listed on UpdateSequenceV2 other than CAMPAIGN_STATUS_NOT_EDITABLE and SEQUENCE_UPDATE_INCONSISTENT.
  • 403 NO_ACTIVE_SUBSCRIPTION: the workspace has no active subscription.
  • 404 CAMPAIGN_API_NOT_ENABLED (the campaign API is not enabled for your account), and INTEGRATION_RESOURCE_NOT_FOUND (the Instantly, Smartlead or EmailBison campaign or list of a SEND_LEAD_TO_* node was not found).

Headers

X-API-KEYstringOptional

API key header using this scheme. Example: “X-API-KEY: {API_KEY}”

Request

This endpoint expects an object.
namestringRequired1-50 characters
The campaign name.
linkedInUserListIdlongRequired

ID of the lead list. Must exist and be of type USER_LIST.

linkedInAccountIdslist of integersRequired
Sender LinkedIn account IDs. All accounts must exist and be connected.
excludeContactedFromOtherCampaignsbooleanOptionalDefaults to false
excludeHasOtherAccConversationsbooleanOptionalDefaults to false
excludeContactedFromSenderInOtherCampaignbooleanOptionalDefaults to false
excludeListIdlong or nullOptional

A separate list of leads to always exclude. Must not equal linkedInUserListId.

excludeFromLeadBlacklistbooleanOptionalDefaults to true
excludeFromCompanyBlacklistbooleanOptionalDefaults to true
schedulemap from strings to anyOptional

When the campaign runs. See UpdateSchedule for every field. If omitted, defaults to Mon-Fri 09:00-17:00 UTC.

sequenceobjectOptional

One node of a campaign sequence on the v2 endpoints (GetCampaignSequenceV2, UpdateSequenceV2, CreateV2). Nodes form a tree through conditionalNode and unconditionalNode. The START node is implicit - the root is your first action node - and every path ends with an END node.

Response

OK
campaignIdinteger

Errors

400
Create V2campaigns Request Bad Request Error
403
Create V2campaigns Request Forbidden Error
404
Create V2campaigns Request Not Found Error