Skip to main content

Location Management API

Version 1.0 — May 2025

Authentication - Login API

To access the GraphQL APIs, users must first authenticate using the Xemelgo Login REST API.

Endpoint Details

  • URL: https://rest.api.xemelgo.com/login
  • Method: POST

Properties

PropertyTypeDescriptionRequired
emailStringbase64 Encoded email id for userYes
passwordStringbase64 encoded password for userYes

Password needs to be a minimum of 8 characters and should have a number in it.

Request Body

{
"email": "base64_encoded_email",
"password": "base64_encoded_password"
}

StatusCode - 200 on success

Response Body

{
"AccessToken": "$accessToken",
"ExpiresIn": 480,
"TokenType": "Bearer",
"RefreshToken": "$refreshToken",
"IdToken": "$idToken"
}

Use the $idToken as the authorization header for all API requests.

Errors

ErrorError codeException
In correct username and/or password400NotAuthorizedException

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

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

For Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

For Invalid Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

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

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

For Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

For Invalid Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

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

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

For Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

For Invalid Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

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

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

For Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

For Invalid Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

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

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

For Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

For Invalid Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

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

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

For Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

For Invalid Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

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

ErrorError codeException
Expired token401Unauthorized
Invalid token401Unauthorized
Missing Authorization Header401Unauthorized

For Expired Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Token has expired."
}
]
}

For Invalid Token

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "Unable to parse JWT token"
}
]
}

Missing Authorization Header

{
"errors": [
{
"errorType": "UnauthorizedException",
"message": "User is not authorized to make this call."
}
]
}

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": []
}
]
}