Clarify Campaigns API

openapi: 3.2.0
info:
  title: Clarify Campaigns API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
tags:
- name: Campaigns
paths:
  /workspaces/{workspace}/campaigns/{campaignId}/recipients:
    get:
      description: Returns the people enrolled in a campaign as an offset-paginated JSON:API collection, each with their per-recipient engagement — whether they opened, clicked, replied, or unsubscribed, and when each last happened. Filter by engagement with `filter[event]` (for example `filter[event]=clicked` to build a retargeting audience), by delivery state with `filter[status]`, or by name/email with `filter[q]`. Recipients are collapsed to one row per person, preferring their active run.
      operationId: getRecipients
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: campaignId
        required: true
        in: path
        description: The unique ID of the campaign.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: Offset pagination, e.g. `page[offset]=0&page[limit]=100`.
        schema:
          properties:
            offset:
              default: 0
              type: number
              minimum: 0
              description: The number of records to skip before the first result.
              required: false
            limit:
              default: 500
              type: number
              minimum: 1
              maximum: 500
              description: The maximum number of records to return per page (up to 500).
              required: false
          default:
            offset: 0
            limit: 500
          type: object
      - name: sortOrder
        required: false
        in: query
        description: Sort order, e.g. `sortOrder[column]=_created_at&sortOrder[dir]=DESC`.
        schema:
          properties:
            column:
              description: The field name to sort by.
              type: string
              minLength: 1
              required: true
            dir:
              type: string
              enum:
              - ASC
              - DESC
              description: The sort direction.
              required: true
          type: object
      - name: filter
        required: false
        in: query
        description: Nested filter object, e.g. `filter[event]=clicked&filter[status]=completed`.
        schema:
          properties:
            status:
              type: string
              enum:
              - scheduled
              - completed
              - paused
              - failed
              - unsubscribed
              description: Return only recipients in this delivery state, e.g. `filter[status]=completed`.
              required: false
            event:
              type: array
              items:
                type: string
                enum:
                - opened
                - clicked
                - replied
              description: Return only recipients who performed at least one of these engagement events. Comma-separated and OR-ed, e.g. `filter[event]=clicked,replied`.
              required: false
              isArray: true
            q:
              type: string
              maxLength: 50
              description: Case-insensitive substring match against the recipient’s name or email address.
              required: false
          type: object
      responses:
        '200':
          description: A page of the campaign’s recipients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfCampaignRecipientsResponse'
              example:
                links:
                  next: null
                  prev: null
                meta:
                  total_records: 1
                  total_pages: 1
                  total_unfiltered: 12
                  campaign_enabled: true
                  list_evaluation_status: idle
                  list_member_count: 12
                data:
                - type: campaign_recipient
                  id: b41d8f62-0e35-4a7c-9d18-6f2a3c5e8b74
                  attributes:
                    workflow_run_id: b41d8f62-0e35-4a7c-9d18-6f2a3c5e8b74
                    person:
                      _id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                      name:
                        first_name: Jane
                        last_name: Doe
                        full_name: Jane Doe
                      email_addresses:
                        items:
                        - jane@acme.com
                      avatar_url: null
                      job_title: VP of Marketing
                      company_id: c0a80121-7ac0-4b1c-8b6d-3e5f9a2d4c88
                    status: success
                    resume_at: null
                    current_block_id: null
                    started_at: '2026-01-15T09:30:00.000Z'
                    ended_at: '2026-02-01T17:45:00.000Z'
                    exit_reason: null
                    exit_block_id: null
                    has_opened: true
                    has_clicked: true
                    has_replied: false
                    has_unsubscribed: false
                    last_opened_at: '2026-01-16T11:02:41.000Z'
                    last_clicked_at: '2026-01-16T11:03:12.000Z'
                    last_replied_at: null
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: List campaign recipients
      tags:
      - Campaigns
