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, kmskey or entitylist.

  • 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:

    • message

    • submission_created

    • submission_edited

    • submission_deleted

    • submission_reviewed

    • form_updated

    • kmskey_rotated

    • export_created

    • export_downloaded

    • entitylist_imported

    • entitylist_deleted

    • profile_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

xform, project, entitylist, kmskey

Users with permission to view the target

Personal user account

The account itself

Organization user account

The account itself, and the organization’s owners and managers

Unavailable targets

A target is unavailable when it is deleted, belongs to a deleted project, is an inactive account, or an inactive personal or organization account owns it. A KMS key is unavailable unless an active account owns it. Rotating, expiring or disabling a key does not hide its events.

Errors

  • 400 - A list or stats request is missing target_type or target_id, or target_type is 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 return 404 for 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=1

Response

[
    {
        "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:

  1. The maximum number of items that can be requested in a page via the page_size query param is 10,000

  2. Information 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

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 is null when 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&timestamp__lte=2024-06-20T00:00

Where:

  • target_type=xform - The target object type is xform

  • target_id=1 - The target object unique id, in this case the xform ID

  • verb=submission_edited - The action occured on the xform, in this case a submission in the xform has been edited

  • timestamp__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