Skip to main content

Location Management API

Version 1.0 — May 2025

Authentication: All requests require an IdToken from the Login API. See Authentication to obtain one and Errors for authorization errors.

Get Location Roles API​

For the items moving to a location either by a reader detection or user transaction, to perform the right action on the item at a location, a location role should be assigned to the location. There is a pre-defined list of location roles that the user can choose from and assign to the location.

This API allows to query the list of Location Roles that can be assigned to a location.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescription
idStringUnique identifier of the location role that will be referred to by createLocation API
nameStringUser friendly name of the location role
descriptionStringDescription of the location role

Headers

Authorization – $idToken

Request Body​

query locationRoles {
locationRoles {
roles {
id
name
description
}
}
}

Status Code - 200

Response Body​

The response consists of a list of all the locationRoles.

{
"data": {
"locationRoles": {
"roles": [
{
"id": "RFID Stock Room",
"name": "RFID Stock Room",
"description": null
},
{
"id": "Enter and Exit",
"name": "Enter and Exit",
"description": null
}
]
}
}
}

Errors​

See authorization errors.


Get Location Categories API​

When creating a location, the category should be specified to determine at what level in the hierarchy the location will be created. Location category is a required field when creating a location. The category is a pre-defined list configured during tenant setup.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescription
idStringUnique identifier of the location category that will be referred to by createLocation API
parentCategoryIdStringThe category identifier for the parent.
childCategoryIdsStringThe category identifier of all the child categories in the hierarchy

Headers

Authorization – $idToken

Request Body​

query locationCategories {
locationCategories {
categories {
id
parentCategoryId
childCategoryIds
}
}
}

Status Code - 200

Response Body​

Response consists of a list of all the locationRoles.

{
"data": {
"locationCategories": {
"categories": [
{
"id": "Facility",
"parentCategoryId": null,
"childCategoryIds": ["Stock Area"]
}
]
}
}
}

Errors​

See authorization errors.


Get Customers API​

Get a list of all the locations, its category, location role and assigned customers to the location.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Request Properties​

PropertyTypeDescriptionRequired
filterStringFilter results on location propertiesNo
nextTokenStringIf the request requires multiple pages to complete, provide the nextToken from the previous request’s response to get the next pageNo

Response Properties​

PropertyTypeDescription
idStringUnique identifier for the customer which will be referred by createLocation API
nameStringDisplay name for the customer
descriptionStringDescription for the customer
customPropertiesAWSJSONAdditional properties that a customer may have specified for the customer

Filter Field Examples​

  • Find item with a specific id Customer 2:

    filter: "id == \"Customer 2\""
  • To find an item whose id starts with the prefix Customer_:

    filter: "id ~= \"$Customer_\""

Headers

Authorization – $idToken

Request Body​

query customers($filter: String, $nextToken: String) {
customers(input: { filter: $filter, nextToken: $nextToken }) {
nextToken
customers {
id
name
description
customProperties
}
}
}

Status Code - 200

Response Body​

{
"data": {
"customers": {
"nextToken": null,
"customers": [
{
"id": "Seattle Children's Hospital",
"name": "Seattle Children's Hospital",
"description": null,
"customProperties": "{}"
},
{
"id": "Customer 1",
"name": "230118",
"description": "Customer 1",
"customProperties": "{}"
},
{
"id": "Customer 2",
"name": "231609",
"description": "Customer 2",
"customProperties": "{}"
}
]
}
}
}

Response consists of a list of all customers.

Errors​

See authorization errors.

Additional 200-Level Errors​

Error TypeError Code
Filter Error200
Invalid Token Error200

Filter error example:​

{
"data": {
"customers": null
},
"errors": [
{
"path": ["customers"],
"data": null,
"errorType": "FilterError",
"errorInfo": null,
"locations": [
{
"line": 57,
"column": 3,
"sourceName": null
}
],
"message": "Error: Lexical error on line 1. Unrecognized text.\nid === \"1234\"\n-----^"
}
]
}

Invalid token error example:​

{
"data": {
"customers": null
},
"errors": [
{
"path": ["customers"],
"data": null,
"errorType": "Error",
"errorInfo": null,
"locations": [
{
"line": 57,
"column": 3,
"sourceName": null
}
],
"message": "Invalid token"
}
]
}

Get Locations API​

Get a list of all the locations, its category, location role and assigned customers to the location.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Request Properties​

