NotifHQAPI reference
174 operations across 9 areas. Generated from openapi/notifhq.v1.json, which a build gate holds bijective with the router — every endpoint on this page is one the API serves, and every endpoint the API serves is on this page.
Base URL and authentication
https://api.notifhq.com
Every request carries Authorization: Bearer <workspace key>. A key is scoped to one workspace and one environment; the scopes it holds decide which of the operations below it may call.
Write operations accept an Idempotency-Key header. Replaying a request with the same key returns the original result rather than sending twice.
alerting
Requires the alerting rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
POST | /v1/observations | Report a condition true or false |
GET | /v1/alerts | The alert board |
GET | /v1/alerts/{id} | Get an alert |
POST | /v1/alerts/{id}/acknowledge | Acknowledge an alert |
POST | /v1/alerts/{id}/close | Close an alert |
GET | /v1/alerts/{id}/escalation | What the escalation would do next |
GET | /v1/conditions | List conditions |
POST | /v1/conditions | Declare a condition |
GET | /v1/conditions/{id} | Get a condition |
PATCH | /v1/conditions/{id} | Amend a condition |
POST | /v1/conditions/{id}/escalations | Add an escalation tier |
DELETE | /v1/conditions/{id}/escalations/{escalation_id} | Remove an escalation tier |
GET | /v1/locations | List places |
POST | /v1/locations | Declare a place |
GET | /v1/locations/{id} | Get a place |
PATCH | /v1/locations/{id} | Amend a place |
GET | /v1/subjects | List tracked things |
POST | /v1/subjects | Declare a tracked thing |
GET | /v1/subjects/{id} | Get a tracked thing |
PATCH | /v1/subjects/{id} | Amend a tracked thing |
GET | /v1/subjects/{id}/positions | Position history |
POST | /v1/subjects/{id}/positions | Report a position |
compliance
Requires the compliance rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
GET | /v1/compliance/profile | Read the compliance profile |
PATCH | /v1/compliance/profile | Update the compliance profile |
GET | /v1/compliance/policies | List compliance policies |
PATCH | /v1/compliance/policies | Update compliance policies |
POST | /v1/compliance/preprocess/test | Run the Preprocessing Rail against a sample |
GET | /v1/compliance/violations | List violations |
POST | /v1/compliance/exports | Generate a hash-sealed compliance export |
POST | /v1/dsar/exports | Request a subject access export |
POST | /v1/dsar/deletions | Request an erasure |
core
Included in every plan.
| Method | Path | What it does |
|---|---|---|
GET | /v1/analytics/summary | Headline metrics |
GET | /v1/analytics/delivery | Delivery metrics |
GET | /v1/analytics/engagement | Engagement metrics |
GET | /v1/analytics/templates | Template performance |
GET | /v1/analytics/preferences | Preference and opt-out trend |
GET | /v1/analytics/tickets | Ticket metrics |
GET | /v1/analytics/invoices | Invoice intake metrics |
GET | /v1/analytics/timeseries | Counts over time |
GET | /v1/analytics/issues | What needs attention |
GET | /v1/apps | List applications |
POST | /v1/apps | Create an application |
GET | /v1/apps/{id} | Retrieve an application |
GET | /v1/api-keys | List API keys |
POST | /v1/api-keys | Create an API key |
DELETE | /v1/api-keys/{id} | Revoke an API key |
POST | /v1/api-keys/{id}/rotate | Replace a key without an outage |
POST | /v1/api-keys/revoke | Revoke every key held by a thing, or at a place |
GET | /v1/billing/subscription | Retrieve the workspace's subscription |
GET | /v1/billing/usage | Metered usage this period |
POST | /v1/billing/portal | Open a billing portal session |
GET | /v1/recipients/{id}/consents | List consents |
POST | /v1/recipients/{id}/consents | Record a consent |
GET | /v1/contracts | List contracts |
POST | /v1/contracts | Create a contract |
GET | /v1/contracts/{id} | Retrieve a contract |
POST | /v1/contracts/{id}/publish | Publish a contract version |
POST | /v1/contracts/{id}/archive | Archive a contract |
GET | /v1/deliveries | List delivery attempts |
GET | /v1/deliveries/{id} | Retrieve a delivery attempt |
GET | /v1/notification-types | List dictionary entries |
POST | /v1/notification-types | Declare a notification type |
GET | /v1/notification-types/{key} | Retrieve a dictionary entry |
PATCH | /v1/notification-types/{key} | Update a dictionary entry |
GET | /v1/domains | List sending domains |
POST | /v1/domains | Add a sending domain |
GET | /v1/domains/{id} | Retrieve a domain |
DELETE | /v1/domains/{id} | Remove a domain |
POST | /v1/domains/{id}/verify | Re-check SPF, DKIM and DMARC |
GET | /v1/jobs | List asynchronous jobs |
GET | /v1/jobs/{id} | Retrieve one job |
GET | /v1/members | List members |
DELETE | /v1/members/{id} | Remove a member |
GET | /v1/members/invitations | List invitations |
POST | /v1/members/invitations | Invite someone to the workspace |
DELETE | /v1/members/invitations/{id} | Revoke an invitation |
GET | /v1/notifications | List notifications |
GET | /v1/notifications/{id} | Retrieve a notification |
POST | /v1/notifications/{id}/cancel | Cancel a queued notification |
GET | /v1/notifications/{id}/deliveries | List the delivery attempts for this notification |
GET | /v1/notifications/{id}/events | List the raw events recorded for this notification |
GET | /v1/notifications/{id}/payload | Retrieve what is retained of the request |
GET | /v1/notifications/{id}/policy | Retrieve the policy decision behind this notification |
POST | /v1/notifications/{id}/resend | Send again as a new notification |
GET | /v1/notifications/{id}/template | Retrieve the template versions that rendered this |
GET | /v1/notifications/{id}/timeline | Retrieve the evidence timeline |
GET | /v1/notifications/{id}/webhooks | List webhook deliveries triggered by this notification |
POST | /v1/notify | Send a notification |
POST | /v1/notify/bulk | Send up to 1,000 notifications |
GET | /v1/packs | List packs |
GET | /v1/packs/{id} | Retrieve a pack |
POST | /v1/packs/{id}/install | Install a pack |
POST | /v1/packs/{id}/upgrade | Upgrade an installed pack |
POST | /v1/packs/{id}/uninstall | Uninstall a pack |
GET | /v1/me/notifications | List the signed-in recipient's own notifications |
POST | /v1/me/notifications/{id}/read | Mark one of the recipient's own notifications read |
GET | /v1/me/preferences | Read the calling recipient's own preferences |
PATCH | /v1/me/preferences | Update the calling recipient's own preferences |
GET | /v1/recipients/{id}/preferences | Read preferences |
PATCH | /v1/recipients/{id}/preferences | Update preferences |
POST | /v1/widget-tokens | Mint a widget token |
GET | /v1/recipients | List recipients |
POST | /v1/recipients | Create or update a recipient |
GET | /v1/recipients/{id} | Retrieve a recipient |
PATCH | /v1/recipients/{id} | Update a recipient |
DELETE | /v1/recipients/{id} | Erase a recipient |
GET | /v1/schemas | List payload schemas |
POST | /v1/schemas | Create a payload schema |
GET | /v1/schemas/{id} | Retrieve a payload schema |
POST | /v1/schemas/{id}/validate | Validate a payload without sending |
GET | /v1/templates | List templates |
POST | /v1/templates | Create a template |
POST | /v1/templates/draft | Draft template copy |
POST | /v1/templates/generate | Draft a template |
GET | /v1/templates/{id} | Retrieve a template |
PATCH | /v1/templates/{id} | Edit a draft template |
POST | /v1/templates/{id}/approve | Approve a template version |
POST | /v1/templates/{id}/archive | Archive a template |
POST | /v1/templates/{id}/preview | Render a preview with sample parameters |
POST | /v1/templates/{id}/publish | Publish an approved template |
POST | /v1/templates/{id}/revise | Open the next draft version of a template |
GET | /v1/webhooks/endpoints | List webhook endpoints |
POST | /v1/webhooks/endpoints | Create a webhook endpoint |
PATCH | /v1/webhooks/endpoints/{id} | Update a webhook endpoint |
DELETE | /v1/webhooks/endpoints/{id} | Delete a webhook endpoint |
GET | /v1/webhooks/deliveries | List webhook deliveries |
POST | /v1/webhooks/deliveries/{id}/replay | Replay a webhook delivery |
GET | /v1/workspaces | List workspaces |
POST | /v1/workspaces | Create a workspace |
GET | /v1/workspaces/{id} | Retrieve a workspace |
PATCH | /v1/workspaces/{id} | Update a workspace |
GET | /v1/workspaces/{id}/signature | Retrieve the workspace's sending signature |
PUT | /v1/workspaces/{id}/signature | Set the workspace's sending signature |
GET | /v1/workspaces/{id}/rails | List every rail and this workspace's standing against it |
POST | /v1/workspaces/{id}/rails/{rail} | Install a rail |
DELETE | /v1/workspaces/{id}/rails/{rail} | Uninstall a rail |
document intake
Requires the document_intake rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
GET | /v1/documents | List documents |
POST | /v1/documents | Upload a document |
GET | /v1/documents/{id} | Retrieve a document |
POST | /v1/documents/{id}/process | Run the Document Rail — not available |
POST | /v1/documents/{id}/review | Record a human review |
inbound email
Requires the inbound_email rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
POST | /v1/inbound/email | Deliver an inbound email to the rail |
GET | /v1/messages | List messages across threads |
GET | /v1/threads | List threads |
GET | /v1/threads/{id} | Retrieve a thread and its messages |
invoice intake
Requires the invoice_intake rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
GET | /v1/invoices | List invoices |
POST | /v1/invoices | Submit an invoice document |
GET | /v1/invoices/{id} | Retrieve a canonical invoice |
POST | /v1/invoices/{id}/approve | Approve an invoice |
POST | /v1/invoices/{id}/reject | Reject an invoice |
notification
Requires the notification rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
GET | /v1/evidence-packs | List a workspace's evidence packs, in chain order |
GET | /v1/evidence-packs/verify | Walk the workspace's pack chain and report where it breaks |
GET | /v1/evidence-packs/{id} | Retrieve one sealed evidence pack |
GET | /v1/journeys | List the journeys this workspace can run |
POST | /v1/journeys/{id}/runs | Start a journey for one subject and one recipient |
GET | /v1/journey-runs | List journey runs |
GET | /v1/journey-runs/{id} | Retrieve one journey run |
POST | /v1/journey-runs/{id}/events | Tell a run that something happened |
POST | /v1/otp/challenges | Issue a one-time passcode |
POST | /v1/otp/challenges/{id}/verify | Check a passcode against a challenge |
search
Requires the search rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
POST | /v1/search | Search across canonical objects |
GET | /v1/saved-searches | List saved searches |
POST | /v1/saved-searches | Save a search |
DELETE | /v1/saved-searches/{id} | Delete a saved search |
team inbox
Requires the team_inbox rail. Absent from the document served to a workspace without it.
| Method | Path | What it does |
|---|---|---|
GET | /v1/tickets | List tickets |
POST | /v1/tickets | Create a ticket |
GET | /v1/tickets/queues | List the inbox queues with their live counts |
GET | /v1/tickets/{id} | Retrieve a ticket with its communication evidence |
PATCH | /v1/tickets/{id} | Update a ticket |
POST | /v1/tickets/{id}/assign | Assign a ticket |
POST | /v1/tickets/{id}/note | Add an internal note |
POST | /v1/tickets/{id}/reopen | Reopen a ticket |
POST | /v1/tickets/{id}/reply | Reply on a ticket |
POST | /v1/tickets/{id}/resolve | Resolve a ticket |
The full contract
openapi.json is the document this page is generated from. Point a client generator at it rather than transcribing anything above.