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

Create an OAuth connect URL for one location

Creates 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. The `url` shown is a placeholder; send the user to the `url` returned in your own response.
Response
{  "data": {    "createConnectUrl": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "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 create 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 return to 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 create a fresh one per attempt rather than caching it.

Use case: connect one store from your own app

When a user connects one store from your app, POST this route with the location's ID, site: "GOOGLE", and redirect URLs that point back into your app. Send the user to url in a popup or a full-page redirect. When they return, read Get connected-account details or the location's connection info to confirm the link landed, then show the connected state in your app. If the user abandons the flow they arrive at errorUrl and nothing is attached, so create a fresh link and let them try again.

Use case: publish through the owner's Apple Business account

Send site: "APPLE" to connect one location to the owner's verified Apple Business organization account. The owner opens url, signs in to that account, and grants access. From then on, ListingsAPI publishes that location's Apple Maps data through the owner's account.

If the owner has no verified Apple Business organization account, skip this flow. ListingsAPI publishes the location through its own Apple Business Connect account, and Apple verifies the submission before it publishes. Each location is connected separately, so one account can have both kinds of location.

After the owner returns to successUrl, call List connected accounts with publisher=AppleAccount and check that the account's status is CONNECTED. For the full flow, including how to check the Apple Maps listing, see Connect Apple Business Connect.

This endpoint creates live OAuth credentials. The sample request and response above are examples.

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