> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a step to a campaign

> Adds a step: a message on one channel, a LinkedIn visit or like, or a condition that branches the sequence. Place it with `sequenceNumber`, in the main sequence or, with `parentStepId` and `branchKey`, in a condition's lane. Once leads move through a branched sequence its shape is fixed: `409` `sequence_structure_locked`. An `ai_generated` step has its topic and title written before the answer.

It answers once the writing is done, which can take a minute: allow two minutes.

Free. **Scope:** campaigns, with a key that can write.



## OpenAPI

````yaml /openapi.json post /v1/campaigns/{campaignId}/steps
openapi: 3.1.0
info:
  title: outbound.dev API
  version: v1
  description: Find people and companies, and see what every call costs, with one API key.
servers:
  - url: https://api.outbound.dev
security: []
tags:
  - name: People
    description: >-
      Search people with filters, a saved search or a plain-language query,
      count matches and look up filter values.
  - name: Companies
    description: >-
      Search companies, count matches, name one company by its name, domain or
      LinkedIn page, and list its people.
  - name: Saved searches
    description: Keep a search under a title and run it again, for people or for companies.
  - name: Lists
    description: >-
      Keep people or companies in lists: create and change lists, page through
      their rows, and add or remove people.
  - name: Folders
    description: Group lists of one kind into folders.
  - name: Enrichment
    description: >-
      Find people's work emails and phone numbers: one person, a batch of
      people, or a list.
  - name: Jobs
    description: >-
      Long tasks a call started: their progress, what they produced and what
      they were charged, and stopping them.
  - name: Accounts
    description: >-
      Connect the mailboxes and LinkedIn seats that campaigns and the inbox send
      from, and look after them.
  - name: Campaigns
    description: >-
      Email and LinkedIn campaigns: their steps, the people they enroll, their
      queue of messages, templates, the knowledge hubs and writing styles AI
      steps are written from, the tracking domain their links go through, and
      the lists every campaign leaves out.
  - name: Inbox
    description: >-
      Read and answer the conversations of your mailboxes and LinkedIn seats,
      and send new messages and invitations.
  - name: Account
    description: >-
      The calling key and its organization, its rate limits, and revoking the
      key.
  - name: Billing
    description: The balance, the ledger of every change to it, and the price list.
  - name: Usage and requests
    description: >-
      Calls and spend by day, and the record of every request of the last 30
      days.
