/api/v4/locations/oauth_connect_urlConnect a location to Apple Business Connect
Creates an Apple Business Connect OAuth link for one location, so ListingsAPI publishes that location to Apple Maps through the owner's verified Apple Business account.
Parameters
Body
| Name | Type | Required | Description |
|---|---|---|---|
| input | object | required | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | required | Location to connect. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
| input.site | string | required | Set to `APPLE`. |
| input.successUrl | string | required | Absolute URL in your application the owner returns to after granting access. |
| input.errorUrl | string | required | Absolute URL in your application the owner returns to if they cancel or the grant fails. |
Sample request
Ready-to-paste body. Replace placeholder IDs and values with yours.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "APPLE", "successUrl": "https://app.example.com/locations/1800289/apple/connected", "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed" }}Responses
200A single-use link to send the owner to. `errors` is `null` on success. The `url` shown is a placeholder; send the owner to the `url` returned in your own 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`).
Use this when the business owner has a verified Apple Business organization account. Send the owner to url; they sign in to Apple Business Connect, grant access, and return to your successUrl. From then on, ListingsAPI publishes that location's name, category, address, phone, website, and hours to Apple Maps through the owner's account. If they cancel or the grant fails, they return to errorUrl and nothing is connected.
If the owner has no verified Apple Business organization account, skip this call. ListingsAPI publishes the location through its own Apple Business Connect account, and Apple verifies the submission before it publishes.
Apple connects one location per link. To connect several locations, create a link for each one. Both redirect URLs must be absolute; a relative or unparseable value comes back as success: true with a null url, so check url before redirecting. The link is single-use, so create a fresh one per attempt.
Confirm the connection
After the owner returns to successUrl, call List connected accounts with publisher=AppleAccount. A status of CONNECTED means updates go through the owner's account. MATCH_IN_PROGRESS or CONNECTIVITY_ISSUE means the owner has to open a new connect link.
To stop publishing through the owner's account, use Disconnect a location from Apple Business Connect. For the full flow, including how to check the Apple Maps listing, see Connect Apple Business Connect.
This page documents the site: "APPLE" case of Create an OAuth connect URL for one location.
This endpoint creates live OAuth credentials. The sample request and response above are examples.
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": "APPLE", "successUrl": "https://app.example.com/locations/1800289/apple/connected", "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed" } }'