A hub is a physical location (such as a warehouse or store) where parcels are stored until they are ready to be picked up by a driver. You can reference a hub in pickup or drop-off information using its external ID.
openapi: 3.0.0
info:
description: 'Welcome to the Cabify Logistics API. This API allows you to create and manage parcel deliveries, track their status in real time, configure proof of delivery options, and receive live updates via webhooks. All requests must be authenticated using a Bearer token.
'
version: 1.0.0
title: Cabify Logistics delivery hubs API
contact:
email: p.delivery@cabify.com
servers:
- url: https://logistics.api.cabify.com
description: Production
- url: https://logistics.api.cabify-sandbox.com
description: Sandbox
tags:
- name: hubs
description: 'A hub is a physical location (such as a warehouse or store) where parcels are stored until they are ready to be picked up by a driver. You can reference a hub in pickup or drop-off information using its external ID.
'
paths:
/v1/hubs:
get:
tags:
- hubs
summary: List all client hubs.
description: Returns all hubs associated with your account.
responses:
'200':
description: Hubs retrieved successfully.
content:
application/json:
schema:
type: object
description: A collection of client hubs.
required:
- client_hubs
properties:
client_hubs:
type: array
items:
$ref: '#/paths/~1v1~1hubs~1none~1%7Bhub_external_id%7D/get/responses/200/content/application~1json/schema'
security:
- bearer_token: []
post:
tags:
- hubs
summary: Create a new client hub.
description: 'Creates a new hub associated with your account. Hubs represent physical locations (such as stores or warehouses) from which parcels can be picked up or delivered to.
'
requestBody:
content:
application/json:
schema:
type: object
description: Request body for creating a new client hub.
required:
- external_id
- address
properties:
external_id:
type: string
description: A unique identifier you define to reference this hub. This ID is used in parcel pickup and drop-off configurations.
address:
type: string
description: Full street address of the hub.
location:
type: object
description: A geographic coordinate expressed as latitude and longitude.
required:
- lat
- lon
properties:
lat:
type: number
format: float
description: Latitude in decimal degrees.
example: 40.4489254
lon:
type: number
format: float
description: Longitude in decimal degrees.
example: -3.6730293
instructions:
type: string
description: Additional instructions for drivers arriving at this hub (e.g. access codes, gate numbers).
contact:
type: object
description: Primary contact person at this hub.
properties:
name:
type: string
description: Full name of the contact person.
phone:
type: string
description: Phone number of the contact person.
responses:
'200':
description: Hub created successfully.
content:
application/json:
schema:
type: object
description: Response returned after successfully creating a hub.
properties:
id:
type: string
description: System-generated ID of the newly created hub.
example: 4f627a06d74011ec97dd06d73193996d
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
/v1/hubs/none/{hub_external_id}:
get:
tags:
- hubs
summary: Get a client hub by its external ID.
description: Returns the details of a specific hub identified by your external ID.
parameters:
- in: path
name: hub_external_id
description: The external ID you assigned to the hub.
required: true
schema:
type: string
responses:
'200':
description: Hub retrieved successfully.
content:
application/json:
schema:
type: object
description: Full details of a client hub.
properties:
hub_id:
type: string
description: System-generated ID of the hub.
external_id:
type: string
description: Your external ID for this hub.
address:
type: string
description: Full street address of the hub.
location:
$ref: '#/paths/~1v1~1hubs/post/requestBody/content/application~1json/schema/properties/location'
instructions:
type: string
description: Additional instructions for drivers arriving at this hub.
contact:
type: object
description: Primary contact person at this hub.
properties:
name:
type: string
description: Full name of the contact person.
phone:
type: string
description: Phone number of the contact person.
'401':
description: Unauthorized. Missing or invalid authentication token.
'404':
description: No hub found with the given external ID.
security:
- bearer_token: []
put:
tags:
- hubs
summary: Update a client hub by its external ID.
description: Updates the details of a specific hub identified by your external ID.
parameters:
- in: path
name: hub_external_id
description: The external ID you assigned to the hub.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
description: Request body for updating an existing client hub. Only included fields will be modified.
properties:
address:
type: string
description: Updated full street address of the hub.
location:
$ref: '#/paths/~1v1~1hubs/post/requestBody/content/application~1json/schema/properties/location'
instructions:
type: string
description: Updated instructions for drivers arriving at this hub.
contact:
type: object
description: Updated primary contact person at this hub.
properties:
name:
type: string
description: Full name of the contact person.
phone:
type: string
description: Phone number of the contact person.
responses:
'200':
description: Hub updated successfully.
'401':
description: Unauthorized. Missing or invalid authentication token.
security:
- bearer_token: []
/api/v4/hub:
get:
callbacks: {}
description: 'Look up hub meeting-point data for a given set of coordinates.
A **hub** is a large venue (e.g. airport, train station) with designated pick-up/drop-off meeting points. Use this endpoint to determine if a location is within a hub and retrieve the available meeting points.
## Response
- If a hub exists at the given coordinates, returns the hub with its meeting points (uid, title, coordinates, images, and localized instructions).
- If no hub exists or the lookup fails, returns `{ "data": null }`.
## Usage
This endpoint is useful when you want to look up hub data independently from the estimation flow. For example:
1. User enters a pickup address
2. Call this endpoint with the address coordinates
3. If a hub is returned, present the meeting points to the user
4. Include the selected meeting point **and** the hub''s `location_id` in the corresponding stop of the `POST /api/v4/journey` request
> 📘 Hub data in Estimates
>
> Hub data is also returned as part of the `POST /api/v4/estimates` response (best-effort, origin stop only).
> Use this standalone endpoint when you need hub data without creating an estimate, or when the estimate did not resolve hub data in time.
'
operationId: getHub
parameters:
- description: Latitude of the location to look up.
in: query
name: latitude
required: true
schema:
type: number
- description: Longitude of the location to look up.
in: query
name: longitude
required: true
schema:
type: number
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/HubResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedRequest'
description: Unauthorized
summary: Get Hub by coordinates
tags:
- hubs
components:
schemas:
HubObject:
description: A hub is a large venue (e.g. airport, train station) with designated pick-up/drop-off meeting points.
example:
active: true
location_id: location-4
meeting_points:
- bottom_image_url: https://example.com/t1-bottom.png
coordinates:
latitude: 40.4722
longitude: -3.5608
header_image_url: https://example.com/t1-header.png
instructions:
- en: Head to the main gate of Terminal 1
es: Dirígete a la puerta principal de la Terminal 1
step_image_url: https://example.com/step1.png
title:
en: Terminal 1
es: Terminal 1
uid: mp-loc4-1
title:
en: Madrid Barajas
es: Madrid Barajas
uid: hub-loc4
nullable: true
properties:
active:
description: Whether the hub is currently active.
type: boolean
location_id:
description: Location identifier used to look up this hub.
type: string
meeting_points:
description: Designated pick-up/drop-off points within the hub. Present one of these to the user as their boarding location.
items:
properties:
bottom_image_url:
description: URL for the bottom image of the meeting point.
nullable: true
type: string
coordinates:
description: GPS coordinates of the meeting point.
properties:
latitude:
type: number
longitude:
type: number
type: object
header_image_url:
description: URL for the header image of the meeting point.
nullable: true
type: string
instructions:
description: Step-by-step instructions to reach the meeting point.
items:
properties:
en:
type: string
es:
type: string
step_image_url:
nullable: true
type: string
type: object
type: array
title:
additionalProperties:
type: string
description: Localized name of the meeting point, keyed by BCP 47 language tag.
type: object
uid:
description: Unique identifier of the meeting point.
type: string
type: object
type: array
title:
additionalProperties:
type: string
description: Localized name of the hub, keyed by BCP 47 language tag.
type: object
uid:
description: Unique identifier of the hub.
type: string
title: HubObject
type: object
BadRequest:
description: Indicates that the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing).
example:
error: Bad Request error message
properties:
message:
type: string
title: BadRequest
type: object
UnauthorizedRequest:
description: The token used is invalid either because it is expired or because it is incorrect.
example:
error: Unauthorized
properties:
error:
type: string
title: UnauthorizedRequest
type: object
HubResponse:
description: Hub information for a given set of coordinates. Returns null inside the data field when no hub exists at those coordinates.
properties:
data:
$ref: '#/components/schemas/HubObject'
title: HubResponse
type: object
securitySchemes:
bearer_token:
type: http
scheme: bearer