Listings APIListings API
Get API keySign in
POST/api/v4/connected-accounts/connect-facebook

Connect a Facebook account

Returns an OAuth URL to link a Facebook Pages account to your Listings API account.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Body

NameTypeRequiredDescription
inputobjectrequiredWrapper object. The entire request body must be nested under `input`.
input.successUrlstringrequiredURL the user is redirected to after they successfully authorize Facebook. Must be an absolute https URL you control.
input.errorUrlstringrequiredURL the user is redirected to if they cancel or the authorization fails. Must be an absolute https URL you control.

Sample request

Ready-to-paste body. Replace placeholder IDs and values with yours.

{
  "input": {
    "successUrl": "https://docs.listingsapi.com/docs/api/connected-accounts-trigger-matches",
    "errorUrl": "https://docs.listingsapi.com/docs/api/connected-accounts-connect-facebook"
  }
}

Responses

200OAuth URL generated successfully. Redirect the user to `url` to begin the Facebook authorization flow.
{
  "data": {
    "bulkConnectLinkForFacebook": {
      "errors": null,
      "success": true,
      "url": "https://claim.verifymybiz.com/locations/redirect_oauth_bulk/facebook?onboarding=false&platform=local&token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52"
    }
  }
}
400Bad request, the body was not wrapped in `input`, or `successUrl`/`errorUrl` was omitted (GraphQL: `Variable "$input" of required type "FacebookOauthBulkInput!" was not provided`).
401Unauthenticated, missing or invalid API key.

Generates a short-lived OAuth URL that a user visits to authorize Listings API to manage their Facebook Pages in bulk. Redirect the user to the returned url; during the flow they review and accept Facebook's terms and grant the page-management permissions Listings API needs. The link is valid for 24 hours.

Request shape. The body must be wrapped in an input object containing two required fields, successUrl and errorUrl. These are the absolute https URLs the user is returned to after they finish (or abandon) the Facebook authorization flow; pass endpoints in your own application that resume onboarding on success and surface a retry on error. There is no accountId field, the connect link is always scoped to the account that owns the API key, and sending accountId (or a flat, unwrapped body) is rejected with an HTTP 400.

This is the Facebook counterpart to the connect-google endpoint and the first step of the bulk-connect workflow. Once authorized, the account shows up in GET /connected-accounts with a connectedAccountId used for matching and syncing.

Use case: onboarding a client's Facebook pages. After a client grants Facebook access, redirect them to the returned url. When they finish, run POST /connected-accounts/trigger-matches, review the results with GET /connected-accounts/{connectedAccountId}/connection-suggestions, and confirm the pairings via POST /connected-accounts/confirm-matches so Facebook Page data begins syncing with the matched Listings API locations.

Use case: re-authorizing after declined permissions. If a user skips a required Facebook permission, the connection cannot sync. Re-issue the link and have them re-authorize with all permissions granted.

For Google, use the connect-google endpoint. success: true with a non-null url means the link was generated; errors is populated only when generation fails.

curl -X POST 'https://listingsapi.com/api/v4/connected-accounts/connect-facebook' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "successUrl": "https://docs.listingsapi.com/docs/api/connected-accounts-trigger-matches",
      "errorUrl": "https://docs.listingsapi.com/docs/api/connected-accounts-connect-facebook"
    }
  }'
Run in playground