API REFERENCE · V1

Cityflow RESTful API

46 business and table endpoints, 20 external integrations and 70 service calls. Everything you need to connect Cityflow Fleet OS with your PMS, ERP or own application.

REST · JSON Bearer auth Sandbox · Mock Data

General information

Base URL (test)https://pruebas.cityflow.app/api/v1/

Base URL (production)https://{tu-instalacion}/api/v1/

MethodPOST (body JSON)

AuthenticationAuthorization: Bearer [API_KEY] — required on every endpoint

Content-Typeapplication/json

Restricted access

All 46 endpoints require an API key provided when you subscribe to the Cityflow software. Without it, the platform responds 401 Unauthorized and no data is exposed.

Mock Data (sandbox)

In this phase, responses are simulated (static payloads with HTTP 200 OK) to validate the JSON contract structure. All identifiers, emails and figures in the examples are fictitious.

OpenAPI 3.1 specification

This reference is generated from the platform's OpenAPI contract. Download it and import it into Postman, generate a client in your language, or spin up a mock server with it.

Download YAML Download JSONcurl -O https://cityflow.app/openapi/cityflow-v1.yaml

Standard response format

{
  "status": "success",
  "code": 200,
  "data": { ... },
  "meta": {
    "api_version": "v1",
    "environment": "sandbox",
    "mock_data": true
  }
}

Public Sharing — Urban micromobility

Public shared-fleet operations: operating zones, geofencing, per-minute fares and vehicle telemetry.

POST/calculate_trip_fare

Calculates a trip fare based on vehicle type and duration in minutes.

Parameters (JSON body)

Parameter	Type	Required
vehicle_type*	string	Yes
duration_minutes*	number	Yes
city_id	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/calculate_trip_fare' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"vehicle_type": "<valor>", "duration_minutes": 0}'

POST/get_operating_zones

Returns a city's operating zones and geofencing rules.

Parameters (JSON body)

Parameter	Type	Required
city_id*	string	Yes
zone_type	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/get_operating_zones' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"city_id": "<valor>"}'

POST/get_vehicles_status

Real-time fleet status: availability, battery and GPS location.

Parameters (JSON body)

Parameter	Type	Required
city_id*	string	Yes
status_filter	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/get_vehicles_status' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"city_id": "<valor>"}'

Corporate Sharing — Private corporate fleets

Private fleets for companies: registration with corporate domain validation, campus reservations and per-department permissions.

POST/create_campus_reservation

Creates a vehicle reservation inside a corporate campus.

Parameters (JSON body)

Parameter	Type	Required
employee_id*	string	Yes
campus_id*	string	Yes
vehicle_type	string	No
start_time	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/create_campus_reservation' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"employee_id": "<valor>", "campus_id": "<valor>"}'

POST/register_corporate_user

Registers a corporate user, validating that the email belongs to the company domain (@company.com).

Parameters (JSON body)

Parameter	Type	Required
email*	string	Yes
company_id*	string	Yes
full_name	string	No
department	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/register_corporate_user' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"email": "<valor>", "company_id": "<valor>"}'

POST/set_employee_permissions

Assigns fleet usage permissions by department or employee profile.

Parameters (JSON body)

Parameter	Type	Required
employee_id*	string	Yes
department	string	No
profile	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/set_employee_permissions' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"employee_id": "<valor>"}'

Rental & Tourist — Rentals and tourism

Advance bookings, day/week tourist passes and the full check-in / check-out cycle.

POST/cancel_booking

Cancels an advance booking.

Parameters (JSON body)

Parameter	Type	Required
booking_id*	string	Yes
reason	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/cancel_booking' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"booking_id": "<valor>"}'

POST/create_advance_booking

Creates an advance rental booking (short or long term).

Parameters (JSON body)

Parameter	Type	Required
customer_email*	string	Yes
property_id*	string	Yes
start_date*	string	Yes
end_date	string	No
bike_quantity	number	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/create_advance_booking' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"customer_email": "<valor>", "property_id": "<valor>", "start_date": "<valor>"}'

