Notify API reference

Notify API · Recipients

put/v1/workspaces/{workspace_id}/recipients/{external_id}Auth

Create or update a recipient

Creates the recipient with this external id, or updates it. Fields you leave out keep their stored value; `null` clears one; `properties` is replaced whole. Calling it again with the same body leaves the same recipient, so a retry is safe without an `Idempotency-Key` (the route does not take one).

Path parameters

workspace_id*string · uuid

Id of the workspace.

external_id*string

Your user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.

Request body

auth_user_idstring · uuid

Link to an Auth end user (its user id) in a ProductCraft Auth app. At most one recipient per end user in a workspace. The id is not looked up: link the id your Auth app gave you.

emailstring · email

Email address for the email channel.

Example: "ada@example.com"

phonestring

Phone number in E.164 form (`+351912345678`), kept for the SMS channel planned after v1.

Example: "+351912345678"

namestring

Display name.

Example: "Ada Lovelace"

localestring

BCP 47 language tag; templates fall back from `pt-PT` to `pt` to the type default.

Example: "pt-PT"

timezonestring

IANA time zone, used for quiet hours.

Example: "Europe/Lisbon"

quiet_hoursobject

Hours when push and web push are held until the window ends (the inbox is never held).

propertiesobject

Your own fields, returned exactly as sent (keys are not re-cased). At most 4 KB as JSON. Replaced whole when present.

Example: {"plan":"pro","team_id":"team_42"}

Response · 200 Updated.

id*string · uuid

Notify's id for the recipient.

external_id*string

Your user id for the recipient (the path key).

Example: "user_123"

auth_user_id*string · uuid

The linked Auth end user.

email*string · email

Email address.

phone*string

Phone number (E.164).

name*string

Display name.

locale*string

BCP 47 language tag.

timezone*string

IANA time zone.

quiet_hours*object

Quiet window.

properties*object

Your own fields, exactly as sent.

email_invalid_at*string · date-time

When the address hard-bounced; email to it stops until the address changes.

email_complained_at*string · date-time

When the recipient marked an email as spam; email to it stops until the address changes.

last_seen_at*string · date-time

Last client (recipient-token) activity.

unsubscribed_all*boolean

Opted out of every non-critical notification.

preferencesarray

Preference cells; only on `GET /recipients?include=preferences`.

created_at*string · date-time

Created.

updated_at*string · date-time

Last change.

Example

Request

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

{
  "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"
  }
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "external_id": "user_123",
  "auth_user_id": "00000000-0000-0000-0000-000000000000",
  "email": "user@example.com",
  "phone": "string",
  "name": "string",
  "locale": "string",
  "timezone": "string",
  "quiet_hours": {},
  "properties": {},
  "email_invalid_at": "2026-01-01T00:00:00.000Z",
  "email_complained_at": "2026-01-01T00:00:00.000Z",
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "unsubscribed_all": false,
  "preferences": [
    {
      "scope": {},
      "key": "string",
      "channel": {},
      "enabled": false
    }
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}