BAMF.ai Outreach API

openapi: 3.2.0
info:
  title: BAMF Developer Platform Outreach API
  version: 0.1.0
servers:
- url: https://api.bamf.ai/v1
security:
- BearerAuth: []
tags:
- name: Outreach
paths:
  /outreach/discoveries:
    post:
      summary: Start outreach discovery
      description: Starts provider-read-only candidate discovery for a server-issued tenant, workspace, agent session, principal context, provider binding, and capability receipt. Requires a signed-in BAMF user session and Idempotency-Key. Never creates or sends a campaign.
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachDiscoveryStartRequest'
      responses:
        '200':
          description: Discovery state; providerMutation is always false
        '403':
          description: Tenant, principal, capability, or session denied
      tags:
      - Outreach
      operationId: postOutreachDiscoveries
      x-operation-id-source: derived
  /outreach/discoveries/{discovery_session_id}/resume:
    post:
      summary: Resume outreach discovery
      description: Resumes from server-owned coverage; caller-supplied provider cursors and organization IDs are not authority.
      parameters:
      - name: discovery_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachDiscoveryStartRequest'
      responses:
        '200':
          description: Discovery state; providerMutation is always false
        '403':
          description: Tenant, principal, capability, or session denied
      tags:
      - Outreach
      operationId: postOutreachDiscoveriesByDiscoverySessionIdResume
      x-operation-id-source: derived
  /outreach/discoveries/{discovery_session_id}/status:
    post:
      summary: Get outreach discovery status
      description: Reads a tenant- and principal-scoped discovery state without provider mutation.
      parameters:
      - name: discovery_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachDiscoveryScopeRequest'
      responses:
        '200':
          description: Discovery state; providerMutation is false
        '404':
          description: Scoped session not found
      tags:
      - Outreach
      operationId: postOutreachDiscoveriesByDiscoverySessionIdStatus
      x-operation-id-source: derived
  /outreach/discoveries/{discovery_session_id}/cancel:
    post:
      summary: Cancel outreach discovery
      description: Requests cancellation of discovery only. It does not mutate or cancel any campaign.
      parameters:
      - name: discovery_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachDiscoveryScopeRequest'
      responses:
        '200':
          description: Cancellation state; providerMutation is false
      tags:
      - Outreach
      operationId: postOutreachDiscoveriesByDiscoverySessionIdCancel
      x-operation-id-source: derived
  /outreach/discoveries/{discovery_session_id}/save:
    post:
      summary: Save outreach discovery
      description: Explicitly saves the current non-excluded candidates as a durable list snapshot. It does not create, enroll, or send a campaign.
      parameters:
      - name: discovery_session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachDiscoveryScopeRequest'
      responses:
        '200':
          description: Saved snapshot receipt; providerMutation is false
        '503':
          description: Session is not saveable or selection is empty
      tags:
      - Outreach
      operationId: postOutreachDiscoveriesByDiscoverySessionIdSave
      x-operation-id-source: derived
  /outreach/campaigns:
    post:
      summary: Prepare outreach campaign
      description: Prepares copy and cadence against an exact current signed list revision and connector account. Requires a signed-in BAMF user session and Idempotency-Key. Never sends.
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachCampaignPrepareRequest'
      responses:
        '200':
          description: Redacted prepared receipt; providerMutation is false
        '403':
          description: JWT session or principal scope required
      tags:
      - Outreach
      operationId: postOutreachCampaigns
      x-operation-id-source: derived
  /outreach/campaigns/{campaign_id}/approve:
    post:
      summary: Approve outreach campaign
      description: Approves the exact action fingerprint until the supplied expiry. Approval does not queue or send.
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OutreachCampaignScopeRequest'
              - type: object
                required:
                - approval_ref
                - action_fingerprint
                - approval_expires_at
                properties:
                  approval_ref:
                    type: string
                  action_fingerprint:
                    type: string
                    pattern: ^[0-9a-f]{64}$
                  approval_expires_at:
                    type: string
                    format: date-time
      responses:
        '200':
          description: Redacted approval receipt; providerMutation is false
      tags:
      - Outreach
      operationId: postOutreachCampaignsByCampaignIdApprove
      x-operation-id-source: derived
  /outreach/campaigns/{campaign_id}/queue:
    post:
      summary: Queue outreach campaign
      description: Queues the approved exact campaign after freshness checks. Does not send.
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachCampaignScopeRequest'
      responses:
        '200':
          description: Redacted queued receipt; providerMutation is false
      tags:
      - Outreach
      operationId: postOutreachCampaignsByCampaignIdQueue
      x-operation-id-source: derived
  /outreach/campaigns/{campaign_id}/cancel:
    post:
      summary: Cancel outreach campaign
      description: Cancels a prepared, approved, or queued campaign without provider invocation.
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachCampaignScopeRequest'
      responses:
        '200':
          description: Redacted cancellation receipt; providerMutation is false
      tags:
      - Outreach
      operationId: postOutreachCampaignsByCampaignIdCancel
      x-operation-id-source: derived
  /outreach/campaigns/{campaign_id}/status:
    post:
      summary: Get outreach campaign status
      description: Reads tenant- and principal-scoped state and redacted receipts.
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachCampaignScopeRequest'
      responses:
        '200':
          description: Redacted status; providerMutation is false
        '404':
          description: Scoped campaign not found
      tags:
      - Outreach
      operationId: postOutreachCampaignsByCampaignIdStatus
      x-operation-id-source: derived
  /outreach/campaigns/{campaign_id}/admit-execution:
    post:
      summary: Admit outreach campaign execution
      description: 'Moves the exact queued campaign to executing after rechecking list, connector, fingerprint, and approval. This is admission only: it never calls a provider and is not proof of send or delivery.'
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OutreachCampaignScopeRequest'
              - type: object
                required:
                - action_fingerprint
                properties:
                  action_fingerprint:
                    type: string
                    pattern: ^[0-9a-f]{64}$
      responses:
        '200':
          description: Redacted execution-admission receipt; providerMutation is false and no send is proven
      tags:
      - Outreach
      operationId: postOutreachCampaignsByCampaignIdAdmitExecution
      x-operation-id-source: derived
  /outreach/exact-thread-replies:
    post:
      summary: Prepare or stop an exact-thread reply
      description: Evaluates and persists a reply or follow-up against server-owned account, exact provider thread/message receipt, suppression, approval, and identity evidence. Requires a signed-in BAMF user session and Idempotency-Key. It returns prepared or stopped and never invokes or sends through a provider.
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExactThreadReplyPrepareRequest'
      responses:
        '200':
          description: Redacted prepared/stopped decision receipt; providerMutation and sendAvailable are false
        '403':
          description: JWT session or workspace scope required
        '409':
          description: Idempotency key conflicts with a different request
      tags:
      - Outreach
      operationId: postOutreachExactThreadReplies
      x-operation-id-source: derived
  /outreach/growth-deliveries/prepare:
    post:
      summary: Prepare exact-comment growth delivery
      description: Persists a preparation-only resource giveaway, newsletter, and booking handoff bound to one exact eligible comment, recipient, account, thread, approval, and artifact revisions. Requires a signed-in BAMF user session and Idempotency-Key. It never calls, sends, or claims delivery through a provider.
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 240
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutreachGrowthDeliveryPrepareRequest'
      responses:
        '200':
          description: Prepared receipt with providerMutation and submitted fixed false
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutreachGrowthDeliveryPrepareResponse'
        '403':
          description: JWT session required
        '409':
          description: Stale, mismatched, opted-out, duplicate, or idempotency-conflicting request
      tags:
      - Outreach
      operationId: postOutreachGrowthDeliveriesPrepare
      x-operation-id-source: derived
