API Reference

API endpoints for managing travelers, passports, and documents.

All endpoints require authentication. Admin endpoints require appropriate admin permissions.

Traveler Endpoints

List Travelers (Admin)

GET /api/admin/travelers

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`perPage`	number	Items per page (default: 10)
`search`	string	Search by name, email, phone, passport
`companyId`	string	Filter by company
`travelerType`	string	Filter by type (ADT, CHD, INF)
`sortBy`	string	Sort field (createdAt, firstName, lastName)
`sortOrder`	string	Sort direction (asc, desc)

Response:

{
  "status": "success",
  "data": [
    {
      "id": "clx123...",
      "userId": "clx456...",
      "title": "mr",
      "firstName": "John",
      "lastName": "Smith",
      "emailAddress": "john@example.com",
      "phone": "+9647701234567",
      "birthDate": "1990-05-15T00:00:00.000Z",
      "age": 35,
      "travelerType": "ADT",
      "passports": [...],
      "user": {...},
      "_count": { "documents": 3 }
    }
  ],
  "total": 150,
  "page": 1,
  "perPage": 10
}

Get Traveler (Admin)

GET /api/admin/travelers/:id

Response: Single traveler object with full details.

Create Traveler (Admin)

POST /api/admin/travelers

Request Body:

{
  "userId": "clx456...",
  "title": "mr",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "john@example.com",
  "phonePrefix": "+964",
  "phoneNumber": "7701234567",
  "birthDate": "1990-05-15"
}

Create Traveler with Passport (Admin)

POST /api/admin/travelers/with-passport
Content-Type: multipart/form-data

Form Fields:

Field	Type	Required
`userId`	string	Yes
`title`	string	Yes
`firstName`	string	Yes
`lastName`	string	Yes
`emailAddress`	string	No
`phonePrefix`	string	Yes
`phoneNumber`	string	Yes
`birthDate`	string (date)	Yes
`passportNumber`	string	Yes
`passportNationality`	string	Yes
`passportIssuingCountry`	string	Yes
`passportIssuingDate`	string (date)	Yes
`passportExpiryDate`	string (date)	Yes
`passportIsPrimary`	boolean	No
`passportDocuments`	File[]	No

Update Traveler (Admin)

PATCH /api/admin/travelers/:id

Request Body: Partial traveler object (only fields to update).

Delete Traveler (Admin)

DELETE /api/admin/travelers/:id

Response: 204 No Content

Travelers with pending booking requests cannot be deleted. Returns 400 Bad Request.

Passport Endpoints

List Passports by Traveler

GET /api/travelers/:travelerId/passports

Response:

{
  "status": "success",
  "data": [
    {
      "id": "clx789...",
      "travelerId": "clx123...",
      "passportNumber": "A12345678",
      "nationality": "US",
      "issuingCountry": "US",
      "issuingDate": "2020-01-15T00:00:00.000Z",
      "expiryDate": "2030-01-15T00:00:00.000Z",
      "isPrimary": true,
      "expiresInDays": 1450
    }
  ]
}

Get Passport

GET /api/passports/:id

Create Passport

POST /api/travelers/:travelerId/passports

Request Body:

{
  "passportNumber": "A12345678",
  "nationality": "US",
  "issuingCountry": "US",
  "issuingDate": "2020-01-15",
  "expiryDate": "2030-01-15",
  "isPrimary": true
}

Create Passport with Documents

POST /api/travelers/:travelerId/passports/with-documents
Content-Type: multipart/form-data

Form Fields:

Field	Type	Required
`passportNumber`	string	Yes
`nationality`	string	Yes
`issuingCountry`	string	Yes
`issuingDate`	string (date)	Yes
`expiryDate`	string (date)	Yes
`isPrimary`	boolean	No
`passportDocuments`	File[]	No

Update Passport

PATCH /api/passports/:id

Request Body: Partial passport object.

Delete Passport

DELETE /api/passports/:id

Set Primary Passport

POST /api/passports/:id/set-primary

Request Body:

{
  "travelerId": "clx123..."
}

Document Endpoints

List Documents by Traveler

GET /api/travelers/:travelerId/documents

Query Parameters:

Parameter	Type	Description
`category`	string	Filter by category

Upload Document

POST /api/travelers/:travelerId/documents
Content-Type: multipart/form-data

Form Fields:

Field	Type	Required
`file`	File	Yes
`documentCategory`	string	Yes
`label`	string	No
`relatedEntityId`	string	No
`relatedEntityType`	string	No

Get Document Download URL

GET /api/documents/:id/download

Response:

{
  "status": "success",
  "data": {
    "url": "https://storage.example.com/signed-url...",
    "expiresAt": "2026-01-26T12:00:00.000Z"
  }
}

Delete Document

DELETE /api/documents/:id

Error Responses

Standard Error Format

{
  "status": "error",
  "message": "Error message here",
  "code": "ERROR_CODE"
}

Common Error Codes

Code	HTTP Status	Description
`TRAVELER_NOT_FOUND`	404	Traveler does not exist
`PASSPORT_NOT_FOUND`	404	Passport does not exist
`DOCUMENT_NOT_FOUND`	404	Document does not exist
`DUPLICATE_NATIONALITY`	400	Passport with nationality exists
`TRAVELER_IN_BOOKING`	400	Cannot delete - pending bookings
`INVALID_DATES`	400	Expiry date before issuing date
`FILE_TOO_LARGE`	400	File exceeds 10MB limit
`INVALID_FILE_TYPE`	400	Unsupported file format

Pagination

All list endpoints return paginated results:

{
  "data": [...],
  "total": 150,
  "page": 1,
  "perPage": 10
}

Field	Description
`data`	Array of items for current page
`total`	Total number of items
`page`	Current page number
`perPage`	Items per page

Rate Limits

Endpoint Type	Limit
Read endpoints	100 requests/minute
Write endpoints	30 requests/minute
File uploads	10 requests/minute

API Reference

On this page