Changelog

Revision History

Date	Version	Summary
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
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.

Reference

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 HOMEPAGE entry already exists on the same resource, the YELP entry is dropped and HOMEPAGE remains.
• If YELP is the only entry, it is dropped with no replacement — the resource will have no urls[] 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 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 — DELEGATION notifications are not generated when a delegated brand location is deleted
• Added missing operation field to the Location Delegation example response body
• Corrected state value in the Location Delegation example from PUBLISHED to SUBMITTED
• Removed DELETE from operation possible values
• Removed "or deleted" from brandId and etag field 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_READ and OAUTH_BRAND_WRITE → OAUTH_BUSINESS_WRITE
• Added documentation for two previously undocumented scopes: OAUTH_BRANDED_MAIL and OAUTH_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:

• Webhook Configuration
• Webhook Health Check POST

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_USER returned when attempting to delete an organization that has an active manager user.

• New validation DepartmentMustBeValidForUseWithBrandPrimaryCategory - Validate that department value 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 orgs instead of companies.

Terminology Changes

• All resource response bodies (Location, Brand, Brand Asset, Email ID, and so on) return orgId instead of companyId.
• Feedback/notification body field renames in DELEGATION and OAUTH_APP_GRANT types. In these sub-objects:
  • companyDetails → orgDetails
  • companyLegalName → orgLegalName
  • companyId → orgId
• Delegation API:
  • delegatedPartnerCompanyId → delegatedPartnerOrgId
  • expand=companyDetails → expand=orgDetails
• Narrative terminology updated from “company/companies” to “organization(s).”

Migration Impact

• Action required: Update all API request paths and parameters from companies to orgs.
• 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

• brandAssetId has 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 brandAssetId from 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.

warning

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 400 error.

---

New Resource State

Location Resource

• New state: PUBLISH_PAUSED. Targeted release date: Monday April 20.

note

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-Timestamp is generated immediately prior to signing and sending the POST request.
• 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-Timestamp freshness.
• Partners who implement freshness validation against Business-Timestamp will 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:

• Get Location API
• Get Location Asset API
• Get Apple Overrides API

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.