Get Matching Delegated Location Resources

API Description

Get a list of your location resources that match location resources associated with one or more brands that have been delegated to you. Any delegated resources that are not matched will be indicated in the response.
Any of your location resources which are not matched will be excluded from the response.

Request

URI Parameters

Name	Input
orgId

Query Parameters

Filters to apply on the operation.

Name	Input
delegatedBrandId
ids
partnerLocationIds

IDs

List of Apple-generated location IDs.

Path Template

GET {url}/api/{version}/orgs/{orgId}/matching-locations

Path Example One

Expected to return the identification of all partner location resources matching locations from among all of the organization's brands.

GET {url}/api/v1/orgs/9467895078742654934/matching-locations

Path Example Two

Expected to return the identification of all partner location resources matching locations belonging to one organization's brand.

GET {url}/api/v1/orgs/9467895078742654934/matching-locations?ql=delegatedBrandId==9467895078742654386

Path Example Three

Expected to return the identification of locations from among all the organization's brands which match the listed partner location ids

GET {url}/api/v1/orgs/9467895078742654934/matching-locations?ql=partnerLocationIds=in=(4567345672,9578578654)

Request Headers

Name	Input
Authorization
Accept

Example Request Headers

Authorization: Bearer <access_token>
Accept: application/json

Request Body

None

Response

200 OK or Error

Response Headers

Name
apple-request-id
content-type

Example Response Headers

HTTP/1.1 200 OK
apple-request-id: 6a746899-b067-4193-9b37-0547658ec0ff
content-type: application/json

Response Body

Parent	Name	Output
$.	pagination
$.	total
$.	data[]
data[]	brandId
data[]	id
data[]	orgId
data[]	matches[]

Brand ID

brandId (string) is the Apple-generated ID of the brand that's delegated to you.

ID

data[].id (string) is the Apple-generated location ID associated with delegated brand that system attempted to match.

Org ID

orgId (string) is the Apple-generated ID of the organization that's delegated you.

Matches

matches[] lists one or more matching partner location resources. When the list is not empty, matches[] has these properties:

Parent	Name	Output
matches[]	delegatedOrgId
matches[]	id
matches[]	partnersLocationId

ID

matches[].id (string) is the Apple-generated ID associated with a matching location.

Example Response Bodies

Response to Path Example One

{
  "data": [
    {
      "orgId": "9467895078742654934",
      "brandId": "9467895078742654921",
      "id": "9467895078742654976",
      "matches": [
        {
          "delegatedOrgId": "9467895078742654822",
          "id": "9467895078742654190",
          "partnersLocationId": "1212121212"
        }
      ]
    },
    {
      "orgId": "9467895078742654934",
      "brandId": "9467895078742654921",
      "id": "9467895078742654992",
      "matches": [] /* No match. Partner has no corresponding resource. Or, partner has a resource but it was unsuitable for conflation with a delegated resource. Partner's resource was interpreted to be a different location. May also be referred to as an "under merge." */
    },
    {
      "orgId": "9467895078742654934",
      "brandId": "9467895078742654386",
      "id": "9467895078742654911",
      "matches": [ /* Theoretical scenario where matches[0] references a partner "copy" of a franchise location and matches[1] references a "copy" of a franchisee location. Partner "copies" describe the same place. */
        {
          "delegatedOrgId": "9467895078742654822",
          "id": "9467895078742659200",
          "partnersLocationId": "23232323232"
        },
        {
          "delegatedOrgId": "9467895078742654822",
          "id": "9467895078742651127",
          "partnersLocationId": "979898989898"
        }
      ]
    }
  ],
  "pagination": {},
  "total": 3
}

Response to Path Example Two

{
  "data": [
    {
      "orgId": "9467895078742654934",
      "brandId": "9467895078742654386",
      "id": "9467895078742654911",
      "matches": [  /* Theoretical scenario where matches[0] references a partner "copy" of a franchise location and matches[1] references a "copy" of a franchisee location. Partner "copies" describe the same place. */
        {
          "delegatedOrgId": "9467895078742654822",
          "id": "9467895078742659200",
          "partnersLocationId": "23232323232"
        },
        {
          "delegatedOrgId": "9467895078742654822",
          "id": "9467895078742651127",
          "partnersLocationId": "979898989898"
        }
      ]
    }
  ],
  "pagination": {},
  "total": 1 
}

Response to Path Example Three

Response to path example three. Collection does not include a corresponding match from among any of the organization's brands for partners location ID 9578578654

{
  "data": [
    {
      "orgId": "9467895078742654934",
      "brandId": "9467895078742654386",
      "id": "9467895078742654306",
      "matches": [
        {
          "delegatedOrgId": "9467895078742654822",
          "id": "9467895078742659501",
          "partnersLocationId": "4567345672"
        }
      ]
    }
  ],
  "pagination": {},
  "total": 1
}

When no collection is returned.

Example Response Body Four (raw JSON)

{
  "data": [],
  "pagination": {},
  "total": 1
}