Overview

The Create Alias endpoint allows you to create or update an alias for a user using a known alias.

How to Use this API

This endpoint performs an upsert—if the user already has an alias with the specified alias label, it gets updated; otherwise, a new alias will be created.

The request body must include an identity object containing one or more aliases to be created or updated.

The OneSignal ID is read-only and used only for fetching.

Aliases are updated immediately upon request.

Examples

Assign a user a new Alias

curl -X "PATCH" "https://api.onesignal.com/apps/<APP_ID>/users/by/<ALIAS_LABEL>/<ALIAS_ID>/identity" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "identity": {
    "<NEW_ALIAS_LABEL>": "<NEW_ID>"
  }
}'

Path Parameters

alias_label

Description

The name of the alias to use to fetch a user. All users include a special OneSignal ID alias named onesignal_id.

Guidance

• We recommend fetching users via your identifier using the External ID alias: external_id.
• Refer to our guide on Aliases & External ID for further details.

alias_id

Description

The specific identifier for a given Alias to identify the user.

Guidance

• Refer to our guide on Aliases & External ID for further details.

Quick Start API Guide