Skip to main content

Broadcasts

important

The OurPeople REST API is currently in a closed beta only.

Broadcasts

Broadcasts can be reported on via the public API. Every broadcast is associated with one or more deliveries.

Additionally, each broadcast contains one or more content items of varying types. These content items are the same for every delivery of a particular broadcast.

Listing deliveries

To report on recent broadcasts, first call the endpoint to list recent deliveries.

Each delivery listed in this endpoint will have a unique ID, and be associated to a broadcast:

{
"delivery": {
"id": "f64ee790-c01b-48c6-b116-cf55c935e53e",
"broadcast": {
"id": "34199",
"name": "Weekly update"
},
"status": "delivered"
}

Reporting on delivery recipients

To see all those recipients that have seen or responded to at least one content item in the delivery, you can list broadcast delivery receipients, using the unique ID of the delivery.

e.g.

GET /v1/broadcasts/deliveries/f64ee790-c01b-48c6-b116-cf55c935e53e/recipients

For each recipient, the seenAt and respondedAt attributes will either be null or set to a date once that action has occurred.

Reporting on responses to delivery content

You can use the broadcast ID associated with a delivery to fetch detail on the content items attached to a broadcast.

e.g.

GET /v1/broadcasts/34199

May return

{
"broadcast": {
"id": "8173",
"name": "Weekly update",
"created": {
"by": {
"id": "42",
"firstName": "John",
"lastName": "Doe"
},
"at": "2020-11-25T16:54:58+01:00"
}
},
"contents": [
{
"id": "4152",
"type": "examplecontent"
}
]
}

From the content items returned, you can return the recipients for a given content item from the API, using this composition:

GET /v1/broadcasts/deliveries/{deliveryId}/contents/{contentId}/recipients

So, for example,

GET /v1/broadcasts/deliveries/f64ee790-c01b-48c6-b116-cf55c935e53e/contents/4152/recipients
tip

Different content types will return slightly different payloads. You can see examples within the API documentation.

Different content types allow you to filter the recipients returned with different options. For example, rating content items will let you filter by the rating(s) provided by the recipient. See the description of each query parameter to see any restrictions on the content item they can be applied to.