/v1/workspaces/{workspace_id}/recipients/{external_id}AuthCreate 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 · uuidId of the workspace.
external_id*stringYour user id for the recipient (URL-encoded): 1-255 of `A-Z a-z 0-9 . _ : @ | -`.
Request body
auth_user_idstring · uuidLink 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 · emailEmail address for the email channel.
Example: "ada@example.com"
phonestringPhone number in E.164 form (`+351912345678`), kept for the SMS channel planned after v1.
Example: "+351912345678"
namestringDisplay name.
Example: "Ada Lovelace"
localestringBCP 47 language tag; templates fall back from `pt-PT` to `pt` to the type default.
Example: "pt-PT"
timezonestringIANA time zone, used for quiet hours.
Example: "Europe/Lisbon"
quiet_hoursobjectHours when push and web push are held until the window ends (the inbox is never held).
propertiesobjectYour 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 · uuidNotify's id for the recipient.
external_id*stringYour user id for the recipient (the path key).
Example: "user_123"
auth_user_id*string · uuidThe linked Auth end user.
email*string · emailEmail address.
phone*stringPhone number (E.164).
name*stringDisplay name.
locale*stringBCP 47 language tag.
timezone*stringIANA time zone.
quiet_hours*objectQuiet window.
properties*objectYour own fields, exactly as sent.
email_invalid_at*string · date-timeWhen the address hard-bounced; email to it stops until the address changes.
email_complained_at*string · date-timeWhen the recipient marked an email as spam; email to it stops until the address changes.
last_seen_at*string · date-timeLast client (recipient-token) activity.
unsubscribed_all*booleanOpted out of every non-critical notification.
preferencesarrayPreference cells; only on `GET /recipients?include=preferences`.
created_at*string · date-timeCreated.
updated_at*string · date-timeLast 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"
}