Users API

Connect platform and advertiser user accounts.

Register a platform user

POST

https://api.onwardinc.net

/v1/users/register

X-API-Key (header)

+X-API-Secret (header)

Publisher

Creates an Onward user for the calling platform, or returns the existing user when the platform user ID is already registered. See the Platform integration guide for the surrounding workflow.

Register a platform user › Request Body

Payload of POST /v1/users/register.

platform_user_id

string · minLength: 1 · maxLength: 255 · required

Unique user identifier from your platform

Example: user_12345

country_code

null | string · minLength: 2 · maxLength: 2

ISO 3166-1 alpha-2 country code of the user.

Example: US

object

Additional user attributes supplied by the platform.

Example: {"username":"player1","avatar_url":"https://platform.example/avatars/player1.png"}

Register a platform user › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required

Result of registering or finding a platform user in Onward.

Example: {"user_id":"6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31","platform_user_id":"user_12345","created_at":"2026-08-20T12:30:00.000Z","already_exists":false}

POST/v1/users/register

curl https://api.onwardinc.net/v1/users/register \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>' \
  --data '{
  "platform_user_id": "user_12345",
  "country_code": "US",
  "user_metadata": {
    "username": "player1",
    "avatar_url": "https://platform.example/avatars/player1.png"
  }
}'

Example Request Body

{
  "platform_user_id": "user_12345",
  "country_code": "US",
  "user_metadata": {
    "username": "player1",
    "avatar_url": "https://platform.example/avatars/player1.png"
  }
}

json

Example Responses

{
  "success": true,
  "data": {
    "user_id": "6f2f6f4e-4a1e-4f6f-9a2b-2c9d1f0b7a31",
    "platform_user_id": "user_12345",
    "created_at": "2026-08-20T12:30:00.000Z",
    "already_exists": false
  }
}