Skip to the content
Get an API key
  1. API reference
  2. Managed Transfers

Create transfer session

POST/public/transfer-sessions
Managed TransfersAuthBasicDevToken

Creates a pre-authorized session of the hosted transfer wizard. Your backend sends the access token of a user who is already signed in to your destination service in your app. We check the token with the service, store it encrypted, attach the account as the destination and answer with a launchUrl. The user then connects only the source. Requires Client Secret (Basic) or a DevToken without sub. See Pre-authorized Sessions.

Request body

application/json · required

target
object
required
target.authData
PreauthorizedAuthData
required
target.authData.accessToken
string
requiredThe user's access token for your destination service.
target.authData.refreshToken
string
The refresh token. Used only when your destination integration has OAuth client credentials that can renew it.
target.authData.expiresAt
date-time | number
When the access token expires: an ISO 8601 date, or a Unix time in seconds or milliseconds.
externalUserId
string
Your own reference for the user. Sent back in the webhooks of this session.
returnUrl
uri
The results page links back to this URL. It must match your Return URLs; with none set, it must be https.
locale
string
The user's language. The wizard is in English today.

Response

201application/json · CreateTransferSessionResponseThe session is created.
sessionUuid
uuid
launchUrl
uri
Opens the hosted wizard. Works once, for 15 minutes. The single-use code is in the URL fragment.
launchExpiresAt
date-time
expiresAt
date-time
When the session ends (24 hours after creation).
externalUserId
string | null
target
PreauthorizedTarget
target.integrationType
string
target.integrationUserUuid
uuid
target.displayName
string | null
Example answer
{
  "sessionUuid": "5b0c6f0e-2c8a-4d0e-9a51-7e3f1c2d9b44",
  "launchUrl": "https://example.com",
  "launchExpiresAt": "2026-10-16T09:41:07.000Z",
  "expiresAt": "2026-10-16T09:41:07.000Z",
  "externalUserId": "string",
  "target": {
    "integrationType": "spotify",
    "integrationUserUuid": "5b0c6f0e-2c8a-4d0e-9a51-7e3f1c2d9b44",
    "displayName": "Jane Listener"
  }
}

Errors

400

The body is not valid, no transfer destination is set, or the destination does not support pre-authorized sessions.

401

The request has no credentials.

403

The credential is not secret, or the transfer service is not enabled for your account.

422

The music service refused the access token. Nothing is stored.

503

The music service could not be reached to check the token. Try again later.