paths:
  /v1/campaigns/{campaignId}/steps:
    post:
      tags:
        - Campaigns
      summary: Add a step to a campaign
      description: >-
        Adds a step: a message on one channel, a LinkedIn visit or like, or a
        condition that branches the sequence. Place it with `sequenceNumber`, in
        the main sequence or, with `parentStepId` and `branchKey`, in a
        condition's lane. Once leads move through a branched sequence its shape
        is fixed: `409` `sequence_structure_locked`. An `ai_generated` step has
        its topic and title written before the answer.


        It answers once the writing is done, which can take a minute: allow two
        minutes.


        Free. **Scope:** campaigns, with a key that can write.
      operationId: postCampaignsCampaignIdSteps
      parameters:
        - name: campaignId
          in: path
          required: true
          description: The campaign's id.
          schema:
            type: string
            minLength: 24
            maxLength: 24
            pattern: ^[0-9a-fA-F]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: >-
                    `email`, `linkedin_connection` (an invitation),
                    `linkedin_message` (to a connection), `linkedin_visit` (a
                    profile visit), `linkedin_like` (a like on a recent post),
                    `inmail`, or `condition`: a branch that waits for
                    `conditionType` and sends each lead down its `yes` or `no`
                    lane, or for an `ab_split`, down variant `a` or `b` at once.
                    A `linkedin_connection` step cannot follow a
                    `linkedin_message` step.
                  enum:
                    - email
                    - linkedin_connection
                    - linkedin_message
                    - linkedin_visit
                    - linkedin_like
                    - inmail
                    - condition
                type:
                  type: string
                  description: >-
                    `manual` (the default) sends `subject` and `body` as
                    written; `ai_generated` writes each message for each lead
                    from a topic it writes itself; `ai_reply` drafts a reply
                    from `topic` that waits for your approval. A condition is
                    always `manual`.
                  enum:
                    - manual
                    - ai_generated
                    - ai_reply
                sequenceNumber:
                  type: integer
                  description: >-
                    The step's place, from 0, in the main sequence or in the
                    lane `parentStepId` and `branchKey` name. Send the length of
                    the sequence or lane to add at its end; a taken place
                    answers `409` `step_position_taken`.
                  minimum: 0
                  maximum: 50
                daysBetween:
                  type: integer
                  description: >-
                    Days to wait after the step before (or after the start, for
                    the first step), 0 to 90. On a condition, how long it waits
                    for its signal, 1 to 30 days; an `ab_split` waits for
                    nothing: send 0.
                  minimum: 0
                  maximum: 90
                subject:
                  type: string
                  description: >-
                    A `manual` step's subject line, up to 500 characters. Not on
                    visits, likes and conditions.
                  maxLength: 500
                body:
                  type: string
                  description: >-
                    A `manual` step's message, up to 20,000 characters; the
                    tokens `GET /v1/campaigns/{campaignId}/variables` lists,
                    such as `{Contact First Name}`, are filled in for each lead.
                    On a `linkedin_connection` step, the invitation note, up to
                    200 characters. Not on visits, likes and conditions.
                topic:
                  type: string
                  description: >-
                    What the step should say, up to 500 characters. Needed by
                    `ai_reply`; `ai_generated` writes its own.
                  minLength: 1
                  maxLength: 500
                cc:
                  type: array
                  description: Up to 10 addresses copied on every email of the step.
                  maxItems: 10
                  items:
                    type: string
                    maxLength: 320
                parentStepId:
                  type: string
                  description: >-
                    The condition whose lane the step goes in, with `branchKey`.
                    Left out, the step goes in the main sequence.
                  minLength: 24
                  maxLength: 24
                  pattern: ^[0-9a-fA-F]+$
                branchKey:
                  type: string
                  description: >-
                    The lane of `parentStepId`: `yes` or `no` under a condition,
                    `a` or `b` under an A/B split.
                  enum:
                    - 'yes'
                    - 'no'
                    - a
                    - b
                    - null
                conditionType:
                  type: string
                  description: >-
                    Conditions only: `invite_accepted` waits for the invitation
                    of the nearest `linkedin_connection` step before it,
                    `clicked_link` for a click in the nearest email before it,
                    and `ab_split` splits leads between variants `a` and `b` by
                    `splitArms`. Conditions can be added only before the
                    campaign starts.
                  enum:
                    - invite_accepted
                    - clicked_link
                    - ab_split
                splitArms:
                  type: array
                  description: >-
                    `ab_split` only: both variants, `a` then `b`, each `{ key,
                    label?, weight }`. 50 each when left out.
                  minItems: 2
                  maxItems: 2
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        description: 'The variant: `a` or `b`.'
                        enum:
                          - a
                          - b
                      label:
                        type: string
                        description: A name for the variant, up to 40 characters.
                        maxLength: 40
                      weight:
                        type: integer
                        description: The whole percent of leads sent down this variant.
                        minimum: 0
                        maximum: 100
                    required:
                      - key
                      - weight
              required:
                - channel
                - sequenceNumber
                - daysBetween
            example:
              channel: email
              sequenceNumber: 1
              daysBetween: 3
              subject: 'Re: your Lisbon fleet'
              body: <p>Hi {Contact First Name}, worth a short call this week?</p>
      responses:
        '201':
          description: The new step.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-Charged-Usd:
              $ref: '#/components/headers/ChargedUsd'
            X-Balance-Usd:
              $ref: '#/components/headers/BalanceUsd'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                  channel:
                    type: string
                    enum:
                      - email
                      - linkedin_connection
                      - linkedin_message
                      - linkedin_visit
                      - linkedin_like
                      - inmail
                      - condition
                  type:
                    type: string
                    enum:
                      - manual
                      - ai_generated
                      - ai_reply
                  sequenceNumber:
                    type: integer
                    description: Its place, from 0, in the main sequence or its lane.
                  daysBetween:
                    type: integer
                    description: Days after the step before. On a condition, its window.
                  title:
                    type: string
                  topic:
                    type: string
                  subject:
                    type: string
                  body:
                    type: string
                    description: On a `linkedin_connection` step, the invitation note.
                  cc:
                    type: array
                    items:
                      type: string
                  parentStepId:
                    type: string
                    description: The condition whose lane holds the step.
                  branchKey:
                    type: string
                    enum:
                      - 'yes'
                      - 'no'
                      - a
                      - b
                  conditionType:
                    type: string
                    enum:
                      - invite_accepted
                      - clicked_link
                      - ab_split
                  splitArms:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          enum:
                            - a
                            - b
                        label:
                          type: string
                        weight:
                          type: integer
                    description: An A/B split's variants.
                  splitWeightsChangedAt:
                    type: string
                    format: date-time
              example:
                id: 6a1f0c2b9d4e8a7f3c5b2e31
                channel: email
                type: manual
                sequenceNumber: 0
                daysBetween: 0
                title: Freight ops intro
                subject: Your Lisbon fleet
                body: >-
                  <p>Hi {Contact First Name},</p><p>Saw Northwind runs 40 trucks
                  out of Lisbon.</p>
                cc: []
        '429':
          $ref: '#/components/responses/RateLimited'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
