openapi: 3.2.0
info:
  title: Nooks Sequencing Sequence States API
  version: 0.1.0
  description: The Nooks Sequencing API provides programmatic access to manage sequences, tasks, templates, and prospect engagement workflows created using the Nooks SEP.
  contact:
    name: Nooks API Support
    email: support@nooks.in
    url: https://www.nooks.in
  license:
    name: Proprietary
  x-logo:
    url: ./nooks-logo.svg
    altText: Nooks Logo
    href: https://www.nooks.ai
servers:
- url: https://partner-api.nooks.in/v1
  description: Production API
security:
- BearerAuth: []
tags:
- name: Sequence States
  description: Track prospect enrollments in sequences
paths:
  /sequenceStates:
    get:
      operationId: listSequenceStates
      summary: List sequence states
      description: 'Returns a paginated list of sequence states (enrollments). Supports filtering by sequence, prospect, account, and state.


        Example:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/sequenceStates?page[size]=50'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by sequence:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/sequenceStates?filter[sequence][id]=550e8400-e29b-41d4-a716-446655440000'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by account (joins through prospect):

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/sequenceStates?filter[account][id]=990e8400-e29b-41d4-a716-446655440099'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by state:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/sequenceStates?filter[state]=active,paused'' \

        -H "Authorization: Bearer nooks-api-..."

        ```'
      tags:
      - Sequence States
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageAfter'
      - $ref: '#/components/parameters/PageBefore'
      - name: filter[sequence][id]
        in: query
        description: Filter by sequence ID
        required: false
        schema:
          type: string
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
      - name: filter[prospect][id]
        in: query
        description: Filter by prospect ID
        required: false
        schema:
          type: string
          format: uuid
        example: 770e8400-e29b-41d4-a716-446655440003
      - name: filter[account][id]
        in: query
        description: Filter by account ID (matches the prospect's account).
        required: false
        schema:
          type: string
          format: uuid
        example: 990e8400-e29b-41d4-a716-446655440099
      - name: filter[state]
        in: query
        description: 'Filter by state (comma-separated). Valid values: active, paused, finished'
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - active
            - paused
            - finished
        style: form
        explode: false
        example:
        - active
        - paused
      - name: include
        in: query
        description: 'Comma-separated relations to expand inline. Valid values: `sequence`, `prospect`, `creator`, `sequenceStep`. Max 3.'
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - sequence
            - prospect
            - creator
            - sequenceStep
          maxItems: 3
        style: form
        explode: false
        example:
        - sequence
        - prospect
      - $ref: '#/components/parameters/FilterUpdatedAtGte'
      - $ref: '#/components/parameters/FilterUpdatedAtLt'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SequenceState'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                - id: 880e8400-e29b-41d4-a716-446655440010
                  state: active
                  sequence:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    _href: /v1/sequences/550e8400-e29b-41d4-a716-446655440000
                  prospect:
                    id: 770e8400-e29b-41d4-a716-446655440003
                    _href: /v1/prospects/770e8400-e29b-41d4-a716-446655440003
                  account:
                    id: 990e8400-e29b-41d4-a716-446655440099
                    _href: /v1/accounts/990e8400-e29b-41d4-a716-446655440099
                  sequenceStep:
                    id: aa0e8400-e29b-41d4-a716-446655440030
                    _href: /v1/sequenceSteps/aa0e8400-e29b-41d4-a716-446655440030
                  creator:
                    id: 660e8400-e29b-41d4-a716-446655440001
                    _href: /v1/users/660e8400-e29b-41d4-a716-446655440001
                  createdAt: '2025-11-01T10:00:00.000Z'
                  updatedAt: '2025-11-05T14:30:00.000Z'
                links:
                  first: https://partner-api.nooks.in/v1/sequenceStates?page[size]=50
                  prev: null
                  next: https://partner-api.nooks.in/v1/sequenceStates?page[size]=50&page[after]=eyJpZCI6Ijg4MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAxMCIsInYiOjF9
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createSequenceState
      summary: Enroll a prospect in a sequence
      description: 'Enrolls a prospect into a sequence, creating a new sequence state.


        When enrolling on behalf of a user, respect the sequence''s `privacy`

        (returned by `GET /v1/sequences/{id}`): enroll into `private` sequences

        only on behalf of their owner.


        Example:

        ```bash

        curl -X POST ''https://partner-api.nooks.in/v1/sequenceStates'' \

        -H "Authorization: Bearer nooks-api-..." \

        -H "Content-Type: application/json" \

        -d ''{

        "data": {

        "prospect": { "id": "770e8400-e29b-41d4-a716-446655440003" },

        "sequence": { "id": "550e8400-e29b-41d4-a716-446655440000" },

        "owner": { "id": "KKLvN5wQoghWFwUvC75CZ12QM7I3" },

        "mailbox": { "id": "bb0e8400-e29b-41d4-a716-446655440040" },

        "emailOverrides": {

        "aa0e8400-e29b-41d4-a716-446655440050": {

        "subject": "Custom subject for step",

        "body": "

        Custom email body

        "

        }

        }

        }

        }''

        ```'
      tags:
      - Sequence States
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body for enrolling a prospect in a sequence
              properties:
                data:
                  type: object
                  additionalProperties: false
                  properties:
                    prospect:
                      type: object
                      description: The prospect to enroll
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: ID of the prospect
                          example: 770e8400-e29b-41d4-a716-446655440003
                      required:
                      - id
                    sequence:
                      type: object
                      description: The sequence to enroll the prospect in
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: ID of the sequence
                          example: 550e8400-e29b-41d4-a716-446655440000
                      required:
                      - id
                    owner:
                      type: object
                      description: The user who owns this enrollment
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          minLength: 1
                          maxLength: 128
                          pattern: ^[A-Za-z0-9_-]{1,128}$
                          description: ID of the owner user (Firebase UID)
                          example: KKLvN5wQoghWFwUvC75CZ12QM7I3
                      required:
                      - id
                    state:
                      type: string
                      enum:
                      - active
                      - paused
                      default: active
                      description: Initial state of the enrollment
                      example: active
                    mailbox:
                      type: object
                      description: The mailbox to use for email outreach (optional, defaults to user's primary email)
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: ID of the mailbox
                          example: bb0e8400-e29b-41d4-a716-446655440040
                      required:
                      - id
                    scheduledAt:
                      type: string
                      format: date-time
                      description: When to start the sequence (ISO 8601 with timezone offset). If omitted, starts immediately.
                      example: '2025-12-01T09:00:00-05:00'
                    emailOverrides:
                      type: object
                      description: 'Per-step email content overrides. Keys are sequence step IDs (UUIDs, obtainable via GET /sequenceSteps).

                        Values specify custom subject and/or body for that step. Omitted fields use the step''s template defaults.

                        Returns 422 if any key is not a valid step ID within the target sequence.

                        '
                      propertyNames:
                        pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                      additionalProperties:
                        type: object
                        properties:
                          subject:
                            type: string
                            description: Custom email subject line
                            example: Custom subject for this prospect
                          body:
                            type: string
                            description: Custom email body (HTML)
                            example: <p>Custom email body</p>
                        additionalProperties: false
                      example:
                        aa0e8400-e29b-41d4-a716-446655440050:
                          subject: Custom subject for step
                          body: <p>Custom email body</p>
                    enrich:
                      type: object
                      additionalProperties: false
                      description: 'Opt this enrollment into data enrichment, per channel. If the workspace forces

                        enrichment for a channel, that channel is enriched regardless of what you pass

                        here; a `false` or omitted channel simply defers to the workspace setting.

                        '
                      properties:
                        phoneNumbers:
                          type: boolean
                          description: Enrich the prospect's phone numbers on enrollment.
                          example: true
                        emails:
                          type: boolean
                          description: Enrich the prospect's email addresses on enrollment.
                          example: false
                  required:
                  - prospect
                  - sequence
                  - owner
              required:
              - data
            example:
              data:
                prospect:
                  id: 770e8400-e29b-41d4-a716-446655440003
                sequence:
                  id: 550e8400-e29b-41d4-a716-446655440000
                owner:
                  id: KKLvN5wQoghWFwUvC75CZ12QM7I3
                state: active
                mailbox:
                  id: bb0e8400-e29b-41d4-a716-446655440040
                emailOverrides:
                  aa0e8400-e29b-41d4-a716-446655440050:
                    subject: Custom subject for step
                    body: <p>Custom email body</p>
                enrich:
                  phoneNumbers: true
                  emails: false
      responses:
        '201':
          description: Prospect successfully enrolled in sequence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceState'
              example:
                id: 880e8400-e29b-41d4-a716-446655440010
                state: active
                createdAt: '2025-11-01T10:00:00.000Z'
                updatedAt: '2025-11-01T10:00:00.000Z'
                prospect:
                  id: 770e8400-e29b-41d4-a716-446655440003
                  _href: /v1/prospects/770e8400-e29b-41d4-a716-446655440003
                sequence:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  _href: /v1/sequences/550e8400-e29b-41d4-a716-446655440000
                sequenceStep:
                  id: aa0e8400-e29b-41d4-a716-446655440030
                  _href: /v1/sequenceSteps/aa0e8400-e29b-41d4-a716-446655440030
                owner:
                  id: KKLvN5wQoghWFwUvC75CZ12QM7I3
                  _href: /v1/users/KKLvN5wQoghWFwUvC75CZ12QM7I3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - prospect is already enrolled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CONFLICT
                  message: Conflict
                  details:
                    message: Prospect is already enrolled in this sequence
        '422':
          description: 'Unprocessable entity. Possible causes:

            - Enrollment prerequisites not met (e.g. prospect missing a valid email)

            - `emailOverrides` contains step IDs that do not belong to the target sequence

            - `owner.id` is not a user in this workspace (use an id from `GET /v1/users`)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingEmail:
                  summary: Prospect missing valid email
                  value:
                    error:
                      code: UNPROCESSABLE_ENTITY
                      message: Unprocessable entity
                      details:
                        message: Prospect does not have a valid primary email
                ownerNotFound:
                  summary: Owner is not a user in the workspace
                  value:
                    error:
                      code: UNPROCESSABLE_ENTITY
                      message: Unprocessable entity
                      details:
                        message: Owner user KKLvN5wQoghWFwUvC75CZ12QM7I3 not found in this workspace. Use a user id from GET /v1/users.
                invalidStepIds:
                  summary: emailOverrides references invalid step IDs
                  value:
                    error:
                      code: UNPROCESSABLE_ENTITY
                      message: Unprocessable entity
                      details:
                        message: 'emailOverrides contains step IDs not in sequence 550e8400-...: aa0e8400-..., bb0e8400-...'
        '500':
          $ref: '#/components/responses/InternalError'
  /sequenceStates/{id}:
    get:
      operationId: getSequenceState
      summary: Get sequence state by ID
      description: 'Returns a single sequence state by its unique identifier.


        Example:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/sequenceStates/880e8400-e29b-41d4-a716-446655440010'' \

        -H "Authorization: Bearer nooks-api-..."

        ```'
      tags:
      - Sequence States
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier for the sequence state
        schema:
          type: string
          format: uuid
        example: 880e8400-e29b-41d4-a716-446655440010
      - name: include
        in: query
        description: 'Comma-separated relations to expand inline. Valid values: `sequence`, `prospect`, `creator`, `sequenceStep`. Max 3.'
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - sequence
            - prospect
            - creator
            - sequenceStep
          maxItems: 3
        style: form
        explode: false
        example:
        - sequence
        - prospect
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceState'
              example:
                id: 880e8400-e29b-41d4-a716-446655440010
                state: active
                sequence:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  _href: /v1/sequences/550e8400-e29b-41d4-a716-446655440000
                prospect:
                  id: 770e8400-e29b-41d4-a716-446655440003
                  _href: /v1/prospects/770e8400-e29b-41d4-a716-446655440003
                account:
                  id: 990e8400-e29b-41d4-a716-446655440099
                  _href: /v1/accounts/990e8400-e29b-41d4-a716-446655440099
                sequenceStep:
                  id: aa0e8400-e29b-41d4-a716-446655440030
                  _href: /v1/sequenceSteps/aa0e8400-e29b-41d4-a716-446655440030
                creator:
                  id: 660e8400-e29b-41d4-a716-446655440001
                  _href: /v1/users/660e8400-e29b-41d4-a716-446655440001
                createdAt: '2025-11-01T10:00:00.000Z'
                updatedAt: '2025-11-05T14:30:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSequenceState
      summary: Remove prospect from sequence
      description: 'Removes a prospect from a sequence by deleting the sequence state. This unenrolls the prospect and cancels any pending tasks.


        Example:

        ```bash

        curl -X DELETE ''https://partner-api.nooks.in/v1/sequenceStates/880e8400-e29b-41d4-a716-446655440010'' \

        -H "Authorization: Bearer nooks-api-..."

        ```'
      tags:
      - Sequence States
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier for the sequence state to remove
        schema:
          type: string
          format: uuid
        example: 880e8400-e29b-41d4-a716-446655440010
      responses:
        '204':
          description: Prospect successfully removed from sequence
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /sequenceStates/{id}/actions/finish:
    post:
      operationId: finishSequenceState
      summary: Finish a sequence state
      description: 'Marks a sequence state as finished (complete). This stops the prospect''s progression

        through the sequence and performs cleanup of pending tasks.


        This endpoint is idempotent: returns 204 even if the sequence state is already finished.


        Example:

        ```bash

        curl -X POST ''https://partner-api.nooks.in/v1/sequenceStates/880e8400-e29b-41d4-a716-446655440003/actions/finish'' \

        -H "Authorization: Bearer nooks-api-..."

        ```'
      tags:
      - Sequence States
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier for the sequence state
        schema:
          type: string
          format: uuid
        example: 880e8400-e29b-41d4-a716-446655440003
      responses:
        '204':
          description: Sequence state finished (or already finished)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Error:
      type: object
      description: Standard error response
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: NOT_FOUND
            message:
              type: string
              description: Human-readable error message
              example: The requested resource was not found
        traceId:
          type: string
          description: 'Request trace identifier for correlating this error with server

            logs and support requests. Present whenever the request carried a

            trace context (the normal case); omitted otherwise.

            '
          example: abc123def456
    ReferenceObject:
      type: object
      description: A reference to a related resource
      properties:
        id:
          type: string
          description: Unique identifier of the referenced resource
          example: 550e8400-e29b-41d4-a716-446655440000
        _href:
          type: string
          description: API path to the referenced resource
          example: /v1/sequences/550e8400-e29b-41d4-a716-446655440000
      required:
      - id
      - _href
    PaginationLinks:
      type: object
      description: 'Pagination links for navigating through results.

        Links are returned as relative references (path + query) that

        should be resolved against the base URL of the request.

        '
      properties:
        first:
          type: string
          format: uri-reference
          description: URL for the first page
          example: /v1/sequences?page[size]=50
        prev:
          type: string
          format: uri-reference
          nullable: true
          description: URL for the previous page (null if on first page)
          example: null
        next:
          type: string
          format: uri-reference
          nullable: true
          description: URL for the next page (null if on last page)
          example: /v1/sequences?page[size]=50&page[after]=eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInYiOjF9
    SequenceState:
      type: object
      description: A prospect's enrollment in a sequence
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the sequence state
          example: 880e8400-e29b-41d4-a716-446655440010
        state:
          type: string
          enum:
          - active
          - paused
          - finished
          description: 'Current state of the enrollment:

            - `active`: Prospect is actively progressing through the sequence

            - `paused`: Enrollment is temporarily paused

            - `finished`: Enrollment has completed or been stopped

            '
          example: active
        sequence:
          $ref: '#/components/schemas/ReferenceObject'
        prospect:
          $ref: '#/components/schemas/ReferenceObject'
        account:
          nullable: true
          description: 'Account the prospect belongs to. Derived from the prospect''s

            `accountId`; `null` when the prospect has no account. Always

            populated on `GET /sequenceStates` (list and by-id); may be

            omitted from `POST /sequenceStates` 201 responses.

            '
          allOf:
          - $ref: '#/components/schemas/ReferenceObject'
        creator:
          $ref: '#/components/schemas/ReferenceObject'
        owner:
          $ref: '#/components/schemas/ReferenceObject'
        sequenceStep:
          nullable: true
          description: The current sequence step
          allOf:
          - $ref: '#/components/schemas/ReferenceObject'
        createdAt:
          type: string
          format: date-time
          description: When the enrollment was created
          example: '2025-11-01T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: When the enrollment was last updated
          example: '2025-11-05T14:30:00.000Z'
      required:
      - id
      - state
      - sequence
      - prospect
      - creator
      - owner
      - sequenceStep
      - createdAt
      - updatedAt
  parameters:
    PageSize:
      name: page[size]
      in: query
      description: Number of items per page (max 100)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
      example: 50
    FilterUpdatedAtGte:
      name: filter[updatedAt][gte]
      in: query
      description: Filter by minimum updatedAt (ISO 8601 datetime)
      required: false
      schema:
        type: string
        format: date-time
      example: '2025-01-01T00:00:00Z'
    FilterUpdatedAtLt:
      name: filter[updatedAt][lt]
      in: query
      description: Filter by updatedAt before this timestamp, exclusive (ISO 8601 datetime)
      required: false
      schema:
        type: string
        format: date-time
      example: '2026-01-01T00:00:00Z'
    PageBefore:
      name: page[before]
      in: query
      description: 'Cursor for fetching the previous page. Opaque token returned by

        the API in `links.prev`; callers should treat it as opaque and

        only pass values they received from a previous response.

        Malformed cursors return `400 Bad Request`.

        '
      required: false
      schema:
        type: string
      example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInYiOjF9
    PageAfter:
      name: page[after]
      in: query
      description: 'Cursor for fetching the next page. Opaque token returned by the

        API in `links.next`; callers should treat it as opaque and only

        pass values they received from a previous response. Malformed

        cursors return `400 Bad Request`.

        '
      required: false
      schema:
        type: string
      example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInYiOjF9
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: BAD_REQUEST
              message: Invalid page[after] cursor
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: The requested resource was not found
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token sent in the `Authorization` header. Accepts either a

        long-lived Nooks API key (`nooks-api-...`, from Developer Settings →

        API Keys) or an OAuth 2.0 access token issued by

        `https://oauth.nooks.in`. Use whichever you already have — the API

        validates both formats on the same header. For full OAuth flow

        details (authorize/token endpoints, scopes, refresh behavior) see

        the Authentication section of this spec''s introduction.

        '
x-tagGroups:
- name: API Reference
  tags:
  - Sequences
  - SequenceSteps
  - Emails
  - Users
  - SequenceStates
  - Prospects
  - Accounts
  - Notes
  - Mailboxes
  - Calls
  - CallDispositions
  - Tasks
  - EmailTemplates
  - Introspection