Skip to content
warmupDocs

Start connecting a network

POST
/projects/{id}/connections/{platform}/start
curl --request POST \
  --url https://api.warmup.social/projects/00000000-0000-0000-0000-000000000000/connections/facebook/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "timezone": "Europe/Kyiv" }'

Returns authUrl. Open it in a browser and sign in to Meta — this step cannot be done through the API. Meta sends the browser back to /oauth/{platform}/callback, and the API redirects it to the dashboard:

  • /projects/{id}?connect={platform}&result=ok — connected;
  • /projects/{id}?connect={platform}&result=error&code=<code> — failed (oauth_denied, instagram_not_professional, no_facebook_pages, …);
  • /projects/{id}?connect=facebook&select=<selectionId> — the Facebook account has several Pages: pick one with “List Facebook Pages to select” and “Select a Facebook Page” (or in the dashboard).

Reconnecting the same account (for example on needs_reauth) uses the same call.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Example 

00000000-0000-0000-0000-000000000000

Project UUID.

platform
required
string
Allowed values: facebook instagram threads

Example 

facebook

Meta network.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
timezone

IANA time zone; daily account refreshes are scheduled in it.

string
>= 1 characters <= 64 characters

Example 

{
  "timezone": "Europe/Kyiv"
}

Responses

Section titled “Responses”

201

Section titled “201”

Link to the Meta authorization window.

Media typeapplication/json
object
authUrl
required
string format: uri

Example generated

{
  "authUrl": "https://example.com"
}

400

Section titled “400”

Invalid request.

Media typeapplication/json
object
statusCode
required
integer
message
required
One of:
string
error
string
key
additional properties
any

Example 

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

401

Section titled “401”

The Bearer token is missing or invalid.

Media typeapplication/json
object
statusCode
required
integer
message
required
One of:
string
error
string
key
additional properties
any

Example 

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

404

Section titled “404”

The requested resource was not found.

Media typeapplication/json
object
statusCode
required
integer
message
required
One of:
string
error
string
key
additional properties
any

Example 

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

503

Section titled “503”

Meta OAuth is temporarily unavailable (meta_unavailable).

Media typeapplication/json

Error with a machine-readable code. Body validation errors come as formErrors / fieldErrors; business errors carry a code.

object
code
string
platform
string
Allowed values: facebook instagram threads
formErrors
Array<string>
fieldErrors
object
key
additional properties
Array<string>

Example 

{
  "code": "connection_missing",
  "platform": "facebook",
  "fieldErrors": {
    "mediaId": [
      "media_required"
    ]
  }
}