PropertyTypeDescriptionRequired
filterStringFilter results on location propertiesNo
nextTokenStringIf the request requires multiple pages to complete, provide the nextToken from the previous request’s response to get the next pageNo

Response Properties​

PropertyTypeDescription
idStringUnique identifier for the location
nameStringDisplay name of the location
descriptionStringLocation description
categoryIdStringCategory the location belongs to
roleIdStringLocation role assigned to the location
parentLocationIdStringParent Location Identifier if any
childLocationIds[String]List of locationIds under this location

Filter Field Examples​

  • Find item with a specific ID (ITEM_1234):

    filter: "id == \"ITEM_1234\""
  • To find an item whose id starts with the prefix ITEM_:

    filter: "id ~= \"$ITEM_\""
  • To find items created after the timestamp 1709254800000:

    filter: "creationDate > 1709254800000"

Headers

Authorization – $idToken

Request Body​

query locations($filter: String, $nextToken: String) {
Locations(input: { filter: $filter, nextToken: $nextToken }) {
locations {
id
name
description
categoryId
parentLocationId
childLocationIds
}
}
}

Status Code - 200

Response Body​

{
"data": {
"locations": {
"locations": [
{
"id": "Receiving",
"name": "Receiving",
"description": null,
"categoryId": "Department",
"parentLocationId": "Test Facility",
"roleId": "RFID Spoke",
"childLocationIds": []
},
{
"id": "Shipping",
"name": "Shipping",
"description": null,
"categoryId": "Department",
"parentLocationId": "Test Facility",
"roleId": "RFID Hub",
"childLocationIds": []
},
{
"id": "Warehouse",
"name": "Warehouse",
"description": "",
"categoryId": "Department",
"roleId": "RFID Stock Room",
"parentLocationId": "Test Facility",
"childLocationIds": []
},
{
"id": "Test Facility",
"name": "Test Facility",
"description": "Test Facility",
"categoryId": "Facility",
"customerId": null,
"roleId": null,
"parentLocationId": null,
"childLocationIds": ["Receiving", "Shipping", "Warehouse"]
}
]
}
}
}

Errors​

See authorization errors.

Additional 200-Level Errors​

Error TypeError Code
Filter Error200
Invalid Token Error200

Filter error example:​

{
"data": {
"customers": null
},
"errors": [
{
"path": ["customers"],
"data": null,
"errorType": "FilterError",
"errorInfo": null,
"locations": [
{
"line": 57,
"column": 3,
"sourceName": null
}
],
"message": "Error: Lexical error on line 1. Unrecognized text.\nid === \"1234\"\n-----^"
}
]
}

Invalid token error example:​

{
"data": {
"customers": null
},
"errors": [
{
"path": ["customers"],
"data": null,
"errorType": "Error",
"errorInfo": null,
"locations": [
{
"line": 57,
"column": 3,
"sourceName": null
}
],
"message": "Invalid token"
}
]
}

Create Locations API​

Create Locations API allows to create one or multiple locations and build a hierarchy of locations where the items will be tracked at.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
idStringUnique identifier for the location that will be used for all future transactionsYes
categoryIdStringPre-defined category to ensure right grouping of the location.Yes
customerIdStringPre-created customer identifier assigned to the location.No
roleIdStringIdentifier of the role that should be assigned to the location.No
descriptionStringDescription of the locationNo
nameStringUser friendly name of the location for display purposesNo
parentLocationIdStringIdentifier of the parent location to create the hierarchyNo
customPropertiesAWSJSONAdditional properties that a customer may want to specify for the locationNo

Headers

Authorization – $idToken

Request Body​

Input can consist of multiple JSON objects of unique items.

mutation {
createLocations(
input: {
locations: [
{
id: "location 2"
categoryId: "Stock Room"
parentLocationId: "U360"
roleId: "RFID Spoke"
customerId: "customer 1"
}
]
}
) {
locationIds
}
}

Status Code - 200

Response Body​

{
"data": {
"createInventory": {
"locationIds": ["location 2"]
}
}
}

Response consists of a list of all inventory item that were created.

Errors​

See authorization errors.


Update Locations API​

Updates one or more location records in the system with new information such as parent location, role, customer, etc.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
idStringThe unique identifier of the location to update.Yes
updatesLocationUpdatesAn object containing the fields to update for the specified location.Yes

Location Updates Properties​

