Connect Apple Business Connect

Publish a location to Apple Maps through the owner's verified Apple Business account, or through the ListingsAPI account when they have none, then check the listing and disconnect when a client leaves.

ListingsAPI publishes a location's name, category, address, phone, website, and hours to Apple Maps and Siri in one of two ways.

The business owner has	What happens
A verified Apple Business organization account	The owner connects it to the location with an OAuth link (steps 1 and 2), and ListingsAPI publishes through their account.
No verified Apple Business organization account	No connection is needed. ListingsAPI submits the location through its own Apple Business Connect account, and Apple verifies the submission before it publishes the data. Go to step 3.

OAuth connects one location at a time, with site set to APPLE.

1. Create the connect link and redirect the owner

Skip steps 1 and 2 if the owner has no verified Apple Business organization account.

POST /locations/oauth_connect_url returns an OAuth URL scoped to one location. Send site: "APPLE" with the location ID and your two redirect URLs.

Connect link

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"  }}'

The response is data.createConnectUrl with success, url, and errors. Redirect the owner to url. They sign in to their verified Apple Business organization account, grant access, and are redirected to your successUrl; if they cancel or the grant fails, they are redirected to errorUrl.

The link is single-use, so create a fresh one per attempt. A relative or unparseable redirect URL comes back as success: true with a null url, so check url before redirecting. A key that may not touch this location gets a 403 with SY90003.

2. Confirm the connection

After the owner returns to your successUrl, list connected accounts filtered to Apple. This is an offset page: records[] plus pageInfo.totalRecords, paged with page and perPage.

List accounts

curl "https://listingsapi.com/api/v4/connected-accounts?publisher=AppleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

Keep the connectedAccountId. status is CONNECTED, MATCH_IN_PROGRESS, or CONNECTIVITY_ISSUE; anything but CONNECTED means the owner has to open a new connect link before updates can go through their account.

3. Check the Apple Maps listing

This step is the same whether or not the owner connected an account. GET /locations/{locationId}/listings/premium returns one record per premium publisher on the plan. The Apple Maps record has site.url set to business.apple.com.

Apple Maps status

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

The record is not SYNCED and listingUrl is null until Apple publishes the place card. When the location was submitted through the ListingsAPI account, Apple verifies the submission before it publishes. Once Apple publishes, the record is SYNCED with listingUrl set to the live Apple Maps URL. For the full status table, see Check listing status and live links.

Siri results come from the location's Apple Maps listing. Their status is returned by GET /locations/{locationId}/voice-assistants under the SIRI voiceIdentifier.

4. Confirm suggested matches

If connection suggestions include Apple records, their accountType is APPLE, and the match-record type you encode for Confirm connection matches is AppleLocationMatchedData. Build the ID as the base64 of AppleLocationMatchedData:<matchedDataDatabaseId> and send it in matchRecordIds.

5. Disconnect the location when a client leaves

This step applies only to a location connected with OAuth. POST /locations/oauth-disconnect removes the connection between one location and the owner's Apple Business account. Send site: "APPLE". The location stays in your account and its other publisher connections are not affected.

Disconnect

curl -X POST https://listingsapi.com/api/v4/locations/oauth-disconnect \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "APPLE" } }'

The response is data.disconnectConnectedAccountsLocations with success and errors. A location with no active Apple connection returns SY10057, and a request with neither site nor providerId returns SY10056.

6. What happens next

There is no connection.* webhook event for Apple. If the owner connected with OAuth, confirm the connection by listing accounts (step 2). In both cases, check the publishing status by reading the Apple Maps record (step 3). The listing.submission event reports each publisher submission when it reaches a terminal state.

If the connection later reports CONNECTIVITY_ISSUE, create a new connect link (step 1) and ask the owner to sign in again.

Next steps

Check listing status and live links: check the Apple Maps submission status and collect the live URL.
Find and fix listing errors: turn REQUIRING_ACTION and FAILED rows into fixes.
SDK references: Python connected accounts and Node connected accounts.
Reference: Create an OAuth connect URL for one location, List connected accounts, Get premium listings, Disconnect one location from a publisher.