PassportScan External API – Documentation for Multi-Branch Integrations
This guide explains how to enable and use the PassportScan External API, intended for selected customers needing centralized access to guest data across multiple branches, without disrupting PMS integrations.
🔐 APIKey Management
To use the API, each branch must have its own APIKey. These keys allow secure access to data from each individual location.
🔧 How to Generate APIKeys (per branch)
Log into PassportScan Workspace
Go to Branches your current branch settings
In the URL, add /service at the end
Example: https://workspace.passportscan.net/account/1/service
Replace 1 with the actual Branch ID and click "Add New"
Follow the steps on that page to create and manage the APIKey
Whitelist your IP address during APIKey setup.
⚠️ Calls from unauthorized IPs will be rejected for security reasons.
🔐 Authentication
To access the API, a token must be generated using the login endpoint:
Endpoint:
POST https://api.passportscan.net/v1/service/login
Headers:
X-Service: Identity Content-Type: application/json
Body:
{ "public_key": "YOUR_API_KEY", "account_id": "ACCOUNT_ID_PROVIDED_DURING_SETUP" }
The response will include a Bearer token to be used in all subsequent calls.
📅 Get Reservations
This call retrieves reservation data, filtered by arrival_date. The all_customers flag controls whether to return all guests or only those whose data changed since your last query.
Endpoint:
GET https://api.passportscan.net/v1/reservations?arrival_date=YYYY-MM-DD&all_customers=1&pagination[page]=1&pagination[limit]=20
Header:
Authorization: Bearer <YOUR_TOKEN>
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9pZGVudGl0eSIsImF1ZCI6Imh0dHA6XC9cL2lkZW50aXR5IiwiaWF0IjoxNTgxMDkyMjU4LCJuYmYiOjE1ODEwOTIyNTgsImV4cCI6MTU4MzU5Nzg1OCwiMCI6IkF1dGhvcml6YXRpb24iLCJqdGkiOjAsInVzZXJfaWQiOjAsInVzZXJuYW1lIjoiU0VSVklDRV9BQ0NPVU5UIiwiY3VzdG9tZXJfaWQiOjU3LCJhY2NvdW50X2lkIjo2OSwicm9sZXMiOlsiUk9MRV9VU0VSIiwiUk9MRV9MSU5LRURfQlJBTkNIIiwiUk9MRV9TRVJWSUNFIl0sInByb2R1Y3Rfa2V5IjoiYmMwNTM5NDMtMDVjZS00YWZiLTg0MzAtYThkODIzN2M2NzFhIn0.0O7PeZFATu10Ub0dv0pXcGoNCI2VO5UNjF9dW1tgXok Content-Type: application/json
Key parameters:
Parameter | Description |
|---|---|
arrival_date | Reservation arrival date (required) |
all_customers=1 | Returns all guests, even if no changes occurred |
all_customers=0 | Returns only guests whose data changed since last query |
pagination[page] | Pagination index |
pagination[limit] | Results per page (avoid high values to prevent slow response) |
Behavioral Notes:
If all_customers=false, the response only includes reservations or customers that have changed since the last call (e.g. scanned via app, updated via web, etc.)
If a reservation is retrieved, and then a document is scanned for a guest, a second call will return only the updated guest data.
👥 Sample Response
{ "total": 1, "count": 1, "items": [ { "id": 1858, "booking_code": "345", "arrival_date": "2020-02-07", "departure_date": "2020-02-17", "adults": 2, "children": 1, "travel_agency": "East Agency", "daily_rate": null, "group_name": "garbage group", "group_id": null, "room_number": "F57", "room_type": "HIGH", "first_name": "Anthony", "middle_name": "John", "last_name": "Soprano", "customer_reservations": [ { "customer": { "last_document": { "document_type": "IDC", "document_number": "787667789", "personal_number": null, "issue_date": "1999-01-10", "expiration_date": "2013-06-19", "issue_place": "North Caldwell", "issue_province": "Essex County", "issue_country": "USA" }, "last_address": { "address": "Aspen Dr 14", "city": "Caldwell", "province": "Essex County", "region": "NJ", "zip": "07006", "country": "USA" }, "last_contact": { "email": null, "phone": null }, "privacy_flags": { "market_research": null, "third_parties": null, "loyalty_program": null, "promotions": null, "privacy": null, "email": null, "mail": null, "phone": null, "sms": null }, "id": 3263, "first_name": "Anthony", "middle_name": null, "last_name": "Soprano", "birth_date": null, "birth_nation": null, "birth_city": null, "birth_province": null, "gender": "F", "nationality": null, "bad_recognized": null, "pms_guest_id": "343433" }, "is_leader": true, "checkin_time": null }, { "customer": { "last_document": { "document_type": "EXT", "document_number": null, "personal_number": null, "issue_date": null, "expiration_date": null, "issue_place": null, "issue_province": null, "issue_country": null }, "last_address": { "address": null, "city": null, "province": null, "region": null, "zip": null, "country": null }, "last_contact": { "email": null, "phone": null }, "privacy_flags": { "market_research": null, "third_parties": null, "loyalty_program": null, "promotions": null, "privacy": null, "email": null, "mail": null, "phone": null, "sms": null }, "id": 3264, "first_name": "Carmella", "middle_name": null, "last_name": "Soprano", "birth_date": null, "birth_nation": null, "birth_city": null, "birth_province": null, "gender": "F", "nationality": null, "worker_id": 59, "bad_recognized": null, "pms_guest_id": "C349" }, "is_leader": false, "checkin_time": null }, { "customer": { "last_document": { "document_type": "EXT", "document_number": null, "personal_number": null, "issue_date": null, "expiration_date": null, "issue_place": null, "issue_province": null, "issue_country": null }, "last_address": { "address": null, "city": null, "province": null, "region": null, "zip": null, "country": null }, "last_contact": { "email": null, "phone": null }, "privacy_flags": { "market_research": null, "third_parties": null, "loyalty_program": null, "promotions": null, "privacy": null, "email": null, "mail": null, "phone": null, "sms": null }, "id": 3265, "first_name": "Meadow", "middle_name": null, "last_name": "Soprano", "birth_date": null, "birth_nation": null, "birth_city": null, "birth_province": null, "gender": "F", "nationality": null, "worker_id": 59, "bad_recognized": null, "pms_guest_id": "C891" }, "is_leader": false, "checkin_time": null } ], "custom_1": "custom 1", "custom_2": "custom 2", "pms_reservation_id": "AI387F" } ], "_links": { "self": "/v1/reservations?arrival_date=2020-02-07&all_customers=1&pagination[page]=1&pagination[limit]=20", "first": "/v1/reservations?arrival_date=2020-02-07&all_customers=1&pagination[page]=1&pagination[limit]=20", "last": "/v1/reservations?arrival_date=2020-02-07&all_customers=1&pagination[page]=1&pagination[limit]=20" } }
🔄 Coexistence with PMS Integration
The external PassportScan API is fully compatible with active PMS integrations.
✅ API usage does not interfere with data exchanges between PassportScan and your PMS.
You can safely:
Query updated reservation data in real time
Centralize guest data from multiple locations
Automate workflows (e.g. CRM sync, loyalty programs)
Access scanned document fields data via API
All updates via PMS, mobile app, or web will reflect in the API responses.
🛡️ Security & Best Practices
Ensure all APIKeys are properly scoped per branch
Always whitelist IPs that will call the API
Use pagination and limit filters to avoid overload
Store and refresh Bearer tokens securely
Log access for traceability and compliance
If you need assistance enabling this feature or integrating it into your infrastructure, please contact our support@passportscan.net or your PassportScan account manager.
Related Articles
Manual de Configuración del Nuevo Módulo SES Hospedajes en PassportScan
Introducción A partir del 2 de Diciembre de 2024, entra en vigor la integración con el módulo SES Hospedajes según lo establecido en el Real Decreto 933/2021. Este reglamento obliga a todos los negocios de hostelería en España, como hoteles, campings ...Old Passportscan Manuals
1 - Prepare the installation 2 - Installation MySQL 3 - Install PassportScan 4 - Install Wacom Tablet Driver 5 - How to create users 6 - Customize signature text and images 7 - How to display statistics 8 - E-invoice Setting with BullzipLocal Passportscan - Windows Client Installation
WARNING: Use exactly the files we provided, using a newer version of ODBC or Visual C++ could create a malfunction into your Passportscan Client. Files needed: Mandatory Passportscan Classic (Windows Client) MySQL ODBC Connector (You might also need ...Modifica del nominativo nelle prenotazioni multi-camera
Quando abbiamo due camere sotto lo stesso nome, la scansione del documento per la seconda camera sovrascrive il documento precedentemente inserito o già presente nel sistema nel caso di un ospite abituale. Motivo del problema Quando nel gestionale ...Installare PassportScan Cloud su un nuovo PC (Windows Client)
Opzione A (rapida): 1. Scaricare BAT INSTALLER desde https://support.passportscan.net/portal/en/kb/articles/download-client-windows e "Avvia come amministratore". A installazione finita si visualizzerà un messaggio di conferma. 2. Da un altro dei ...