OurPeople API
The OurPeople API uses common standards to allow easy read and write access to your data, with JWT authentication and broadcast delivery tracking endpoints.
OpenAPI Specification
openapi: 3.0.3
info:
title: OurPeople 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
externalDocs:
description: OurPeople Developer Documentation
url: https://developer.ourpeople.com/
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: Authentication
description: Token issuance and refresh.
- name: Broadcasts
description: Inspect broadcasts, deliveries, and recipient engagement.
paths:
/v1/auth:
post:
tags:
- Authentication
summary: Exchange client credentials for a token
description: >-
Exchange a client ID and secret for a short-lived JWT access token and
a long-lived refresh token.
operationId: createToken
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRequest'
responses:
'200':
description: Token issued
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
description: Invalid credentials
/v1/auth/refresh:
post:
tags:
- Authentication
summary: Refresh an access token
description: Use a refresh token to obtain a new access token and refresh token.
operationId: refreshToken
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshRequest'
responses:
'200':
description: Token refreshed
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
description: Invalid or expired refresh token
/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:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
AuthRequest:
type: object
required:
- id
- secret
properties:
id:
type: string
description: Client identifier
secret:
type: string
description: Client secret credential
RefreshRequest:
type: object
required:
- refresh_token
properties:
refresh_token:
type: string
description: Previously issued refresh token
TokenResponse:
type: object
properties:
token:
type: string
description: JWT access token
refresh_token:
type: string
description: Token used to obtain new access tokens
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
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'
ContentItem:
type: object
properties:
id:
type: string
type:
type: string
description: The content type (e.g., text, file, rating).
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