POST/get_booking

Retrieves the details of an existing booking.

Parameters (JSON body)

Parameter	Type	Required
booking_id*	string	Yes

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/get_booking' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"booking_id": "<valor>"}'

POST/purchase_tourist_pass

Sells a tourist pass per day or per week.

Parameters (JSON body)

Parameter	Type	Required
pass_type*	string	Yes
customer_email*	string	Yes
start_date	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/purchase_tourist_pass' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"pass_type": "<valor>", "customer_email": "<valor>"}'

POST/rental_checkin

Rental check-in: vehicle handover and unlock code.

Parameters (JSON body)

Parameter	Type	Required
booking_id*	string	Yes
bike_id	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/rental_checkin' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"booking_id": "<valor>"}'

POST/rental_checkout

Rental check-out: vehicle return and settlement.

Parameters (JSON body)

Parameter	Type	Required
booking_id*	string	Yes

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/rental_checkout' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"booking_id": "<valor>"}'

POST/validate_tourist_pass

Validates a tourist pass and returns its remaining validity.

Parameters (JSON body)

Parameter	Type	Required
pass_code*	string	Yes

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/validate_tourist_pass' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"pass_code": "<valor>"}'

Franchises & Multi-property — Multi-city and franchises

Master panel for centralized supervision and metrics segmented by franchise or property.

POST/get_franchise_metrics

Metrics segmented by franchise or property, with period and metric-type filters.

Parameters (JSON body)

Parameter	Type	Required
franchise_id*	string	Yes
metric_type	string	No
period	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/get_franchise_metrics' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"franchise_id": "<valor>"}'

POST/get_master_overview

Master panel: centralized supervision of all fleets, cities and franchises.

Parameters (JSON body)

Parameter	Type	Required
period	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/get_master_overview' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"period": "<valor>"}'

Internal management

Platform administration operations: bike and hotel registration, per-hotel pricing and fleet statuses.

POST/create_bike

Registers a bike in the system (equivalent to the internal admin page workflow).

Parameters (JSON body)

Parameter	Type	Required
bike_name*	string	Yes
bike_model	string	No
hotel_id	string	No
lock_type	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/create_bike' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"bike_name": "<valor>"}'

POST/create_hotel

Registers a hotel/property on the platform.

Parameters (JSON body)

Parameter	Type	Required
hotel_name*	string	Yes
city*	string	Yes
contact_email	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/create_hotel' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"hotel_name": "<valor>", "city": "<valor>"}'

POST/set_hotel_prices

Sets a hotel's specific rental prices.

Parameters (JSON body)

Parameter	Type	Required
hotel_id*	string	Yes
price_per_hour	number	No
price_per_day	number	No
currency	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/set_hotel_prices' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"hotel_id": "<valor>"}'

POST/update_bike_status

Changes a bike's operational status (available, rented, maintenance).

Parameters (JSON body)

Parameter	Type	Required
bike_id*	string	Yes
status*	string	Yes
notes	string	No

curl -X POST \
  'https://pruebas.cityflow.app/api/v1/update_bike_status' \
  -H 'Authorization: Bearer [API_KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"bike_id": "<valor>", "status": "<valor>"}'

Table API — field-by-field updates

Every platform table has its own update_* endpoint. They all work the same way:

The record is identified with record_id (required).
All other parameters are optional: only the fields included in the request are modified.
References to other tables are sent as their unique id; dates in ISO 8601; files as URLs.
Purely internal system tables are managed automatically and are not exposed in the API.

External integrations — API Connector

The platform connects to these external services through the API Connector. All calls run server-side: credentials (API keys, tokens, accounts) are configured as private parameters and are never exposed to the browser or in this documentation. For each call we list the method, the resource and the public parameters, along with an explanation of what it does.

Backend

1 calls

Auxiliary calls to the platform's own backend (business case calculations, e.g. number of rentals).

