openapi: 3.0.3
info:
  title: OurPeople Authentication Broadcasts API
  description: The OurPeople API uses common standards to allow easy read and write access to your data. OurPeople is a frontline communications platform that helps organizations communicate with deskless workers. The API is currently in closed beta.
  contact:
    name: OurPeople Support
    email: support@ourpeople.com
    url: https://ourpeople.com/support
  version: 1.0.0
servers:
- url: https://{account}-api.ourpeople.co
  description: Account-specific API endpoint
  variables:
    account:
      default: example
      description: Your account subdomain. If your console URL is https://example.ourpeople.com, then your API endpoint is https://example-api.ourpeople.co.
tags:
- name: Broadcasts
  description: Inspect broadcasts, deliveries, and recipient engagement.
paths:
  /v1/broadcasts/deliveries:
    get:
      tags:
      - Broadcasts
      summary: List recent deliveries
      description: List recent broadcast deliveries with status and basic metadata.
      operationId: listDeliveries
      security:
      - bearerAuth: []
      responses:
        '200':
          description: A list of recent deliveries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Delivery'
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
  /v1/broadcasts/{broadcastId}:
    get:
      tags:
      - Broadcasts
      summary: Get broadcast details
      description: Fetch detail on the content items attached to a broadcast.
      operationId: getBroadcast
      security:
      - bearerAuth: []
      parameters:
      - name: broadcastId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Broadcast detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Broadcast'
        '401':
          description: Unauthorized
        '404':
          description: Broadcast not found
  /v1/broadcasts/deliveries/{deliveryId}/recipients:
    get:
      tags:
      - Broadcasts
      summary: List delivery recipients
      description: See recipients who engaged with content in a delivery. Includes seenAt and respondedAt timestamps (null if the action has not occurred).
      operationId: listDeliveryRecipients
      security:
      - bearerAuth: []
      parameters:
      - name: deliveryId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A list of recipients for the delivery
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
        '404':
          description: Delivery not found
  /v1/broadcasts/deliveries/{deliveryId}/contents/{contentId}/recipients:
    get:
      tags:
      - Broadcasts
      summary: List content recipients
      description: Return the recipients for a given content item within a delivery. Supported query parameters vary by content type (e.g., rating-based filtering for rating content).
      operationId: listContentRecipients
      security:
      - bearerAuth: []
      parameters:
      - name: deliveryId
        in: path
        required: true
        schema:
          type: string
      - name: contentId
        in: path
        required: true
        schema:
          type: string
      - name: rating
        in: query
        required: false
        description: Filter by rating value when the content type is a rating.
        schema:
          type: integer
      responses:
        '200':
          description: A list of recipients for the content item
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
        '404':
          description: Content or delivery not found
components:
  schemas:
    ContentItem:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          description: The content type (e.g., text, file, rating).
    Delivery:
      type: object
      properties:
        id:
          type: string
          description: Delivery identifier
        broadcastId:
          type: string
          description: Identifier of the parent broadcast
        broadcastName:
          type: string
        status:
          type: string
          description: Delivery status
    Recipient:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        seenAt:
          type: string
          format: date-time
          nullable: true
        respondedAt:
          type: string
          format: date-time
          nullable: true
    Broadcast:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdBy:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        createdAt:
          type: string
          format: date-time
        contents:
          type: array
          items:
            $ref: '#/components/schemas/ContentItem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: OurPeople Developer Documentation
  url: https://developer.ourpeople.com/