Register device

Register a device token for push notifications. The workspace is resolved from the API key, and the person is identified by the external ID in the path — the same userId you send to /identify and /track. Neither belongs in the request body.

An unknown external ID does not 404: the person is created on the spot and the device is registered against them, with person_created: true in the response. Do not 404-guard this call for new users — a genuine miss cannot happen. Like POST /track, seeing person_created on an identifier you believed established points at a typo, not a new user.

Re-posting the same token updates the existing device record rather than creating a duplicate; use this to refresh app_version or os_version.

Accepts devices:register or devices:write. Use devices:register for keys embedded in a mobile app.

curl -X POST "https://api.flameup.ai/api/v1/people/example_string/devices" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "token": "example_string",
  "platform": "ios",
  "device_name": "John Doe",
  "device_model": "example_string",
  "os_version": "example_string",
  "app_version": "example_string"
}'

import requests
import json

url = "https://api.flameup.ai/api/v1/people/example_string/devices"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
  "token": "example_string",
  "platform": "ios",
  "device_name": "John Doe",
  "device_model": "example_string",
  "os_version": "example_string",
  "app_version": "example_string"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://api.flameup.ai/api/v1/people/example_string/devices", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
},
  body: JSON.stringify({
  "token": "example_string",
  "platform": "ios",
  "device_name": "John Doe",
  "device_model": "example_string",
  "os_version": "example_string",
  "app_version": "example_string"
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "token": "example_string",
  "platform": "ios",
  "device_name": "John Doe",
  "device_model": "example_string",
  "os_version": "example_string",
  "app_version": "example_string"
}`)

    req, err := http.NewRequest("POST", "https://api.flameup.ai/api/v1/people/example_string/devices", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://api.flameup.ai/api/v1/people/example_string/devices')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
  "token": "example_string",
  "platform": "ios",
  "device_name": "John Doe",
  "device_model": "example_string",
  "os_version": "example_string",
  "app_version": "example_string"
}'

response = http.request(request)
puts response.body

{
  "success": true,
  "device_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "example_string",
  "person_created": true
}

{
  "error": "Bad Request",
  "message": "The request contains invalid parameters or malformed data",
  "code": 400,
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

POST

/people/{externalId}/devices

POST

Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token

Bearer Tokenstring

Required

Your Flameup API key (passed as Bearer token)

path

externalIdstring

Required

Your own user id — the same userId you send to /identify and /track. This is NOT the Flameup person UUID. Every API-key route keys on this identifier; the Flameup UUID is used only by the dashboard's workspace-scoped routes.

Content-Typestring

Required

The media type of the request body

Options: application/json

tokenstring

Required

The FCM/APNs token from the device, as an opaque string of 10-4096 characters. For platform: web this is the FCM web registration token from getToken() — not a Web Push PushSubscription object, which is rejected. Note the asymmetry: this field is named token on the way in, but is returned as device_token on the Device object. The person and workspace are taken from the path and the API key respectively, so person_id and workspace_id are not accepted here.

Min length: 10 • Max length: 4096

platformstring

Required

Device platform

Options: ios, android, web

Request Preview

Response

Response will appear here after sending the request

Authentication

header

Authorizationstring

Required

Bearer token. Your Flameup API key (passed as Bearer token)

Path Parameters

externalIdstring

Required

Body

application/json

tokenstring

Required

Note the asymmetry: this field is named token on the way in, but is returned as device_token on the Device object. The person and workspace are taken from the path and the API key respectively, so person_id and workspace_id are not accepted here.

platformstring

Required

Device platform

Allowed values:iosandroidweb