Call	Method & resource	What it does
Business Case - número alquileres	POST`[host]/version-test/api/1.1/wf/calcular_alquileres`	Calculates the estimated number of rentals for the business case.

Brevo

5 calls

Transactional email provider. Sends the platform's operational emails: confirmations, internal alerts and app emails (with or without CC).

Call	Method & resource	What it does
API Call	GET`—`	Generic group call (auxiliary configuration).
Send Alert Email	POST`api.brevo.com/v3/smtp/email`	Sends an internal alert email to the operations team.
Send App Email	POST`api.brevo.com/v3/smtp/email`	Sends an application email to the customer.
Send App Email (with CC)	POST`api.brevo.com/v3/smtp/email`	Sends an application email with CC recipients.
Send Email	POST`api.brevo.com/v3/smtp/email`	Sends a transactional email through Brevo.

Buildprint API

1 calls

Buildprint integration to launch automated agents (e.g. the news agent).

Call	Method & resource	What it does
Trigger Novedades Agent	POST`api.buildprint.ai/api/public/v1/agents`	Launches the automated news agent.

Clone

2 calls

Internal data cloning/migration utilities between environments (get a hotel and create records).

Call	Method & resource	What it does
Create thing	POST`[host]/version-test/api/1.1/obj/[Type]`	Creates a record via the Data API (cloning utility).
Get Hotel	GET`[host]/version-test/api/1.1/obj/[Type]/[id]`	Retrieves a hotel's data (cloning utility).

Gemini AI

1 calls

Google generative AI. Used to automatically generate probable breakdown causes from the incident description.

Call	Method & resource	What it does
Generate Causes	POST`generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent`	Uses AI to generate the probable causes of a breakdown.

GPS

3 calls

External GPS tracking platform: authentication, device listing and position data reading for each tracker.

Call	Method & resource	What it does
Device Data	GET`[host]/fit/deviceData`	Gets the position and telemetry data of a specific tracker.
List Devices	GET`[host]/fit/share/deviceandShareDeviceList`	Lists the GPS trackers registered on the account.
Login	POST`[host]/fit/registerOrlogin`	Authenticates against the GPS platform and obtains the session token.

Holded

7 calls

Billing ERP. Manages contacts, invoices, sales receipts, payments and document delivery.

Call	Method & resource	What it does
Create Contact	POST`api.holded.com/api/invoicing/v1/contacts`	Creates a contact (customer) in Holded.
Create Invoice	POST`api.holded.com/api/invoicing/v1/documents/invoice`	Creates an invoice in Holded.
Create Sales Receipt	POST`api.holded.com/api/invoicing/v1/documents/salesreceipt`	Creates a sales receipt in Holded.
Delete Recurring Invoice	DELETE`api.holded.com/api/invoicing/v1/documents/invoicerecurring/[documentId]`	Deletes a recurring invoice in Holded.
Pay Document	POST`api.holded.com/api/invoicing/v1/documents/[docType]/[documentId]/pay`	Marks a Holded document as paid.
Pay Invoice	POST`api.holded.com/api/invoicing/v1/documents/invoice/[documentId]/pay`	Marks a Holded invoice as paid.
Send Invoice	POST`api.holded.com/api/invoicing/v1/documents/invoice/[documentId]/send`	Emails a Holded invoice to the customer.

Holded v2

1 calls

Second version of the Holded integration, dedicated to recurring invoices.

Call	Method & resource	What it does
Create Recurring Invoice	POST`api.holded.com/api/v2/recurring-invoices`	Creates a recurring invoice in Holded.

KeySafe-Cloud API

2 calls

KeySafe smart key locks: claim ownership of a lock and manage electronic key slots (eKeys).

Call	Method & resource	What it does
API Call	PUT`keysafe-cloud.appspot.com/api/v1/locks/[lock_id]/slots/[slot_number]`	Generic group call (auxiliary configuration).
Claim a Lock	POST`keysafe-cloud.appspot.com/api/v1/locks`	Claims ownership of a KeySafe lock in the cloud.

