Messaging¶
The messaging API provides read-only access to events recorded by internal
application code. Clients cannot create, edit or delete events. Authenticated
POST, PUT, PATCH and DELETE requests return 405 Method Not Allowed.
Events have the following target and action fields:
target_type- The type of the target object:xform,project,user,kmskeyorentitylist.target_id- The unique identifier of the target object.verb- The action recorded on the target. The following verbs can appear in GET responses and can be used to filter events. None can be posted through the API:messagesubmission_createdsubmission_editedsubmission_deletedsubmission_reviewedform_updatedkmskey_rotatedexport_createdexport_downloadedentitylist_importedentitylist_deletedprofile_updated
Targets and feeds¶
Every event belongs to one target, identified by target_type and
target_id. The events for a target are its feed.
A user target is an account. Organizations are accounts too. To read an
organization’s feed, pass target_type=user and the organization’s account
ID, rather than its organization profile ID.
Permissions¶
All requests require authentication. Read permissions apply to lists, grouped counts, individual event details and messaging statistics, including empty feeds.
Target |
Who can read its feed |
|---|---|
|
Users with permission to view the target |
Personal |
The account itself |
Organization |
The account itself, and the organization’s owners and managers |
Errors¶
400- A list or stats request is missingtarget_typeortarget_id, ortarget_typeis not supported.403- The target exists but you cannot access it. This applies even when the target has no events.404- The target ID is malformed, does not exist, or identifies an unavailable target. Event detail reads also return404for missing events or events whose targets are unavailable.405- An authenticated client attempts to create, edit or delete an event.
Caching¶
Responses are private, and browsers and shared caches do not store them. The server caches list responses, including grouped counts, for up to ten minutes. Lists may omit new events or retain internally deleted events for that long. The API still checks permissions and target availability on every request. The server does not cache event detail or messaging stats responses.
GET All event messages that have been sent for a form¶
Lists the events messages that have been sent for a specific form.
GET /api/v1/messaging?target_type={type}&target_id={form_id}Example¶
curl -X GET https://api.ona.io/api/v1/messaging?target_type=xform&target_id=1Response¶
[ { "id": 16485370, "verb": "message", "message": "Hey there", "user": "bob", "timestamp": "2021-02-26T03:32:57.799647-05:00" }, { "id": 16484965, "verb": "submission_deleted", "message": "{\"id\": [\"71470149\"]}", "user": "bob", "timestamp": "2021-02-26T03:28:19.512875-05:00" }, { "id": 12778522, "verb": "submission_edited", "message": "{\"id\": [71472574]}", "user": "bob", "timestamp": "2020-12-14T02:57:23.454169-05:00" }, { "id": 12778520, "verb": "submission_created", "message": "{\"id\": [71472574]}", "user": "bob", "timestamp": "2020-12-14T02:57:23.264655-05:00" } ]
GET List of events that have occured on a form for a specific verb¶
Lists out all messages sent for a specific verb.
GET /api/v1/messaging?target_type={type}&target_id={form_id}&verb={message}
Example¶
curl -X GET https://api.ona.io/api/v1/messaging?target_type=xform&target_id=1&verb=message
Response¶
[
{
"id": 16485370,
"verb": "message",
"message": "Hey there",
"user": "bob",
"timestamp": "2021-02-26T03:32:57.799647-05:00"
},
{
"id": 16485370,
"verb": "message",
"message": "lorem ipsum",
"user": "bob",
"timestamp": "2021-02-26T03:49:57.799647-05:00"
}
]
GET Paginate events messages for a specific verb¶
Lists out event messages using page number and the number of items per page. Use the page parameter to specify page number and page_size parameter is used to set the custom page size.
page- Integer representing the page.page_size- Integer representing the number of records that should be returned in a single page.
There are a few important facts to note about retrieving paginated data:
The maximum number of items that can be requested in a page via the
page_sizequery param is 10,000Information regrading transversal of the paginated responses can be found in the Link header returned in the response. Note: Some relational links may not be present depending on the page accessed i.e the ``first`` relational page link won’t be present on the first page response
Example¶
curl -X GET https://api.ona.io/api/v1/messaging?target_type=xform&target_id=1&verb=message&page=1&page_size=1
Sample response with link header¶
Response Header:
...
Link: <https://api.ona.io/api/v1/messaging?target_type=xform&target_id=1&verb=message&page=2&page_size=1>; rel="next", <https://api.ona.io/api/v1/messaging?target_type=xform&target_id=1&verb=message&page=3&page_size=1>; rel="last"
Response:
[
{
"id": 16485370,
"verb": "message",
"message": "Hey there",
"user": "bob",
"timestamp": "2021-02-26T03:32:57.799647-05:00"
}
]
GET Grouped activity counts¶
Passing one or more group_by parameters returns activity counts instead of
individual event messages, grouped by the requested dimension(s). The supported
dimensions are user, verb and a time bucket (one of hour, day,
week, month or year); repeat the parameter to combine them. At most
one time bucket may be combined per request. The same target_type,
target_id and optional user filters apply. The results are paginated and
ordered by most recent activity first. Any other group_by value, or more
than one time bucket, returns an HTTP 400 response.
group_by=verb- Counts per verb, aggregated across users.group_by=user- Counts per user, aggregated across verbs.group_by=user&group_by=verb- Counts per(user, verb).group_by=day- Counts per UTC day, aggregated across users and verbs.group_by=day&group_by=user&group_by=verb- Counts per(day, user, verb).
Each row always contains:
count- The number of events in the group.earliest_timestamp- The timestamp of the oldest event in the group.latest_timestamp- The timestamp of the most recent event in the group.
The requested dimensions are also included in each row:
period_start- The UTC start of the time bucket. Only present when a time bucket was requested. Time bucket boundaries are computed in UTC.user- The username of the acting user. This isnullwhen the actor id no longer resolves to a user.verb- The action that occurred on the target.
All timestamps in grouped responses are rendered in UTC. Because a time bucket
also reports earliest_timestamp and latest_timestamp, a client can
render an event range (e.g. “15 submissions from 09:00 to 10:00”) by merging
adjacent buckets; the endpoint does not collapse bursts on the server.
GET /api/v1/messaging?target_type={type}&target_id={form_id}&group_by=day&group_by=user&group_by=verb
Example¶
curl -X GET https://api.ona.io/api/v1/messaging?target_type=xform&target_id=1&group_by=day&group_by=user&group_by=verb
Response¶
[
{
"period_start": "2026-03-15T00:00:00Z",
"user": "bob",
"verb": "submission_created",
"count": 14,
"earliest_timestamp": "2026-03-15T06:10:00Z",
"latest_timestamp": "2026-03-15T18:22:57Z"
},
{
"period_start": "2026-03-14T00:00:00Z",
"user": "bob",
"verb": "submission_edited",
"count": 2,
"earliest_timestamp": "2026-03-14T02:57:23Z",
"latest_timestamp": "2026-03-14T09:41:05Z"
}
]
Query events of a target using timestamp¶
Filter messages using the timestamp field. To filter messages by their timestamp, the timestamp parameter is appended to the messaging endpoint URL. This allows for precise retrieval of events that occurred within specific time frames or ranges.
Example¶
curl -X GET https://api.ona.io/api/v1/messaging?target_type=xform&target_id=1&verb=submission_edited×tamp__lte=2024-06-20T00:00
Where:
target_type=xform- The target object type is xformtarget_id=1- The target object unique id, in this case the xform IDverb=submission_edited- The action occured on the xform, in this case a submission in the xform has been editedtimestamp__lte=2024-06-20T00:00- Filters the events/messages to include only those that occurred on or before June 20, 2024, at 00:00 (midnight).
Timestamp field Filters Options
Filter |
Description |
|---|---|
timestamp__year |
Exact year e.g. 2024 |
timestamp__year__lt |
Year Less than |
timestamp__year__lte |
Year Less than or Equal to |
timestamp__year__gt |
Year Greater than |
timestamp__year__gte |
Year Greater than or Equal to |
timestamp__month |
Exact month e.g. 10 |
timestamp__month__lt |
Month Less than |
timestamp__month__lte |
Month Less than or Equal to |
timestamp__month__gt |
Month Greater than |
timestamp__month__gte |
Month Greater than or Equal to |
timestamp__day |
Exact day e.g. 12 |
timestamp__day__lt |
Day Less than |
timestamp__day__lte |
Day Less than or Equal to |
timestamp__day__gt |
Day Greater than |
timestamp__day__gte |
Day Greater than or Equal to |