Create notification

POST /v1/notifications

Create notification

cURL

curl --request POST \
  --url https://staging.api.us.aptlydone.com/v1/notifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "templateKey": "DELEGATION_ISSUED",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "550e8400-e29b-41d4-a716-446655440000",
  "entityType": "delegation",
  "entityId": "9da9a193-7ce8-4540-8020-d22ad2333960",
  "placeholders": {
    "delegation_id": "ABC123",
    "user_email": "[e-mail]"
  },
  "actionUrl": "https://example.com/delegations/123456",
  "payload": {
    "delegationName": "Q3 Budget Review",
    "priority": "high"
  }
}
'

201

{
  "statusCode": 200,
  "timestamp": "2026-01-12T09:08:08.140Z",
  "message": "Success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "tenantId": "123e4567-e89b-12d3-a456-426614174000",
    "templateKey": "DELEGATION_ISSUED",
    "category": "Delegations",
    "title": "Delegation Issued",
    "message": "Delegation ABC123 was issued to you. Click to review.",
    "isActionable": true,
    "status": "UNREAD",
    "createdAt": "2023-01-01T12:00:00Z",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "entityType": "delegation",
    "entityId": "123456",
    "relativeTime": "2 hours ago",
    "readAt": "2023-01-02T14:30:00Z",
    "actionUrl": "https://example.com/delegations/123456",
    "payload": {
      "assignedBy": "John Doe",
      "priority": "high"
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

templateKey · string · required

The template key for the notification

Example:

"DELEGATION_ISSUED"

userId · string<uuid> · required

The user ID who should receive this notification

Example:

"550e8400-e29b-41d4-a716-446655440000"

tenantId · string<uuid> · required

The tenant ID of the user who should receive this notification

Example:

"550e8400-e29b-41d4-a716-446655440000"

entityType · string · required

The type of entity this notification relates to

Example:

"delegation"

entityId · string · required

The ID of the entity this notification relates to

Example:

"9da9a193-7ce8-4540-8020-d22ad2333960"

placeholders · object · required

Template placeholders to populate in the message

Example:

{
  "delegation_id": "ABC123",
  "user_email": "[e-mail]"
}

actionUrl · string

Optional URL for action button on the notification

Example:

"https://example.com/delegations/123456"

payload · object

Optional payload with additional data for the notification

Example:

{
  "delegationName": "Q3 Budget Review",
  "priority": "high"
}

Response

201 - application/json

The notification has been successfully created

statusCode · number · required

HTTP Status code

Example:

200

timestamp · string · required

Timestamp of the response

Example:

"2026-01-12T09:08:08.140Z"

message · string · required

Response message

Example:

"Success"

data · object · required

Response data

Show child attributes