LINKA API

1 calls

LINKA smart locks: query lock information and status.

Call	Method & resource	What it does
Fetch Lock Info	POST`app.linkalock.com/api/merchant_api/fetch_lock`	Queries a LINKA lock's information and status.

New Collection

1 calls

Generic unconfigured call group (API Connector placeholder).

Call	Method & resource	What it does
API Call	GET`[host]/status/[device_id]`	Generic group call (auxiliary configuration).

New Collection

1 calls

Generic unconfigured call group (API Connector placeholder).

Call	Method & resource	What it does
API Call	GET`—`	Generic group call (auxiliary configuration).

Omni API

15 calls

Cityflow's own gateway for Omni smart locks. It is the core of remote fleet control: lock/unlock, battery, alarm, lights, speed and GPS.

Call	Method & resource	What it does
Accelerometer	POST`[host]/accelerometer/[lock_id]/[low/medium/high]`	Adjusts accelerometer sensitivity (low/medium/high) for motion detection.
All bikes status	GET`[host]/status`	Queries the status of every lock in the fleet in a single call.
GPS API	POST`[host]/gps/[id]`	Requests the device's current GPS position.
Kick	POST`[host]/kick/[lock_id]`	Forces a restart/reconnection of the lock device.
Lock	POST`[host]/lock/[lock_id]`	Remotely locks the vehicle's lock.
Lock Battery	POST`[host]/lock-battery/[lock_id]`	Locks the battery compartment.
Luces	POST`[host]/headlight/[lock_id]/[on/off]`	Turns the vehicle lights on or off.
Sound Alarm	POST`[host]/beep/[lock_id]/find`	Sounds the lock alarm to locate the vehicle.
Status	GET`[host]/status/[lock_id]`	Queries a lock's real-time status (closure, battery, connectivity).
Unlock	POST`[host]/unlock/[lock_id]`	Remotely unlocks the vehicle's lock.
Unlock Battery	POST`[host]/unlock-battery/[lock_id]`	Unlocks the battery compartment.
speed mode	POST`[host]/speed-mode/[lock_id]/[low/medium/high]`	Changes the vehicle's speed mode (low/medium/high).
speed-limit	POST`[host]/speed-limit/[lock_id]/medium/[speed-limit]`	Sets the vehicle's speed limit.
startup-mode	POST`[host]/startup-mode/[lock_id]/[zero/non-zero]`	Configures the vehicle's start mode (zero start / non-zero start).
throttle	POST`[host]/throttle/[lock_id]/[on/off]`	Enables or disables the vehicle throttle.

Ortizma

3 calls

Ortizma locks managed through Cityflow's lock gateway: device status, auto-lock and location resolution.

Call	Method & resource	What it does
Get Device Status	GET`[host]/v2/devices/[id]/status`	Queries the Ortizma device status.
Resolve Location	POST`[host]/v2/devices/[id]/location/resolve`	Requests resolution of the device's current location.
Set Autolock	POST`[host]/v2/devices/[id]/autolock`	Configures lock auto-lock after a period of inactivity.

Rapiwha

1 calls

Former WhatsApp messaging provider (deprecated, replaced by WasenderAPI).

Call	Method & resource	What it does
(old) Enviar whatsapp	POST`panel.rapiwha.com/send_message.php`	Old version of WhatsApp sending (deprecated).

ShortPixel

1 calls

Image optimization service: compresses and reduces the size of uploaded photos.

Call	Method & resource	What it does
Reduce	POST`api.shortpixel.com/v2/reducer.php`	Compresses an image to reduce its size.

Stripe API

21 calls

Payment gateway. Manages the full billing cycle: checkout sessions, customers, saved payment methods, off-session charges, subscriptions and invoices.

