Changelog
Revision History
Date | Version | Summary |
|---|---|---|
| October 21, 2026 | 1.10.0 | Advance notice: social media urls[] entries that link to no profile will be removed the week of November 16, 2026; Get User & Organization Details response enhancement: granularAccess; New Get Delegated Access API |
| October 7, 2026 | 1.9.1 | Address rules corrections: postCode required for AL, CZ, PK, RO, SA and optional for AS, MP, UM; fullThoroughfare required for EG, IE |
| October 2, 2026 | 1.9.0 | Apple Categories taxonomy update; Apple Categories with localized names available for download; Removed undocumented REMOVE__FLEXIBLE_ACTION_LINK_FROM_LOCATION metadata code; New review validation for About section suitability screening; New BRAND_ID_REQUIRED_FOR_AUTHORIZATION error code for Location create/update; New Close and Delete Location API |
| September 10, 2026 | 1.8.0 | New APPLE_OVERRIDE__CLOSED error code; advance notice of YELP urls[].type removal effective October 22, 2026; new brand-inheritance metadata codes |
| August 24, 2026 | 1.7.2 | Location claim validation documentation |
| August 18, 2026 | 1.7.1 | Apple Override documentation: update location with a non-matching value |
| August 3, 2026 | 1.7.0 | Apple Categories and Location Attributes taxonomy updates |
| July 21, 2026 | 1.6.0 | Null byte (U+0000) added to unsupported characters |
| July 17, 2026 | 1.5.3 | Pagination properties documentation correction |
| July 13, 2026 | 1.5.2 | AIE location count limit added to location count validations; New LocationAssetCountExceedsMaximum validation for location asset count limit |
| June 26, 2026 | 1.5.1 | Location asset update validation documentation |
| June 23, 2026 | 1.5.0 | Brand delete notification and feedback documentation; Delegation notification documentation corrections; Get User & Organization Details (formerly known as Get Access Token Details) response enhancements; Location capture eligibility guidance; Undelete Location API enhancement |
| June 15, 2026 | 1.4.4 | OAuth scopes documentation update; OAuth authorization request parameter name correction: redirection_endpoint → redirect_uri |
| June 11, 2026 | 1.4.3 | Webhook health check message type correction: HEALTH_CHECK → HEALTH |
| June 10, 2026 | 1.4.2 | OAuth scope correction: OAUTH_BRAND_WRITE does not permit brand deletion |
| June 9, 2026 | 1.4.1 | Delegation state value correction |
| June 5, 2026 | 1.4.0 | New 409 Conflict status code and BRAND__CREATION_IN_PROGRESS error code |
| May 21, 2026 | 1.3.0 | Location duplicate detection error code update |
| May 19, 2026 | 1.2.1 | Delegation API documentation |
| May 5, 2026 | 1.2.0 | Notifications API enhancements |
| April 21, 2026 | 1.1.0 | Validation and error code updates |
| April 14, 2026 | 1.0.0 | Initial release |
Revision Number Increments
| Version | Explanation |
|---|---|
| 1.0.0 | Major version with incompatible API changes. Includes number increment and new content. |
| 1.0.0 | Minor version with functionality added in a backward compatible manner. Includes number increment and changes to current content. |
| 1.0.0 | Patch version with backward compatible bug fixes. Includes number increment and content corrections that do not change functionality, such as graphics, grammar, etc. |
Version 1.10.0
Location & Brand URLs
Advance Notice — Removal of Social Media URLs With No Profile
The week of November 16, 2026, urls[] entries that link to a social media platform itself, rather than to a profile on it, will be removed from stored Location and Brand records. A link such as https://twitter.com/ takes a customer to the platform's front page and does not identify the business.
This applies to entries typed FACEBOOK, INSTAGRAM or X_DOT_COM, and to entries stored with the earlier type TWITTER. An entry is removed when nothing follows the platform's domain except, optionally, a trailing / or a query string:
| Removed | Kept |
|---|---|
https://twitter.com/ | https://twitter.com/examplebrand |
https://www.facebook.com/?locale=en_gb | https://www.facebook.com/examplebrand |
https://www.instagram.com | https://www.instagram.com/examplebrand/ |
https://twitter.com/#!/examplebrand |
HOMEPAGE entries are not affected, and other entries on the same resource are not affected. If the removed entry is the resource's only URL, the resource will have no urls[] entries afterward.
Each record that changes receives a new etag. Read the resource again before submitting an update to it, or the update will be rejected with 412 Precondition Failed.
No action is required. To keep a link to a social media profile, replace the entry with the profile's full URL before the week of November 16, 2026. See URL guidance.
Get User & Organization Details
Enhancement
The Get User & Organization Details response body (GET /api/v1/me) now supports the expand=granularAccess query parameter. When included, the response returns granularAccess[], listing the features an OAuth app has been delegated access to and, for each, whether it applies to all of the organization's brands or a specific set of brand IDs. ADS_ON_MAPS is never included in granularAccess[], since it can only be delegated and has no OAuth equivalent.
Delegation API
New API
Added Get Delegated Access, which retrieves the features and brands that have been delegated to you by one or more owner organizations, grouped by owner organization.
Version 1.9.0
Apple Categories
Updated Taxonomy
The following categories were added:
| Category | Name |
|---|---|
civil_service.public_safety | Public Safety |
civil_service.public_safety.emergency_assistance_center | Emergency Assistance Center |
civil_service.public_safety.resource_distribution_center | Resource Distribution Center |
shopping.store.toy_store.toy_library | Toy Library |
Updated Download Apple Categories and Download Quicklink Category and Primary Apple Category Mapping with the new taxonomy.
Location
New Error Code
Added error code BRAND_ID_REQUIRED_FOR_AUTHORIZATION (403 Forbidden). This error is returned when a Location create or update request is submitted without a brandId, which is required to authorize the request. See Brand ID Required for Authorization for details.
New API
Added Close and Delete Location (DELETE /api/v1/orgs/{orgId}/locations/{locationId}/close-and-delete). This operation closes a location — setting locationStatus to CLOSED with the current date as closedDate and publishing the change — then soft-deletes the resource in a single call. Use it to record a permanent closure before removing the location; to delete a location without recording a closure, use Delete.
Location Metadata
Documentation Correction
Removed REMOVE__FLEXIBLE_ACTION_LINK_FROM_LOCATION from Metadata Codes. This code was documented but never implemented — it does not appear anywhere in production. A flexible action link that no longer meets Apple Business standards continues to be reported only via Feedback (CURATION__FlexibleActionLinkRemovedFromLocation); no metadata is added to the location resource.
Review Validations
New Validation
Added ReviewBodyMustBeSuitableForAboutSection — validates that a critic review's reviewBody is suitable for display as the fallback content in a location's place card About section.
Version 1.8.0
Apple Override Accept
New Error Code
Added 400 Bad Request error code APPLE_OVERRIDE__CLOSED. This error is returned when a request to accept an Apple Override is submitted after the override has transitioned to CLOSED — meaning the location changed again before the user responded, superseding the override being accepted. See Closed for details.
Location & Brand URLs
Advance Notice — Upcoming Breaking Change
Expected October 22, 2026, YELP will be removed from the supported urls[].type values for both Location and Brand. Requests submitted with type: YELP on or after this date will be rejected.
Existing urls[] entries with type: YELP will be removed from stored records at the same time:
- If a
HOMEPAGEentry already exists on the same resource, theYELPentry is dropped andHOMEPAGEremains. - If
YELPis the only entry, it is dropped with no replacement — the resource will have nourls[]entries afterward unless a partner submits a new one.
A HOMEPAGE entry whose url happens to resolve to a Yelp domain is not affected by this change — only entries explicitly typed YELP are removed.
No action is required before October 22, 2026. Partners who rely on a type: YELP entry as their only anchor URL should submit a replacement HOMEPAGE value before this date to avoid ending up with no urls[] entries.
Location Metadata
Documentation
Added missing INHERIT__HOMEPAGE_FROM_BRAND, INHERIT__IOS_APP_FROM_BRAND, and INHERIT__AS_NON_PRIMARY_NAME_FROM_BRAND to Metadata Codes. These codes indicate when a location displays a value inherited from its brand — a homepage URL, an iOS app URL, or a non-primary display name — on the place card. The inherited value is computed downstream of the location's own data and is not written to the location's own resource.
Version 1.7.2
Location Validations
Documentation
Added missing ClaimedLocationSignificantlyModified to the Location validation rules. This validation fires on a Business Portal claim submission when the submitted displayNames or displayPoint have significantly diverged from the claimed Apple Maps record.
Version 1.7.1
Apple Override
Documentation
Added Update Location with a Non-Matching Value documenting the behavior when an API user updates a location while an Apple override is active on a field, and the submitted value does not match the override's feedback value. In this case, the override is not accepted, contested, or closed — it remains attached to the location resource under the new etag. Also added a note to Contest Apple Override clarifying that submitting a differing value through a location update is not equivalent to contesting an override.
Version 1.7.0
Apple Categories
Updated Taxonomy
The following categories were added:
| Category | Name |
|---|---|
association_or_organization.community_development_authority | Community Development Authority |
consumer_sector.professional.legal_service.law_firm.attorney.insurance_attorney | Insurance Attorney |
shopping.food_mart.bento_shop | Bento Shop |
shopping.food_mart.noodle_store | Noodle Store |
travel_and_leisure.watersports_center.surfing.wave_park | Wave Park |
Updated Download Apple Categories and Download Quicklink Category and Primary Apple Category Mapping with the new taxonomy.
Location Attributes
Updated Taxonomy
The following categories were added:
| Category | Name |
|---|---|
dining.mealoptions.omakase | Omakase |
dining.mealoptions.tasting_menu | Tasting Menu |
As previously announced, the deprecated category hotel.doorperson (Doorperson) has been removed. Partners using this category should migrate to hotel.property_amenity.door_attendant (Door Attendant).
Updated Download Location Attributes with the new taxonomy.
Version 1.6.0
Null Byte Character
New Validation
The null byte character (U+0000, JSON escape \u0000) has been added to the list of unsupported characters. A property MUST NOT contain this character in its value. This character has no legitimate use in location data text fields and causes failures in downstream data processing systems.
Targeted enforcement date: August 10, 2026
Version 1.5.3
Pagination
Documentation Correction
Corrected the Pagination Properties table to show the full JSON path (pagination.cursors, pagination.cursors.after, pagination.next) instead of bare property names. Also clarified that pagination is forward-only — there is no before or previous cursor — and added an example showing a subsequent page retrieved via pagination.next.
Version 1.5.2
Location Asset Validations
New Validation
Added LocationAssetCountExceedsMaximum. A location may have no more than 100 location assets. This validation applies in AIE environments only.
Location Validations
Updated Validations
Updated CountOfAgencyLocationsExceedsThreshold, CountOfUnverifiedOwnerLocationsExceedsThreshold, and CountOfVerifiedOwnerLocationsExceedsThreshold to include an AIE-specific location count limit of one thousand (1,000).
Version 1.5.1
Location Asset Update Validation
Documentation
Added missing VALIDATION__UpdatedLocationAssetShouldNotMatchExistingLocationAsset to the Location Asset validation rules. This validation rejects a location asset update when the submitted asset data is identical to the previous stored record.
Version 1.5.0
Brand Delete Notification and Feedback
Documentation
Added brand delete example response bodies to Type Processing Successful (Notification and Feedback tabs). When a brand is deleted, a PROCESSING_SUCCESSFUL notification and feedback record with state: DELETED is generated for the organization that initiated the delete and all partners whose delegation scope includes the brand.
Delegation Notifications
Documentation Correction
Corrected the Type Delegation notification description and example response body:
- Removed location delete as a triggering event —
DELEGATIONnotifications are not generated when a delegated brand location is deleted - Added missing
operationfield to the Location Delegation example response body - Corrected
statevalue in the Location Delegation example fromPUBLISHEDtoSUBMITTED - Removed
DELETEfromoperationpossible values - Removed "or deleted" from
brandIdandetagfield descriptions
Get User & Organization Details
Enhancement
The Get User and Organization Details response body (GET /api/v1/me) now includes companyDetails and companyId for backward compatibility with existing integrations. These fields are deprecated — clients should transition to orgDetails and orgId. New integrations should use orgDetails and orgId only.
Location
New Validation
Added documentation for the VALIDATION__PoiSuppressedInAppleMaps (INFO) validation code. This code is generated asynchronously when Apple Maps suppresses a conflated record associated with a location. The validation report includes a {{reason}} context value identifying the suppression condition(s). See PoiSuppressedInAppleMaps for details.
Location Capture Eligibility
New Guidance
Added Location Capture Eligibility guidance covering what does and does not qualify as a location eligible for submission. Includes eligible place types, general disqualifiers, and detailed examples of ineligible entities — departments and internal subdivisions, utility and service spaces, and administrative designations.
Version 1.4.4
OAuth Scopes
Documentation Update
Updated OAuth 2.0 Scopes:
- Corrected scope names:
OAUTH_BRAND_READ→OAUTH_BUSINESS_READandOAUTH_BRAND_WRITE→OAUTH_BUSINESS_WRITE - Added documentation for two previously undocumented scopes:
OAUTH_BRANDED_MAILandOAUTH_BUSINESS_CALLER_ID - Expanded scope tables to show granular permissions for each scope
Documentation Correction
Corrected the authorization request parameter name in Request Authorization Code. The parameter was incorrectly documented as redirection_endpoint; the correct name is redirect_uri, consistent with the API implementation and RFC 6749.
Version 1.4.3
Webhooks
Documentation Correction
The webhook health check message type value was incorrectly documented as HEALTH_CHECK. The correct value is HEALTH. Changes are visible in:
Version 1.4.2
OAuth Scopes
Documentation Correction
Corrected the permissions description for OAUTH_BRAND_WRITE. Brand deletion is not permitted under this scope. The description previously stated "Create, get, update, and delete"; the correct description is "Create, get, and update."
Version 1.4.1
Delegation API
Documentation Correction
Corrected the possible values for the delegation relationship state field in Get Delegated Brand Resources. The value NOT_ACTIVE was incorrectly documented; the correct value is INACTIVE, consistent with the API implementation and Type Delegation.
Version 1.4.0
Brand Create
New Error Code
Added 409 Conflict HTTP status code and error code BRAND__CREATION_IN_PROGRESS. This error is returned when a Brand create request is submitted while a previous create request for the same brand is still pending completion. See Creation In Progress for details.
Version 1.3.0
Location Duplicate Detection
Error Code Update
When a Location create request payload matches an already-existing location, the API now returns LOCATION__IS_MATCHED (400 Bad Request) with message "Resource has comparable representation". Previously this case returned LOCATION__ALREADY_EXISTS. Partners that check for LOCATION__ALREADY_EXISTS to detect Location duplicates should update their error handling to also handle LOCATION__IS_MATCHED. See Is Matched for details.
Version 1.2.1
Delegation API
Documentation
- Added specifications for Get Delegated Notifications and Get Delegated Feedback. These APIs were previously available but undocumented.
Version 1.2.0
Notifications API
Enhancements
The createdDate field on MAPS_DISPLAY notifications for APPLE_OVERRIDE__ notification types now reflects the time at which the notification was published and became available to query — not when the underlying change was originally submitted. Previously, because the publishing pipeline can take up to 48 hours, createdDate could significantly predate when a notification first appeared in query results, causing events to be missed when polling with a tight real-time window. This change makes createdDate a reliable anchor for time-based polling.
Version 1.1.0
- New error code
ORG__HAS_ACTIVE_MANAGER_USERreturned when attempting to delete an organization that has an active manager user.
- New validation
DepartmentMustBeValidForUseWithBrandPrimaryCategory- Validate thatdepartmentvalue is valid for use in conjunction with the brand's primary category. See Department Validations for details.
Breaking Changes
API Version and Request Path Changes
- API version in URL paths:
/api/v3/→/api/v1/ - API request templates now use
orgsinstead ofcompanies.
Terminology Changes
- All resource response bodies (Location, Brand, Brand Asset, Email ID, and so on) return
orgIdinstead ofcompanyId. - Feedback/notification body field renames in
DELEGATIONandOAUTH_APP_GRANTtypes. In these sub-objects:companyDetails→orgDetailscompanyLegalName→orgLegalNamecompanyId→orgId
- Delegation API:
delegatedPartnerCompanyId→delegatedPartnerOrgIdexpand=companyDetails→expand=orgDetails
- Narrative terminology updated from “company/companies” to “organization(s).”
Migration Impact
- Action required: Update all API request paths and parameters from
companiestoorgs. - No behavioral change: This is a naming/terminology change only; request semantics, authorization, and responses are unchanged.
Webhook Request Header Renames
The following request headers have been renamed for the Webhook POST request and the Health Check:
| Previous Name | New Name |
|---|---|
BusinessConnect-Timestamp | Business-Timestamp |
BusinessConnect-Signature | Business-Signature |
BusinessConnect-Webhook-Environment | Business-Webhook-Environment |
Migration Impact
- Action required: Update webhook implementations to recognize the new header names.
- No behavioral change: Header semantics and values are unchanged.
Removal of brandAssetId from Email ID
brandAssetIdhas been removed from all API operations- The field is no longer returned in Get responses and is not present in Create or Update response schemas.
Migration Impact
- Action required: Remove
brandAssetIdfrom all client models and response handling. - No replacement: This field is no longer exposed by the API.
Validations
New empty array validations added. Severity is VIOLATION. Fields:
$.assetDetails.captions$.assetDetails.classifications$.locationDetails.accessPoints$.locationDetails.actionLinkDetails.quicklinks$.locationDetails.internalNicknames$.locationDetails.keywords.other$.locationDetails.keywords.products$.locationDetails.keywords.services$.locationDetails.locationAttributes$.locationDetails.locationDescriptions$.locationDetails.locationDescriptions[].descriptions$.locationDetails.structuredAddress.dependentLocality$.locationDetails.openingHoursByDay$.locationDetails.openingHoursByDay[].times$.locationDetails.paymentMethods$.locationDetails.phoneNumbers$.locationDetails.serviceHours$.locationDetails.serviceHours[].hoursByDay[].times$.locationDetails.specialHours[].descriptions$.locationDetails.specialHours$.locationDetails.specialHours[].hoursByDay[].times$.locationDetails.urls$.reviewDetails.interactionStatistics$.reviewDetails.localizedReviews$.reviewDetails.starRatings
Location Duplicate Detection on Create
A duplicate detection constraint for the Location Create operation is now enforced with the v1 API launch. This constraint was previously documented in the Already Exists error reference but was not implemented.
Behavior: An attempt to create a Location resource using field values that match an already existing Location resource will return 400 ALREADY_EXISTS with code LOCATION__ALREADY_EXISTS.
Partners should review their Location create workflows prior to the v1 API launch to ensure requests do not submit duplicate records.
Migration Impact
- Action required: Audit Location create integrations and update error-handling logic to account for
LOCATION__ALREADY_EXISTS. - Behavioral change: Previously, duplicate Location create requests may have succeeded; they will now return a
400error.
New Resource State
Location Resource
- New state:
PUBLISH_PAUSED. Targeted release date: Monday April 20.
PUBLISH_PAUSED will be supported by a new processing code PROCESSING__LocationPublishingPausedInMapRegion which is expected to be released on Monday May 4.
Enhancements
Business-Timestamp Behavior Correction
Expected week of May 4, 2026
The Business-Timestamp request header in Webhook POST requests now reflects the HTTP request send time.
Previously, Business-Timestamp reflected the time the feedback event was generated rather than when the HTTP POST request was sent.
Updated behavior:
Business-Timestampis generated immediately prior to signing and sending thePOSTrequest.- The value no longer reflects the generation time of the feedback event described in the payload.
Migration Impact
- No action required for partners who do not validate
Business-Timestampfreshness. - Partners who implement freshness validation against
Business-Timestampwill now receive accurate send-time values.
Documentation Corrections
Pagination Link Correction
Updated example response bodies to correct pagination.next values by removing the /api prefix from the path. Changes are visible in:
The correction applies to documentation examples only. At this time, API responses may return pagination links either with the /api prefix or starting with /{api_version} (for example, /v1). This variation will be standardized in a future release.