Listings APIListings API
Get API keySign in
POST/api/v4/locations/oauth_connect_url

Create an OAuth connect URL for one location

Mints a publisher OAuth link that connects a single location, with your own success and error redirects.

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.locationIdstringrequiredLocation the connection will be attached to. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID.
input.sitestringrequiredPublisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`.
input.successUrlstringrequiredAbsolute URL the publisher returns the user to after they grant access.
input.errorUrlstringrequiredAbsolute URL the publisher returns the user to if they cancel or the grant fails.

Sample request

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

Request body
{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}

Responses

200A single-use OAuth URL to send the user to. `errors` is `null` on success.
Response
{  "data": {    "createConnectUrl": {      "success": true,      "url": "https://accounts.google.com/o/oauth2/auth?client_id=...&state=8f3c1d92-4a7e-4d0b-9c31-6b2f7ae51c04",      "errors": null    }  }}
401Unauthenticated, missing or invalid API key.
403The key is valid but not permitted to connect this location (`SY90003`).

Returns a publisher OAuth URL scoped to one location. Send the end user to url; when they finish, the publisher redirects them to your successUrl (or errorUrl) and the resulting credentials are attached to the location as a connected account.

This is the single-location counterpart to the bulk flows, Bulk-connect Google accounts and Bulk-connect Facebook accounts, which mint an account-wide link and then rely on matching to attach listings. Use this route when you already know which location the user is connecting and want them to land back on that location's page in your own product.

Both redirect URLs are required and must be absolute; a relative or unparseable value comes back as success: true with a null url, so check url and not just success. The link is single-use and tied to the location you named, so mint a fresh one per attempt rather than caching it.

Use case: an in-app "Connect Google" button per store

On a location's settings screen, POST this route with the location's ID, site: "GOOGLE", and redirects pointing at that same screen. Open url in a popup or full-page redirect. On return, read Get connected-account details or the location's connection info to confirm the link landed, then show the connected state. If the user abandons the flow they arrive at errorUrl and nothing is attached, so the button can simply be offered again.

This endpoint mints live OAuth credentials. The request shape and sample response above are documented from the gateway's request translation and the upstream CreateConnectUrl mutation (ConnectUrlType), not captured from a live call.

Request
curl -X POST 'https://listingsapi.com/api/v4/locations/oauth_connect_url' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "locationId": "TG9jYXRpb246MTgwMDI4OQ==",      "site": "GOOGLE",      "successUrl": "https://app.example.com/locations/1800289/connected",      "errorUrl": "https://app.example.com/locations/1800289/connect-failed"    }  }'
Run in playground