components:
  headers:
    RequestId:
      description: The request's id. Quote it when you write to support.
      schema:
        type: string
        example: req_6a1f0c2b9d4e8a7f3c5b2e10
    ChargedUsd:
      description: What this call cost, in US dollars as an exact six-decimal string.
      schema:
        type: string
        example: '0.005000'
    BalanceUsd:
      description: >-
        The organization's balance after this call, in US dollars as an exact
        six-decimal string.
      schema:
        type: string
        example: '9.995000'
    RateLimitLimit:
      description: >-
        The calls allowed in the window of the route's limit with the fewest
        calls left.
      schema:
        type: integer
        example: 20
    RateLimitRemaining:
      description: The calls left in that window.
      schema:
        type: integer
        example: 19
    RateLimitReset:
      description: Seconds until that window resets.
      schema:
        type: integer
        example: 42
    RetryAfter:
      description: Seconds to wait before calling again.
      schema:
        type: integer
        example: 42
  responses:
    RateLimited:
      description: >-
        Too many calls. Wait the seconds in Retry-After, then call again. When
        the limit reached does not say when it resets, such as a mail provider's
        own limit on a mailbox, Retry-After is 60. The RateLimit headers
        describe this API's own limits, so they come only with a 429 one of
        those gave. The body is empty.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
    Error:
      description: The request was refused. The body names the reason in `error.code`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        Something failed on our side and nothing was charged. Retry with
        backoff; quote X-Request-Id if it persists. The body is empty.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - doc_url
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable: branch on it. It never changes
                meaning.
            message:
              type: string
              description: >-
                A human-readable explanation for logs. It may be reworded at any
                time.
            param:
              type: string
              description: The request field the error is about, when there is one.
            doc_url:
              type: string
              description: The code's entry in the errors reference.
            request_id:
              type: string
              description: >-
                The request's id, as in the X-Request-Id header. Quote it to
                support.
      example:
        error:
          code: insufficient_balance
          message: Your balance cannot cover this call. Add funds and try again.
          doc_url: https://docs.outbound.dev/errors#insufficient_balance
          request_id: req_6a1f0c2b9d4e8a7f3c5b2e10
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key from the console, starting `ob_live_`, sent as
        `Authorization: Bearer <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.