Call	Method & resource	What it does
API Call	GET`—`	Generic group call (auxiliary configuration).
Charge a saved card (off‑session)	POST`api.stripe.com/v1/payment_intents`	Charges a saved card without the customer being present (off-session).
Charge customer saved payment method	POST`api.stripe.com/v1/payment_intents`	Charges the customer using their saved payment method.
Checkout Session for Alipay and WeChatPay	POST`api.stripe.com/v1/checkout/sessions`	Creates a checkout session with Asian payment methods (Alipay/WeChat Pay).
Checkout hora extra	POST`api.stripe.com/v1/checkout/sessions`	Charges an extra rental hour via checkout.
Checkout session	POST`api.stripe.com/v1/checkout/sessions`	Creates a Stripe Checkout payment session.
Checkout session - Subscription	POST`api.stripe.com/v1/checkout/sessions`	Creates a checkout session for a subscription.
Checkout session status	GET`api.stripe.com/v1/checkout/sessions/[session_id]`	Queries the status of a checkout session.
Create Stripe Customer (Step 1 store payment information)	POST`api.stripe.com/v1/customers`	Creates the customer in Stripe as the first step to save their payment method.
Create invoice (charge automatically)	POST`api.stripe.com/v1/invoices`	Creates an auto-charge invoice.
Create invoice item (impago difference)	POST`api.stripe.com/v1/invoiceitems`	Adds an invoice line to settle unpaid balance differences.
Finalize invoice	POST`api.stripe.com/v1/invoices/[invoice_id]/finalize`	Finalizes a draft invoice to issue it.
Find the Customer by email	GET`api.stripe.com/v1/customers`	Looks up a Stripe customer by email.
List PaymentMethods for that Customer	GET`api.stripe.com/v1/payment_methods`	Lists a customer's saved payment methods.
Pay invoice (off session)	POST`api.stripe.com/v1/invoices/[invoice_id]/pay`	Charges an invoice without the customer being present.
Retrieve invoice	GET`api.stripe.com/v1/invoices/[id]`	Retrieves a Stripe invoice.
Retrieve subscription	GET`api.stripe.com/v1/subscriptions/[subscription_id]`	Retrieves a Stripe subscription's data.
Set default payment method (customer)	POST`api.stripe.com/v1/customers/[Customer_ID]`	Sets the customer's default payment method.
Stripe – Retrieve PI	GET`api.stripe.com/v1/payment_intents/[PI_ID]`	Retrieves a PaymentIntent to check a charge's status.
Update customer (not being used)	POST`api.stripe.com/v1/customers/[id]`	Updates a customer's data (deprecated call).
Update rider subscription	POST`api.stripe.com/v1/subscriptions/[subscription_id]`	Updates a rider's subscription.

WasenderAPI

1 calls

Current WhatsApp messaging provider for customer notifications.

Call	Method & resource	What it does
Enviar whatsapp	POST`www.wasenderapi.com/api/send-message`	Sends a WhatsApp message to the customer.

1 calls

Generic WhatsApp call (auxiliary configuration).

Call	Method & resource	What it does
API Call	POST`graph.facebook.com/v20.0/[device_id]/messages`	Generic group call (auxiliary configuration).

WhatsApp Meta

1 calls

Official WhatsApp Business API (Meta): sends template messages, such as the booking start notice.

Call	Method & resource	What it does
Send Reservation Start Message	POST`graph.facebook.com/v19.0/YOUR_PHONE_NUMBER_ID/messages`	Sends the booking start template message via WhatsApp (Meta).

Cityflow RESTful API

General information

Public Sharing — Urban micromobility

Corporate Sharing — Private corporate fleets

Rental & Tourist — Rentals and tourism

Franchises & Multi-property — Multi-city and franchises

Internal management

Table API — field-by-field updates

External integrations — API Connector

Backend

Brevo

Buildprint API

Clone

Gemini AI

GPS

Holded

Holded v2

KeySafe-Cloud API

LINKA API

New Collection

New Collection

Omni API

Ortizma

Rapiwha

ShortPixel

Stripe API

WasenderAPI

Whatsapp

WhatsApp Meta