Skip to main content
Use the User Preferences API to manage notification preferences from your backend. This tutorial covers reading and updating preferences programmatically; for setting up subscription topics and surfacing preferences to users, see:

​
Prerequisites

​
Required Parameters

Every preference update needs two identifiers:
  • user_id - The recipient’s unique ID (same ID used in send requests)
  • topic_id - The subscription topic ID, found in the Preferences Editor

​
Read a User’s Preferences

Fetch all preferences for a user to see their current opt-in/out status across all topics: 
curl -X GET https://api.courier.com/users/{user_id}/preferences \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"

​
Update a Topic Preference

Set a user’s opt-in status for a specific topic. The topic object requires a status field with one of these values:
StatusBehavior
OPTED_INUser receives notifications for this topic
OPTED_OUTUser does not receive notifications for this topic
REQUIREDUser cannot opt out (use for critical notifications like security alerts)
curl -X PUT https://api.courier.com/users/{user_id}/preferences/{topic_id} \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": {
      "status": "OPTED_IN"
    }
  }'

​
Custom Routing (Enterprise)

Enterprise customers can set channel delivery preferences per topic. For example, if a notification template has email, SMS, and push channels, you can let a user receive only email: 
curl -X PUT https://api.courier.com/users/{user_id}/preferences/{topic_id} \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": {
      "status": "OPTED_IN",
      "has_custom_routing": true,
      "custom_routing": ["email"]
    }
  }'
Custom routing requires an Enterprise plan. The notification template must have multiple delivery channels configured and be linked to a subscription topic.

​
Tenant-Scoped Preferences

If your app uses tenants, pass a tenant_id to read or write preferences scoped to a specific tenant: 
curl -X GET "https://api.courier.com/users/{user_id}/preferences?tenant_id=tenant_abc" \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"

​
What’s Next

Set Up Hosted Preferences

Deploy a hosted preference page for your users

Embed Preferences in React

Build an in-app preference center with React components

Preferences Editor

Configure topics, sections, and channel options

User Preferences API

Full API reference