Criar uma sessão de cadastro de número

curl

curl -X POST 'https://api.synergyconnect.com.br/v1/onboarding-sessions' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"redirect_url":"https://app.minha-plataforma.com/whatsapp/ok","state":"e7f2c0d4-9b1e-4c52-8d0a-3f6a1b2c4d5e","mode":"choice","return":"redirect","display_name":"Minha Plataforma","external_ref":"tenant_8841","attach_to_key_ids":["0b9c4d1e-52a7-4f6b-8c3d-1e2f3a4b5c6d"],"expires_in":900}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v1/onboarding-sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "redirect_url": "https://app.minha-plataforma.com/whatsapp/ok",
    "state": "e7f2c0d4-9b1e-4c52-8d0a-3f6a1b2c4d5e",
    "mode": "choice",
    "return": "redirect",
    "display_name": "Minha Plataforma",
    "external_ref": "tenant_8841",
    "attach_to_key_ids": [
      "0b9c4d1e-52a7-4f6b-8c3d-1e2f3a4b5c6d"
    ],
    "expires_in": 900
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v1/onboarding-sessions",
    headers={
        "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
    },
    json={
        "redirect_url": "https://app.minha-plataforma.com/whatsapp/ok",
        "state": "e7f2c0d4-9b1e-4c52-8d0a-3f6a1b2c4d5e",
        "mode": "choice",
        "return": "redirect",
        "display_name": "Minha Plataforma",
        "external_ref": "tenant_8841",
        "attach_to_key_ids": [
            "0b9c4d1e-52a7-4f6b-8c3d-1e2f3a4b5c6d",
        ],
        "expires_in": 900,
    },
)
print(res.status_code, res.json())

201

{
  "id": "obs_4Fq9Lm2Xr7Tz1Vb8Nc3Kd6Hs",
  "status": "pending",
  "url": "https://app.synergyconnect.com.br/connect#obl_org_7Hk2pQ9_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA_bbbbbbbbbb",
  "mode": "choice",
  "return": "redirect",
  "redirect_url": "https://app.minha-plataforma.com/whatsapp/ok",
  "state": "e7f2c0d4-9b1e-4c52-8d0a-3f6a1b2c4d5e",
  "external_ref": "tenant_8841",
  "display_name": "Minha Plataforma",
  "created_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:15:00.000Z",
  "blocked": null,
  "last_error": null,
  "result": null
}

Há 2 casos com este status; veja a tabela de respostas.

400

{
  "error": "Invalid body",
  "issues": [
    {
      "code": "custom",
      "path": [
        "display_name"
      ],
      "message": "reserved"
    }
  ]
}

401

{
  "error": "Invalid or revoked key"
}

Há 2 casos com este status; veja a tabela de respostas.

403

{
  "error": "This key lacks the onboarding scope"
}

Há 6 casos com este status; veja a tabela de respostas.

413

{
  "error": "The body is too large (8 KB max)"
}

422

{
  "error": "Cadastre esta URL de retorno em Configurações → Desenvolvedor.",
  "reason": "return_url_not_registered"
}

Há 2 casos com este status; veja a tabela de respostas.

429

{
  "error": "Rate limit hit"
}

Há 4 casos com este status; veja a tabela de respostas.