Notify API reference

Notify API · Recipients

post/v1/workspaces/{workspace_id}/recipients/bulkAuth

Create or update up to 1,000 recipients

Upserts each row like `PUT /recipients/{external_id}`, with its devices. Rows are independent: a bad row is reported in `data` with `status: error` and its code, and never fails the rest. Rows are written in order of external id, in transactions of at most 200. At most 20 calls per minute per workspace (20,000 recipients) and 4 MB per request. Each row may carry its complete `preferences` set (as `PUT …/preferences`); a bad cell fails only its row. Send an `Idempotency-Key` so a retried import replays its first result.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original result for 24 h.

Request body

recipients*array

Up to 1,000 recipients. Each row is validated and written on its own: a bad row is reported in `data` and never fails the others. A row repeating an earlier `external_id` in the same call is refused.

Response · 200 One result per row.

data*array

One result per row, in request order.

created*number

Rows created.

updated*number

Rows updated.

failed*number

Rows refused.

Example

Request

POST https://api.notify.productcraft.co/v1/workspaces/{workspace_id}/recipients/bulk
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "recipients": [
    {
      "auth_user_id": "00000000-0000-0000-0000-000000000000",
      "email": "ada@example.com",
      "phone": "+351912345678",
      "name": "Ada Lovelace",
      "locale": "pt-PT",
      "timezone": "Europe/Lisbon",
      "quiet_hours": {},
      "properties": {
        "plan": "pro",
        "team_id": "team_42"
      },
      "external_id": "user_123",
      "devices": [
        {
          "channel": {},
          "token": "740f4707bebcf74f9b7c25d48e3358945f6aa01da5ddb387462c7eaf61bb78ad",
          "subscription": {},
          "app_id": "com.example.app",
          "environment": {},
          "platform": {},
          "timezone": "Europe/Lisbon"
        }
      ],
      "preferences": [
        {
          "scope": {},
          "key": "billing",
          "channel": {},
          "enabled": false
        }
      ]
    }
  ]
}

Response

{
  "data": [
    {
      "external_id": "user_123",
      "status": {},
      "error": {}
    }
  ],
  "created": 0,
  "updated": 0,
  "failed": 0
}