PropertyTypeDescriptionRequired
descriptionStringDescription of the locationNo
nameStringUser friendly name of the location for display purposesNo
customerIdStringThe identifier for the customer this location belongs toNo
roleIdStringThe updated role identifier for the location, e.g., "RFID Stock Room", "RFID Spoke", "RFID Hub"No
parentLocationIdStringThe new parent location's ID. This establishes a hierarchy between locations.No
customPropertiesAWSJSONAdditional properties that a customer may want to specify for the locationNo

Headers

Authorization – $idToken

Request Body​

Input can consist of multiple JSON objects of unique items.

mutation {
updateLocations(
input: {
locations: [
{
id: "location 2"
updates: {
parentLocationId: "parent location 1"
roleId: "RFID Stock Room"
customerId: "other customer"
}
}
]
}
) {
locations {
id
customerId
roleId
parentLocationId
categoryId
childLocationIds
}
}
}

Status Code - 200

Response Body​

{
"data": {
"updateLocations": {
"locations": [
{
"id": "location 2",
"customerId": "other customer",
"roleId": "RFID Stock Room",
"parentLocationId": "parent location 1",
"categoryId": "Stock Room",
"childLocationIds": []
}
]
}
}
}

Response consists of a list of updated inventory item with updated properties.

Errors​

See authorization errors.


Delete Locations API​

Delete Locations API allows you to permanently delete one or more location records from the system.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
locationIds[String]List of location IDs to be deleted.Yes

Headers –
Authorization – $idToken

Request Body​

mutation deleteLocations {
deleteLocations(input: { locationIds: ["U123"] }) {
locationIds
}
}

StatusCode - 200

Response Body​

{
"data": {
"deleteLocations": {
"locationIds": ["U123"]
}
}
}

Response consists of a list of all location IDs that were deleted.

Errors​

See authorization errors.

Additional 200-Level Errors​

ErrorError code
Locations not found200

Locations Not Found​

{
"data": {
"deleteLocations": {
"locationIds": []
}
},
"errors": [
{
"path": ["deleteLocations"],
"data": null,
"errorType": "ResourceNotFoundError",
"errorInfo": null,
"locations": [
{
"line": 2,
"column": 3,
"sourceName": null
}
],
"message": "Locations not found: U123"
}
]
}

Location Management Postman Collection​

{
"info": {
"_postman_id": "a79d0bd1-a2dd-4f84-a077-a8ecf7134247",
"name": "Locations API collection",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_exporter_id": "14257901"
},
"item": [
{
"name": "list location roles",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Tenant",
"value": "{{customerId}}",
"type": "text",
"disabled": true
},
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "query locationRoles {\n locationRoles {\n roles {\n id\n name\n description \n }\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "list location categories",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Tenant",
"value": "{{customerId}}",
"type": "text",
"disabled": true
},
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "query locationCategories {\n locationCategories {\n categories {\n id\n parentCategoryId\n childCategoryIds\n }\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "list customers",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Tenant",
"value": "{{customerId}}",
"type": "text",
"disabled": true
},
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "query customers ($filter: String, $nextToken: String) {\n customers(input: { filter: $filter, nextToken: $nextToken }) {\n nextToken\n customers {\n id\n name\n description\n customProperties\n }\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "list locations",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Tenant",
"value": "{{customerId}}",
"type": "text",
"disabled": true
},
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "query locations ($filter: String, $nextToken: String) {\n locations(input: { filter: $filter, nextToken: $nextToken }) {\n locations {\n id\n name\n description\n categoryId\n parentLocationId\n childLocationIds\n }\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "create locations",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Tenant",
"value": "{{customerId}}",
"type": "text"
},
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "mutation {\n createLocations(\n input: {\n locations: [\n {\n id: \"location 2\",\n categoryId: \"Stock Room\"\n parentLocationId: \"parent location\"\n roleId: \"RFID Stock Room\"\n customerId: \"customer 1\"\n }\n ]\n }) {\n locationIds\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "update locations",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Tenant",
"value": "{{customerId}}",
"type": "text"
},
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "mutation {\n updateLocations(input: {\n locations: [ \n {\n id: \"location 2\",\n updates: {\n parentLocationId: \"parent location\"\n roleId: \"RFID Stock Room\"\n customerId: \"other customer\"\n }\n }\n ]\n }) {\n locations {\n id\n customerId\n roleId\n parentLocationId\n categoryId\n childLocationIds\n }\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
}
]
}