Skip to content
Tilecast Docs

createPairingSession

POST
/api/v1/player/pairing-sessions
curl --request POST \
  --url https://example.com/api/v1/player/pairing-sessions \
  --header 'Content-Type: application/json' \
  --data '{ "installationId": "example", "metadata": { "playerInstallationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "platform": "example", "manufacturer": "example", "model": "example", "androidVersion": "example", "playerVersion": "example", "screenWidth": 1, "screenHeight": 1, "density": 1, "locale": "example", "timezone": "example", "approximateAddress": "example" } }'

Public. Start a pairing session and return the visible code with its private poll secret.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
installationId
required

Installation identity the Player read from the server.

string
metadata
required
object
playerInstallationId
required
string format: uuid
platform
required
string
>= 1 characters <= 120 characters
manufacturer
required
string
>= 1 characters <= 120 characters
model
required
string
>= 1 characters <= 120 characters
androidVersion
required
string
>= 1 characters <= 120 characters
playerVersion
required
string
>= 1 characters <= 120 characters
screenWidth
required
integer
>= 1 <= 16384
screenHeight
required
integer
>= 1 <= 16384
density
required
number
>= 0.5 <= 10
locale
required
string
>= 1 characters <= 120 characters
timezone
required
string
>= 1 characters <= 120 characters
approximateAddress
string
Examplegenerated
{
  "installationId": "example",
  "metadata": {
    "playerInstallationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "platform": "example",
    "manufacturer": "example",
    "model": "example",
    "androidVersion": "example",
    "playerVersion": "example",
    "screenWidth": 1,
    "screenHeight": 1,
    "density": 1,
    "locale": "example",
    "timezone": "example",
    "approximateAddress": "example"
  }
}

Responses

Section titled “ Responses ”

201

Section titled “201”

Pairing session created

Media typeapplication/json
object
data
required
object
id
required
string format: uuid
code
required

Visible six-character pairing code shown to the installer.

string
>= 6 characters <= 6 characters /^[2-9A-HJ-KM-NP-Z]{6}$/
pollSecret
required

Private poll secret for Authorization Pairing polling. Never use the visible code to poll.

string
expiresAt
required
string format: date-time
serverTime
required
string format: date-time
pollingIntervalSeconds
required
integer
>= 1
approvalUrl
required
string
organizationName
required
string
Examplegenerated
{
  "data": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "code": "example",
    "pollSecret": "example",
    "expiresAt": "2026-04-15T12:00:00Z",
    "serverTime": "2026-04-15T12:00:00Z",
    "pollingIntervalSeconds": 1,
    "approvalUrl": "example",
    "organizationName": "example"
  }
}

409

Section titled “409”

Installation identity mismatch

429

Section titled “429”

Pairing requests are rate limited