Validations

Validation Reports

Validation reports are returned synchronously and/or asynchronously. Get operations for resources such as brands, locations, and so on, do not include validation reports in their respective response bodies. Validation reports may include all severity levels. Severities are used to categorize validation results.

Severity	Description
INFO	Non-critical constraint violation for informational purposes
WARNING	Non-critical constraint violation indicating a warning
VIOLATION	Constraint violation

Validation Report Properties

Name	Type	Description	Output
code	string	Validation name
message	string	Validation message describing the issue
severity	string	Possible values: VIOLATION, WARNING, or INFO
context	object	Refer to Context
details	object	Refer to Details

Context

Name	Type	Description	Output
key	string	A name-value map of a variable and its value necessary to construct the message. REQUIRED when message includes dynamic content. fieldName and value SHOULD NOT be present when a name/value mapping is used
field	string	Property provided by Apple Business that may be used to construct the message
minValue	string	A minimum value provided by Apple Business that may be used to construct the message
maxValue	string	A maximum value provided by Apple Business that may be used to construct the message
value	string	Value(s) provided by the API caller which may be used to construct the message
validValue	string	Value(s) provided by Apple Business that may be used to construct the message

Details

Name	Type	Description	Output
createdDate	dateTime	Apple-generated timestamp
compared	array	Describes a resource used in a comparison against the submitted record
expected	array	One or more field name expected to be present in a submitted record. MAY include an expected value
submitted	array	One or more field name and raw data value directly or indirectly contributing to the validation exception condition. MAY include an index identifying the position of an element in a list (array). Indexes are 0-based

note

Refer to FAQs for additional information

Synchronous Reporting

400 Bad Request indicates that the request to create or update a resource has failed. Only validation reports are included in a response body. The response body will include all VIOLATION, WARNING, and INFO severities.

Example Response Headers

HTTP/1.1 400 Bad Request
content-type: application/json

Example Response Body (raw JSON)

[
  {
    "code": "VALIDATION__DisplayNamesNameMustNotBeEmpty",
    "severity": "VIOLATION",
    "message": "'{{name}}' must not be empty string",
    "context": {
      "name": ""
    },
    "details": {
      "createdDate": "2026-10-10T11:36:02.00Z",
      "submitted": [
        {
          "field": "$.locationDetails.displayNames[0].name",
          "value": ""
        }
      ]
    }
  },
  {
    "code": "VALIDATION__LatLongMustNotBeZero",
    "severity": "VIOLATION",
    "message": "Values of latitude and longitude must not be both zero",
    "details": {
      "createdDate": "2026-10-10T11:36:02.00Z",
      "submitted": [
        {
          "field": "$.locationDetails.displayPoint.coordinates.latitude",
          "value": "0"
        },
        {
          "field": "$.locationDetails.displayPoint.coordinates.longitude",
          "value": "0"
        }
      ]
    }
  }
]

---

2XX indicates that the request to create or update a resource was successful. The response body may include WARNING and INFO severities. You are not required to take action against these validation reports. WARNING severities should be reviewed for conditions which warrant subsequent update of a resource.

Example Response Headers

HTTP/1.1 201 Created
apple-request-id: 3e1318e4-a34f-49a7-8640-33d70bb4f46e
content-type: application/json
etag: "4d891a34-ddc8-11ec-a7a0-f7f6c418993d"
location: /api/v1/orgs/9467895078742654934/brands/9467895078742654921

Example Response Body (raw JSON)

{
  "orgId": "9467895078742654934",
  "id": "9467895078742654921",
  "etag": "4d891a34-ddc8-11ec-a7a0-f7f6c418993d",
  "createdDate": "2026-10-01T07:30:00.00Z",
  "updatedDate": "2026-10-01T07:30:00.00Z",
  "state": "SUBMITTED",
  "brandDetails": {
    "partnersBrandId": "456456",
    "partnersBrandVersion": "PBV01",
    "countryCodes": [ "US" ],
    "displayNames": [
      {
        "name": "Organization Brand Name",
        "locale": "en",
        "primary": true
      }
    ],
    "categories": [ "dining.dessert_shop.ice_cream_shop", "dining.dessert_shop.ice_cream_shop.gelato_shop", "travel_and_leisure.sports_equipment_rental.watersports_rental.boat_rental" ],
    "urls": [
      {
        "url": "http://example.com",
        "type": "HOMEPAGE"
      }
    ],
    "ownershipType": "BRAND_OWNER"
  },
  "validationReports":[
    {
      "code": "VALIDATION__SuspiciousCombinationOfTopLevelCategories",
      "severity": "WARNING",
      "message": "Suspicious combination of top-level categories present",
      "details": {
        "createdDate": "2026-10-01T07:30:02.00Z",
        "submitted": [
          {
            "field": "$.brandDetails.categories",
            "value": [ "dining.dessert_shop.ice_cream_shop", "dining.dessert_shop.ice_cream_shop.gelato_shop", "travel_and_leisure.sports_equipment_rental.watersports_rental.boat_rental" ]
          }
        ]
      }
    }
  ]
}

Asynchronous Reporting

The feedback API provides validation reports and includes:

• All WARNING severities from inline validations (previously reported synchronously)
• All VIOLATION, WARNING, and INFO severities generated by offline validations

Validation Report Examples

Example One

Asynchronous reporting about geometry and a main address.

Response Body (raw JSON)

{
  "validationReports":[
    {
      "code": "VALIDATION__PointMustBeContainedByCountry",
      "severity": "VIOLATION",
      "message": "Point geometry must be contained by Country identified in mainAddress",
      "details": {
        "createdDate": "2026-10-10T11:36:02.00Z",
        "submitted": [
          {
            "field": "$.locationDetails.mainAddress.structuredAddress.countryCode",
            "value": "US"
          }
        ]
      }
    }
  ]
}

Example Two

Change detection reporting. A previously submitted location record is used for comparison purposes.

Response Body (raw JSON)

{
  "validationReports":[
    {
      "code": "VALIDATION__UnexpectedPrimaryPhoneNumberChange",
      "severity": "WARNING",
      "message": "Primary '{{phoneNumber}}' changed between last version and latest submittal",
      "context": {
        "phoneNumber": "+12222222222"
      },
      "details": {
        "createdDate": "2026-10-10T11:36:02.00Z",
        "submitted": [
          {
            "field": "$.locationDetails.phoneNumbers[0].phoneNumber",
            "value": "+12222222222"
          }
        ],
        "compared": [
          {
            "field": "$.locationDetails.phoneNumbers[0].phoneNumber",
            "value": "+19999999999"
          }
        ]
      }
    }
  ]
}

Example Three

Reporting about the absence of a recommended feature.

Response Body (raw JSON)

{
  "validationReports":[
    {
      "code": "VALIDATION__RecommendedFeatureNotPresent",
      "severity": "WARNING",
      "message": "New location does not include recommended Feature",
      "details": {
        "createdDate": "2026-10-10T11:36:02.00Z",
        "expected": [
          {
            "field": "$.locationDetails.phoneNumbers.phoneNumber"
          }
        ]
      }
    }
  ]
}