# Start connection

> Start a hosted OAuth connection and get the URL to send your customer to.

Canonical: <https://www.tryadeli.com/docs/api/connect/start-connection>

`POST https://app.tryadeli.com/api/v1/profiles/{profileId}/connect`

Authorization: `Bearer <API key>` — see [Authentication](https://www.tryadeli.com/docs/authentication)

**Body**

| Name          | Type                                                                     | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform`    | `"instagram" \| "tiktok" \| "facebook" \| "youtube" \| "x" \| "bluesky"` | Yes      | X returns `402 x_billing_required` until the workspace has a card on file; see [X API pricing](https://www.tryadeli.com/docs/pricing/x). WhatsApp and Google Business Profile are accepted by the schema but return `422 provider_not_supported`. A business connects its WhatsApp number itself, through Embedded Signup on the dashboard's Accounts page.                                                                  |
| `redirectUrl` | `string`                                                                 |          | Where to send the browser when authorization finishes. Its origin must be allowlisted on the server, and it must use HTTPS unless the host is localhost or 127.0.0.1. Omit it to poll only.                                                                                                                                                                                                                                  |
| `authMethod`  | `"instagram_login" \| "facebook_login"`                                  |          | Instagram only, and optional. `instagram_login` (the default) signs in on Instagram; `facebook_login` signs in with Facebook and connects the Instagram account linked to one of your customer's Pages. See [Instagram login methods](https://www.tryadeli.com/docs/api/connect#instagram-login-methods). Sending it with any other platform returns `400 invalid_request`.                                                  |
| `handle`      | `string`                                                                 |          | Bluesky only, and optional: your customer's handle, such as `alice.example.com`, or their DID. The connect then starts at the server their account lives on. Leave it out for accounts hosted on Bluesky itself (`*.bsky.social` and most custom domains), which sign in at bsky.social. See [Bluesky](https://www.tryadeli.com/docs/api/connect#bluesky). Sending it with any other platform returns `400 invalid_request`. |

A successful start returns `201`.

Instagram sessions also carry the `authMethod` they were started with.

**Errors** — `401 unauthorized`, `400 invalid_request`,
`400 invalid_redirect_uri`, `404 profile_not_found`,
`402 billing_required` (past the workspace's free accounts with no card on file; see [Billing](https://www.tryadeli.com/docs/billing#in-the-api)), `409 auth_method_conflict`, `422 provider_not_supported`,
`422 provider_not_configured`, `502 database_error`.

## Request examples

**cURL**

```bash
curl --fail-with-body -X POST "https://app.tryadeli.com/api/v1/profiles/00000000-0000-4000-8000-000000000001/connect" \
  -H "Authorization: Bearer $ADELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "instagram",
  "redirectUrl": "https://client.example/callback"
}'
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/profiles/00000000-0000-4000-8000-000000000001/connect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADELI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "instagram",
    redirectUrl: "https://client.example/callback",
  }),
});
console.log(await response.json());
```

**Python**

```python
import os

import requests

response = requests.post(
    "https://app.tryadeli.com/api/v1/profiles/00000000-0000-4000-8000-000000000001/connect",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    json={
        "platform": "instagram",
        "redirectUrl": "https://client.example/callback",
    },
)
print(response.json())
```

## Responses

### 201

```json
{
  "id": "00000000-0000-4000-8000-000000000002",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "platform": "instagram",
  "authMethod": "instagram_login",
  "status": "pending_authorization",
  "accountId": null,
  "expiresAt": "2026-09-08T20:10:00.000Z",
  "completedAt": null,
  "error": null,
  "authUrl": "https://www.instagram.com/oauth/authorize?..."
}
```

### 400

```json
{
  "error": {
    "code": "invalid_redirect_uri",
    "message": "redirectUrl origin is not allowlisted"
  }
}
```