Docs / API and agents
Messages and notifications API
Application messages between supplier, applicant and reference, the inbox, and the notification bell.
Messages#
| Method and path | Who | What |
|---|---|---|
POST /applications/:id/messages | applicant who owns it, or supplier with messages.view and messages.send | post a message. Body: body (max 4000), visibility (INTERNAL, APPLICANT, REFERENCE), optional documentIds (max 10) |
POST /applications/:id/messages/read | applicant, reference, or supplier with messages.view | mark the thread read |
GET /messages/inbox | supplier with messages.view | inbox with unread count; thread selects one thread |
POST /reference/:token/messages, GET /reference/:token/messages | public, link token | a reference writes to and reads the supplier thread |
Applicants may only post APPLICANT messages. Attachments must be the poster's own active, unattached uploads on the same application; otherwise 409. Send an Idempotency-Key to make retries safe (a reused key is a 409).
| Status | When |
|---|---|
| 400 | invalid body, empty message with no attachment, bad request key |
| 403 | wrong role or missing permission |
| 404 | unknown application or thread |
| 410 | reference link expired |
| 413 | reference body above 16 KB |
| 429 | 30 posts per user per minute; 20 messages per link and 50 per IP per hour for references; reads 60 per minute |
| 503 | inbox temporarily unavailable |
Posting a message (supplier, applicant or reference) saves it, its activity entry and its email notices (outbox rows plus the sending job) in one transaction. The notice emails are sent a few seconds after the response by a queue job, never inside the request.
Notifications#
All need a session and answer no-store.
| Method and path | What |
|---|---|
GET /notifications | the bell: { notifications, lastReadAt, unreadCount }, scoped to the caller's organization |
GET /notifications/page?shell=app | 30 days, up to 100 items; the vendor or customer side comes from the role, never the caller; any other shell value is 400 |
POST /notifications/mark-read | body { itemId, read? }; an empty body does nothing |
POST /notifications/mark-all-read | mark everything read |