components:
  schemas:
    ExactThreadReplyPrepareRequest:
      type: object
      additionalProperties: false
      required:
      - workspace_id
      - intent
      properties:
        workspace_id:
          type: string
          format: uuid
        intent:
          type: object
          additionalProperties: false
          required:
          - version
          - account_ref
          - channel
          - action
          - draft_id
          - draft_revision
          - draft_sha256
          - approval_id
          - thread
          - identity
          properties:
            version:
              const: exact-thread-reply/v1
            account_ref:
              type: string
            channel:
              type: string
              enum:
              - linkedin
              - gmail
              - x
              - instagram
            action:
              type: string
              enum:
              - reply
              - follow_up
            draft_id:
              type: string
            draft_revision:
              type: integer
              minimum: 1
            draft_sha256:
              type: string
              pattern: ^[0-9a-f]{64}$
            approval_id:
              type: string
            thread:
              type: object
              additionalProperties: false
              required:
              - provider_thread_id
              - source_message_id
              - provider_receipt_id
              - observed_at
              properties:
                provider_thread_id:
                  type: string
                source_message_id:
                  type: string
                provider_receipt_id:
                  type: string
                observed_at:
                  type: string
                  format: date-time
            identity:
              type: object
              additionalProperties: false
              required:
              - evidence_id
              - subject_id
              - linkedin_profile_url
              - gmail_address
              - observed_at
              - expires_at
              properties:
                evidence_id:
                  type: string
                subject_id:
                  type: string
                linkedin_profile_url:
                  type:
                  - string
                  - 'null'
                gmail_address:
                  type:
                  - string
                  - 'null'
                observed_at:
                  type: string
                  format: date-time
                expires_at:
                  type: string
                  format: date-time
    OutreachGrowthDeliveryPrepareRequest:
      type: object
      additionalProperties: false
      required:
      - schema_version
      - tenant_id
      - workspace_id
      - principal_context_ref_id
      - recipient
      - eligibility
      - artifacts
      - approval
      - suppression
      - delivery
      properties:
        schema_version:
          type: integer
          const: 1
        tenant_id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        principal_context_ref_id:
          type: string
          format: uuid
        recipient:
          type: object
          additionalProperties: false
          required:
          - recipient_id
          - account_id
          - thread_id
          properties:
            recipient_id:
              type: string
              minLength: 1
            account_id:
              type: string
              minLength: 1
            thread_id:
              type: string
              minLength: 1
        eligibility:
          type: object
          additionalProperties: false
          required:
          - evidence_id
          - tenant_id
          - workspace_id
          - principal_context_ref_id
          - account_id
          - thread_id
          - recipient_id
          - source_receipt_id
          - post_id
          - comment_id
          - comment_text
          - keyword
          - captured_at
          - eligible_until
          properties:
            evidence_id:
              type: string
              minLength: 1
            tenant_id:
              type: string
              format: uuid
            workspace_id:
              type: string
              format: uuid
            principal_context_ref_id:
              type: string
              format: uuid
            account_id:
              type: string
              minLength: 1
            thread_id:
              type: string
              minLength: 1
            recipient_id:
              type: string
              minLength: 1
            source_receipt_id:
              type: string
              minLength: 1
            post_id:
              type: string
              minLength: 1
            comment_id:
              type: string
              minLength: 1
            comment_text:
              type: string
              minLength: 1
            keyword:
              type: string
              minLength: 1
            captured_at:
              type: string
              format: date-time
            eligible_until:
              type: string
              format: date-time
        artifacts:
          type: array
          minItems: 3
          maxItems: 3
          items:
            type: object
            additionalProperties: false
            required:
            - kind
            - artifact_id
            - revision
            properties:
              kind:
                type: string
                enum:
                - resource
                - newsletter
                - booking
              artifact_id:
                type: string
                minLength: 1
              revision:
                type: string
                minLength: 1
        approval:
          type: object
          additionalProperties: false
          required:
          - approval_id
          - revision
          - binding
          - approved_at
          - expires_at
          properties:
            approval_id:
              type: string
              minLength: 1
            revision:
              type: string
              minLength: 1
            binding:
              type: string
              minLength: 1
            approved_at:
              type: string
              format: date-time
            expires_at:
              type: string
              format: date-time
        suppression:
          type: object
          additionalProperties: false
          required:
          - opted_out
          - checked_at
          properties:
            opted_out:
              type: boolean
            checked_at:
              type: string
              format: date-time
        delivery:
          type: object
          additionalProperties: false
          required:
          - delivery_id
          - state
          - prior_delivery_ids
          properties:
            delivery_id:
              type: string
              minLength: 1
            state:
              type: string
              const: pending
            prior_delivery_ids:
              type: array
              items:
                type: string
    OutreachCampaignScopeRequest:
      type: object
      additionalProperties: false
      required:
      - workspace_id
      - session_id
      - principal_context_ref_id
      properties:
        workspace_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        principal_context_ref_id:
          type: string
          format: uuid
    OutreachCampaignPrepareRequest:
      allOf:
      - $ref: '#/components/schemas/OutreachCampaignScopeRequest'
      - type: object
        required:
        - binding
        - plan
        properties:
          binding:
            type: object
            additionalProperties: false
            required:
            - search_list_id
            - snapshot_id
            - list_version
            - connector_provider
            - connector_account_id
            - channel
            properties:
              search_list_id:
                type: string
                format: uuid
              snapshot_id:
                type: string
                format: uuid
              list_version:
                type: integer
                minimum: 1
              connector_provider:
                type: string
              connector_account_id:
                type: string
              channel:
                type: string
                enum:
                - linkedin
                - gmail
                - x
                - instagram
          plan:
            type: object
            additionalProperties: false
            required:
            - copy
            - cadence
            - timezone
            properties:
              copy:
                type: array
                minItems: 1
                items:
                  type: object
                  required:
                  - step
                  - body
                  properties:
                    step:
                      type: integer
                      minimum: 1
                    body:
                      type: string
                      minLength: 1
                    subject:
                      type: string
              cadence:
                type: array
                minItems: 1
                items:
                  type: object
                  required:
                  - step
                  - delayMinutes
                  properties:
                    step:
                      type: integer
                      minimum: 1
                    delayMinutes:
                      type: integer
                      minimum: 0
              timezone:
                type: string
              resource_refs:
                type: array
                items:
                  type: string
              booking_ref:
                type:
                - string
                - 'null'
    OutreachDiscoveryScopeRequest:
      type: object
      additionalProperties: false
      required:
      - workspace_id
      - session_id
      - principal_context_ref_id
      - gateway_run_id
      - provider
      - provider_account_id
      - capability_receipt_ref
      properties:
        workspace_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        principal_context_ref_id:
          type: string
          format: uuid
        gateway_run_id:
          type: string
          format: uuid
        provider:
          type: string
          maxLength: 64
        provider_account_id:
          type: string
          maxLength: 256
        capability_receipt_ref:
          type: string
          maxLength: 256
    OutreachDiscoveryStartRequest:
      allOf:
      - $ref: '#/components/schemas/OutreachDiscoveryScopeRequest'
      - type: object
        required:
        - source_mode
        - targeting
        properties:
          source_mode:
            type: string
            enum:
            - external
            - crm
            - first_degree
          targeting:
            type: string
            minLength: 1
            maxLength: 4000
    OutreachGrowthDeliveryPrepareResponse:
      type: object
      additionalProperties: false
      required:
      - version
      - receiptId
      - preparedIntentId
      - replay
      - state
      - suppressionOutcome
      - providerMutation
      - submitted
      properties:
        version:
          const: outreach-growth-delivery-preparation/v1
        receiptId:
          type: string
          format: uuid
        preparedIntentId:
          type: string
          format: uuid
        replay:
          type: boolean
        state:
          const: prepared
        suppressionOutcome:
          const: clear
        providerMutation:
          const: false
        submitted:
          const: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer