Staging: carrier-integration-api main at 8eb88c7. Carriers do not see this version yet.
GLS/NXT OOH Platform Integration REST API

Locker API

Server

The Locker API endpoints provide comprehensive management of lockers, including their creation, updating, and retrieval. These endpoints support:

  • Locker Creation: Set up new lockers with necessary details such as location, internal carrier IDs, and specific locker features.
  • Locker Information Retrieval: Access detailed information about lockers, including their status and location.
  • Locker Updates: Update existing locker details to reflect changes in status or configuration.

Key Features:

  • Flexible Locker Management: Create and update lockers to keep information current and accurate.
  • Detailed Location Data: Access geographic and logistical details of each locker.
  • Compartment Management: Manage the availability and allocation of compartments within lockers.

Get a list of lockers

GET
https://api.staging.glsnxt.com/ooh/carrier-connector/v1
/lockers

Retrieve a list of lockers with optional filters such as location, status, carrier, and provider.

Get a list of lockers › query Parameters

providerName
​string

Filter lockers by provider name.

status
​status · enum

Filter lockers by status.

Enum values:
ACTIVE
INACTIVE
MAINTENANCE
DECOMMISSIONED
INITIAL
PLANNED
city
​string

Filter lockers by city.

countryCode
​string

Filter lockers by country code (ISO 3166-1 alpha-2).

compartmentSize
​compartment_size · enum

Filter lockers by the size of compartments available.

Locker compartment size.

Enum values:
XXSMALL
XSMALL
SMALL
XMEDIUM
MEDIUM
LARGE
XLARGE
XXLARGE
ownedBy
​boolean

When true, return only the lockers that the carrier owns.

Default: false

Get a list of lockers › Responses

List of lockers retrieved successfully.

uid
​string · required

The internal unique identifier assigned to the locker.

​object · required

The details of the locker on the Carrier's system.

​object · required

The details of the locker on the Provider's system.

​location · required

Details about the geographical location of the locker.

​

Features available in the locker. null when the locker has no feature data.

​opening_hours

Locker availability schedule.

Conditional constraints (enforced server-side, not by the generated client):

  • If accessMode is SCHEDULED, weeklySchedule MUST be provided and non-empty.
  • If accessMode is ALWAYS, weeklySchedule MUST be omitted.
​array | null

Additional metadata associated with the locker. null when the carrier locker has none.

ownedByCarrier
​string | null

Indicates which carrier owns the locker. null means the locker belongs to a 3rd party provider.

​array | null

A list of different compartment types available in the locker.


Create a new locker

POST
https://api.staging.glsnxt.com/ooh/carrier-connector/v1
/lockers

Create a new locker with the specified details for the carrier, provider, location, and features.

Create a new locker › Request Body

​carrier_input · required

The carrier's details for the locker. Requests use these fields in addition to the shared carrier fields.

​provider_input · required

The provider's details for the locker. Requests use these fields in addition to the shared provider fields.

​location · required

Details about the geographical location of the locker.

​metadata_input[]

Additional metadata associated with the locker.

​features

Features available in the locker.

​group[]

Locker groups to assign, identified by key and uid; at most one per type key.

Create a new locker › Responses

Locker created successfully.

uid
​string · required

The internal unique identifier assigned to the locker.

​object · required

The details of the locker on the Carrier's system.

​object · required

The details of the locker on the Provider's system.

​location · required

Details about the geographical location of the locker.

​

Features available in the locker. null when the locker has no feature data.

​opening_hours

Locker availability schedule.

Conditional constraints (enforced server-side, not by the generated client):

  • If accessMode is SCHEDULED, weeklySchedule MUST be provided and non-empty.
  • If accessMode is ALWAYS, weeklySchedule MUST be omitted.
​array | null

Additional metadata associated with the locker. null when the carrier locker has none.

ownedByCarrier
​string | null

Indicates which carrier owns the locker. null means the locker belongs to a 3rd party provider.

​array | null

A list of different compartment types available in the locker.


Update a locker

PATCH
https://api.staging.glsnxt.com/ooh/carrier-connector/v1
/lockers/{uid}

Update the details of an existing locker, including carrier details, provider details, location, and features.

Update a locker › path Parameters

uid
​string · required

The OOH Platform UID for the locker.

Update a locker › Request Body

​carrier_input

The carrier's details for the locker. Requests use these fields in addition to the shared carrier fields.

​location

Details about the geographical location of the locker.

​metadata_input[]

Additional metadata associated with the locker.

​features

Features available in the locker.

​group[]

Locker groups to assign, identified by key and uid; at most one per type key. Omit to leave current groups unchanged.

The provider fields a locker update can change.

Update a locker › Responses

Locker updated successfully.

uid
​string · required

The internal unique identifier assigned to the locker.

​object · required

The details of the locker on the Carrier's system.

​object · required

The details of the locker on the Provider's system.

​location · required

Details about the geographical location of the locker.

​

Features available in the locker. null when the locker has no feature data.

​opening_hours

Locker availability schedule.

Conditional constraints (enforced server-side, not by the generated client):

  • If accessMode is SCHEDULED, weeklySchedule MUST be provided and non-empty.
  • If accessMode is ALWAYS, weeklySchedule MUST be omitted.
​array | null

Additional metadata associated with the locker. null when the carrier locker has none.

ownedByCarrier
​string | null

Indicates which carrier owns the locker. null means the locker belongs to a 3rd party provider.

​array | null

A list of different compartment types available in the locker.


Get lockers by UIDs

GET
https://api.staging.glsnxt.com/ooh/carrier-connector/v1
/lockers/by-uid

Retrieve one or more lockers by their UIDs in a single request.

  • The ids query parameter accepts a comma-separated list of locker UIDs (e.g. ids=10000001,10000002).
  • Maximum 10 UIDs per request — exceeding the limit returns 400.
  • Returns 200 with a JSON array when at least one numeric UID is present; non-existent UIDs, UIDs belonging to other carriers, and non-numeric tokens within a mixed input are silently omitted.
  • Returns 400 when ids is missing, blank, or contains no numeric tokens.

Get lockers by UIDs › query Parameters

ids
​string · minLength: 1 · maxLength: 200 · required

Comma-separated locker UIDs. Up to 10 numeric UIDs per request. Non-numeric tokens within a mixed input are silently dropped before the cap check; an input with no numeric tokens at all returns 400.

Get lockers by UIDs › Responses

List of matching lockers retrieved successfully. Missing or inaccessible UIDs are silently omitted.

uid
​string · required

The internal unique identifier assigned to the locker.

​object · required

The details of the locker on the Carrier's system.

​object · required

The details of the locker on the Provider's system.

​location · required

Details about the geographical location of the locker.

​

Features available in the locker. null when the locker has no feature data.

​opening_hours

Locker availability schedule.

Conditional constraints (enforced server-side, not by the generated client):

  • If accessMode is SCHEDULED, weeklySchedule MUST be provided and non-empty.
  • If accessMode is ALWAYS, weeklySchedule MUST be omitted.
​array | null

Additional metadata associated with the locker. null when the carrier locker has none.

ownedByCarrier
​string | null

Indicates which carrier owns the locker. null means the locker belongs to a 3rd party provider.

​array | null

A list of different compartment types available in the locker.


Get lockers by carrier locker ids

GET
https://api.staging.glsnxt.com/ooh/carrier-connector/v1
/lockers/by-carrier-locker-id

Retrieve one or more lockers by their carrier locker ids in a single request.

  • The ids query parameter accepts a comma-separated list of carrier locker ids (e.g. ids=DE46677,DE12345).
  • Carrier locker ids are alphanumeric and kept as-is — this is exactly the case /lockers/by-uid cannot handle.
  • Maximum 10 ids per request — exceeding the limit returns 400.
  • Returns 200 with a JSON array; non-existent ids and ids belonging to other carriers are silently omitted.
  • Returns 400 when ids is missing, blank, or contains no non-empty tokens.

Get lockers by carrier locker ids › query Parameters

ids
​string · minLength: 1 · maxLength: 200 · required

Comma-separated carrier locker ids. Up to 10 ids per request. Empty tokens are dropped before the cap check; an input with no non-empty tokens returns 400.

Get lockers by carrier locker ids › Responses

List of matching lockers retrieved successfully. Missing or inaccessible carrier locker ids are silently omitted.

uid
​string · required

The internal unique identifier assigned to the locker.

​object · required

The details of the locker on the Carrier's system.

​object · required

The details of the locker on the Provider's system.

​location · required

Details about the geographical location of the locker.

​

Features available in the locker. null when the locker has no feature data.

​opening_hours

Locker availability schedule.

Conditional constraints (enforced server-side, not by the generated client):

  • If accessMode is SCHEDULED, weeklySchedule MUST be provided and non-empty.
  • If accessMode is ALWAYS, weeklySchedule MUST be omitted.
​array | null

Additional metadata associated with the locker. null when the carrier locker has none.

ownedByCarrier
​string | null

Indicates which carrier owns the locker. null means the locker belongs to a 3rd party provider.

​array | null

A list of different compartment types available in the locker.


Get a list of existing locker model and locker version pairs for provider

GET
https://api.staging.glsnxt.com/ooh/carrier-connector/v1
/lockers/providers

Retrieve a list of existing locker model and locker version pairs for each provider.

Get a list of existing locker model and locker version pairs for provider › Responses

List of existing locker model and locker version pairs for each provider retrieved successfully.

​object[]
providerName
​string

The name of the locker provider.

lockerModel
​string

The model of the locker provided by the provider.

lockerVersion
​string

The version of the locker model provided by the provider.

providerUid
​string

The unique identifier of the provider on the GLS/NXT system.


Update Locker Status

PATCH
https://api.staging.glsnxt.com/ooh/carrier-connector/v1
/lockers/status

Update the status of an existing locker.

Update Locker Status › Request Body

lockerUid
​string · required

The unique identifier of the locker in the GLS/NXT Platform

status
​status · enum · required
Enum values:
ACTIVE
INACTIVE
MAINTENANCE
DECOMMISSIONED
INITIAL
PLANNED

Update Locker Status › Responses

Locker status updated successfully.

No data returned