notiflowsDocs
Users

Create or update user

Create a new user or update an existing user by external ID (upsert operation).

  • If the user doesn't exist, they will be created with the provided attributes.
  • If the user exists, their attributes will be updated (merge behavior).
  • custom_fields are deep-merged with existing values.

Returns:

  • 201 Created when a new user is created
  • 200 OK when an existing user is updated
PUT
/users/{id}

Authorization

ApiKeyAuth SecretKeyAuth
x-notiflows-api-key<token>

Your project's public API key. Found in Project Settings. Starts with pk_.

In: header

x-notiflows-secret-key<token>

Your project's secret key. Found in Project Settings. Starts with sk_. Keep this secret!

In: header

Path Parameters

id*string

User external ID

Request Body

application/json

User attributes

avatar?string

URL to user's avatar image (must start with http:// or https://)

Formaturi
channel_settings?array<>

Initial channel settings (e.g., device tokens for push)

custom_fields?object

Custom attributes. Deep-merged with existing values on update.

email?string

User's email address

Formatemail
external_id*string

Your system's unique identifier for this user. Required for creating new users.

first_name?string

User's first name

last_name?string

User's last name

locale?string

BCP 47 locale code (e.g., en-US, es-ES, fr-FR)

phone?string

User's phone number in E.164 format

preferences?

Initial notification preferences (optional)

timezone?string

IANA timezone (e.g., America/New_York, Europe/London)

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://api.notiflows.com/admin/users/user_12345" \  -H "Content-Type: application/json" \  -d '{    "custom_fields": {      "company": "Acme Inc",      "plan": "premium"    },    "email": "jane.doe@example.com",    "external_id": "user_12345",    "first_name": "Jane",    "last_name": "Doe",    "locale": "en-US",    "timezone": "America/New_York"  }'
{
  "avatar": "https://example.com/avatars/jane.jpg",
  "created_at": "2024-01-15T10:30:00Z",
  "custom_fields": {
    "company": "Acme Inc",
    "plan": "premium"
  },
  "email": "jane.doe@example.com",
  "external_id": "user_12345",
  "first_name": "Jane",
  "id": "01HQXYZ123456789ABCDEFGHIJ",
  "last_name": "Doe",
  "locale": "en-US",
  "phone": "+15551234567",
  "timezone": "America/New_York",
  "updated_at": "2024-01-20T14:45:00Z"
}
{
  "avatar": "https://example.com/avatars/jane.jpg",
  "created_at": "2024-01-15T10:30:00Z",
  "custom_fields": {
    "company": "Acme Inc",
    "plan": "premium"
  },
  "email": "jane.doe@example.com",
  "external_id": "user_12345",
  "first_name": "Jane",
  "id": "01HQXYZ123456789ABCDEFGHIJ",
  "last_name": "Doe",
  "locale": "en-US",
  "phone": "+15551234567",
  "timezone": "America/New_York",
  "updated_at": "2024-01-20T14:45:00Z"
}
{
  "error": {
    "code": "not_found",
    "details": {
      "allowed_statuses": [
        "string"
      ],
      "allowed_transitions": [
        "string"
      ],
      "auth": "api_key",
      "current_status": "string",
      "fields": [
        {
          "field": "email",
          "message": "can't be blank",
          "reason": "required"
        }
      ],
      "id": "string",
      "idempotency_key": "string",
      "limit": 0,
      "param": "string",
      "reason": "string",
      "required_scope": "string",
      "resource": "string",
      "retry_after": 0,
      "window": "string"
    },
    "message": "User not found",
    "request_id": "req_abc123",
    "status": 404,
    "type": "https://docs.notiflows.com/errors/not_found"
  }
}
{
  "error": {
    "code": "not_found",
    "details": {
      "allowed_statuses": [
        "string"
      ],
      "allowed_transitions": [
        "string"
      ],
      "auth": "api_key",
      "current_status": "string",
      "fields": [
        {
          "field": "email",
          "message": "can't be blank",
          "reason": "required"
        }
      ],
      "id": "string",
      "idempotency_key": "string",
      "limit": 0,
      "param": "string",
      "reason": "string",
      "required_scope": "string",
      "resource": "string",
      "retry_after": 0,
      "window": "string"
    },
    "message": "User not found",
    "request_id": "req_abc123",
    "status": 404,
    "type": "https://docs.notiflows.com/errors/not_found"
  }
}
{
  "error": {
    "code": "not_found",
    "details": {
      "allowed_statuses": [
        "string"
      ],
      "allowed_transitions": [
        "string"
      ],
      "auth": "api_key",
      "current_status": "string",
      "fields": [
        {
          "field": "email",
          "message": "can't be blank",
          "reason": "required"
        }
      ],
      "id": "string",
      "idempotency_key": "string",
      "limit": 0,
      "param": "string",
      "reason": "string",
      "required_scope": "string",
      "resource": "string",
      "retry_after": 0,
      "window": "string"
    },
    "message": "User not found",
    "request_id": "req_abc123",
    "status": 404,
    "type": "https://docs.notiflows.com/errors/not_found"
  }
}
{
  "error": {
    "code": "not_found",
    "details": {
      "allowed_statuses": [
        "string"
      ],
      "allowed_transitions": [
        "string"
      ],
      "auth": "api_key",
      "current_status": "string",
      "fields": [
        {
          "field": "email",
          "message": "can't be blank",
          "reason": "required"
        }
      ],
      "id": "string",
      "idempotency_key": "string",
      "limit": 0,
      "param": "string",
      "reason": "string",
      "required_scope": "string",
      "resource": "string",
      "retry_after": 0,
      "window": "string"
    },
    "message": "User not found",
    "request_id": "req_abc123",
    "status": 404,
    "type": "https://docs.notiflows.com/errors/not_found"
  }
}
{
  "error": {
    "code": "not_found",
    "details": {
      "allowed_statuses": [
        "string"
      ],
      "allowed_transitions": [
        "string"
      ],
      "auth": "api_key",
      "current_status": "string",
      "fields": [
        {
          "field": "email",
          "message": "can't be blank",
          "reason": "required"
        }
      ],
      "id": "string",
      "idempotency_key": "string",
      "limit": 0,
      "param": "string",
      "reason": "string",
      "required_scope": "string",
      "resource": "string",
      "retry_after": 0,
      "window": "string"
    },
    "message": "User not found",
    "request_id": "req_abc123",
    "status": 404,
    "type": "https://docs.notiflows.com/errors/not_found"
  }
}

Update user preferences PUT

Previous Page

Overview

Client-side API for managing user-specific feed entries, notification states, and preferences