components:
  schemas:
    ListOfCampaignRecipientsResponse:
      type: object
      properties:
        links:
          type: object
          properties:
            next:
              type: string
              nullable: true
              description: URL of the next page, or `null` on the last page.
            prev:
              type: string
              nullable: true
              description: URL of the previous page, or `null` on the first page.
          required:
          - next
          - prev
          description: Pagination links.
        meta:
          type: object
          properties:
            total_records:
              type: number
            total_pages:
              type: number
            total_unfiltered:
              type: number
            campaign_enabled:
              type: boolean
            list_evaluation_status:
              type: string
              enum:
              - idle
              - evaluating
              - error
              nullable: true
            list_member_count:
              type: number
              nullable: true
          required:
          - total_records
          - total_pages
          - total_unfiltered
          - campaign_enabled
          - list_evaluation_status
          - list_member_count
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - campaign_recipient
                description: The resource type; matches the `object` path parameter.
              id:
                type: string
                description: The unique ID of the resource.
              attributes:
                type: object
                properties:
                  workflow_run_id:
                    type: string
                    description: The ID of this recipient’s run through the campaign. Use it to fetch the full engagement timeline.
                  person:
                    type: object
                    properties:
                      _id:
                        type: string
                        description: The unique ID of the person record.
                      name:
                        type: object
                        properties:
                          first_name:
                            type: string
                            description: The person’s first name.
                          last_name:
                            type: string
                            description: The person’s last name.
                          full_name:
                            type: string
                            description: The person’s full name (first and last combined).
                        nullable: true
                        description: The person’s name, or null when the record has no name set.
                      email_addresses:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: string
                        required:
                        - items
                        nullable: true
                        description: The person’s email addresses. The campaign sends to the first item.
                      avatar_url:
                        type: string
                        nullable: true
                        description: URL of the person’s profile image, or null when they have none.
                      job_title:
                        type: string
                        nullable: true
                        description: The person’s job title, or null when not known.
                      company_id:
                        type: string
                        nullable: true
                        description: ID of the company this person belongs to, or null when unaffiliated.
                    required:
                    - _id
                    - name
                    - email_addresses
                    - avatar_url
                    - job_title
                    - company_id
                    nullable: true
                    description: The recipient. Null when the run has no linked person record, or that record no longer exists.
                  status:
                    type: string
                    enum:
                    - pending
                    - running
                    - success
                    - failed
                    - cancelled
                    - skipped
                    - waiting
                    - retrying
                    description: The raw workflow-run state of this recipient’s campaign run. For the delivery status shown in the app, use `filter[status]` to query instead.
                  resume_at:
                    type: number
                    nullable: true
                    description: Unix timestamp (ms) at which a waiting run resumes, or null when the run is not waiting.
                  current_block_id:
                    type: string
                    nullable: true
                    description: The campaign step the recipient is currently waiting on, or null when the run is not waiting.
                  started_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the recipient entered the campaign.
                  ended_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the recipient’s run finished, or null while still active.
                  exit_reason:
                    type: string
                    nullable: true
                    description: Why the run ended (for example a reply or an unsubscribe), or null while still active.
                  exit_block_id:
                    type: string
                    nullable: true
                    description: The campaign step at which the run ended, or null.
                  has_opened:
                    type: boolean
                    description: Whether the recipient opened at least one campaign email.
                  has_clicked:
                    type: boolean
                    description: Whether the recipient clicked a link in a campaign email.
                  has_replied:
                    type: boolean
                    description: Whether the recipient replied to a campaign email.
                  has_unsubscribed:
                    type: boolean
                    description: Whether the recipient unsubscribed.
                  last_opened_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the recipient most recently opened, or null if never.
                  last_clicked_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the recipient most recently clicked a link, or null if never.
                  last_replied_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the recipient most recently replied, or null if never.
                  _created_at:
                    type: string
                    format: date-time
                    description: When this recipient run was created.
                  _updated_at:
                    type: string
                    format: date-time
                    description: When this recipient run was last updated.
                required:
                - workflow_run_id
                - person
                - status
                - resume_at
                - current_block_id
                - started_at
                - ended_at
                - exit_reason
                - exit_block_id
                - has_opened
                - has_clicked
                - has_replied
                - has_unsubscribed
                - last_opened_at
                - last_clicked_at
                - last_replied_at
                - _created_at
                - _updated_at
                description: Field values keyed by field name; available fields depend on the object’s schema.
              relationships:
                type: object
                properties: {}
                description: Related resources keyed by relationship name, present when requested via `include`.
            required:
            - type
            - id
            - attributes
          description: The page of resources.
      required:
      - links
      - meta
      - data
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Send your key in the Authorization header as: `api-key <your-api-key>`.'
    bearer:
      type: http
      scheme: bearer
      description: 'User access token authentication for endpoints that act across workspaces. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'