Manage travelers and travel documents for a customer

Booking
Customer account
5 routes

How can I manage travelers and travel documents for a customer account?

This scenario documents how to list travelers linked to a customer account, create new travelers, retrieve travel documents, update them, and resolve a customer when needed.

Overview

Use this scenario to manage the travelers linked to a customer account and keep their travel documents up to date. The flow combines traveler listing and creation, travel-document read-back, updates, and customer search when the right account must first be identified.

Prerequisites

A valid customer_id is required on traveler and travel-document routes.
Customer-scoped routes require authorization, and all documented calls require accept-language and x-api-key.
Customer search may be needed to resolve the correct account before document updates.

Process workflow

Legend:

Mandatory

Optional

List linked travelers

Mandatory

Use GET/v1/customers/{customer_id}/travelers to list linked travelers.

Prerequisites

Prepare customer_id. Keep x-api-key and, when the route is customer-scoped, a valid bearer token.

Calling CURL

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.clubmed.com/v1/customers/{customer_id}/travelers"

Example answer

[
  {
    "id": "traveler-1",
    "first_name": "Jane",
    "last_name": "Doe"
  }
]

info: Use the traveler list to confirm who is already attached to the customer before creating a new traveler or updating documents.

Response codes

200 OK: the expected data is returned.
400 Bad Request: the request is invalid or incomplete.
401 Unauthorized: the token is missing or invalid.
403 Forbidden: access is denied in this context.
404 Not Found: the requested resource cannot be found.

GET/v1/customers/{customer_id}/travelers

Create a traveler

Mandatory

Use POST/v1/customers/{customer_id}/travelers to create an additional traveler on the customer account before working on travel documents.

Prerequisites

Prepare customer_id. Keep x-api-key and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

Calling CURL

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane", "last_name": "Doe", "birthdate": "1990-03-12"}' \
  "https://api.clubmed.com/v1/customers/{customer_id}/travelers"

Example answer

{
  "id": "traveler-1",
  "first_name": "Jane",
  "last_name": "Doe"
}

info: Keep the returned traveler id if the same traveler must be reused or reconciled in later customer operations.

Response codes

200 OK: the operation succeeds and the resource is returned.
400 Bad Request: the body or parameters are invalid.
401 Unauthorized: the token is missing or invalid.
403 Forbidden: access is denied in this context.
404 Not Found: the target resource cannot be found.

POST/v1/customers/{customer_id}/travelers

Retrieve travel documents

Mandatory

Use GET/v1/customers/{customer_id}/travel_documents to review the customer's existing travel documents before deciding whether one must be updated.

Prerequisites

Prepare customer_id. Keep x-api-key and, when the route is customer-scoped, a valid bearer token.

Calling CURL

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.clubmed.com/v1/customers/{customer_id}/travel_documents"

Example answer

[
  {
    "id": "doc-1",
    "type": "PASSPORT",
    "number": "XX123456",
    "expiration_date": "2030-07-01"
  }
]

info: Use document id, type, and expiry data to decide which travel document needs an update.

Response codes

200 OK: the expected data is returned.
400 Bad Request: the request is invalid or incomplete.
401 Unauthorized: the token is missing or invalid.
403 Forbidden: access is denied in this context.
404 Not Found: the requested resource cannot be found.

GET/v1/customers/{customer_id}/travel_documents

Update travel documents

Mandatory

Use PATCH/v1/customers/{customer_id}/travel_documents to update travel documents.

Prerequisites

Prepare customer_id. Keep x-api-key and, when the route is customer-scoped, a valid bearer token. Validate the request body before the call to avoid a validation error.

Calling CURL

curl -X PATCH \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"id": "doc-1", "number": "XX123456", "expiration_date": "2030-07-01"}]}' \
  "https://api.clubmed.com/v1/customers/{customer_id}/travel_documents"

Example answer

HTTP/1.1 204 No Content

info: Success may be returned without a response body. Read the resource again afterwards if you need to display the final state.

Response codes

204 No Content: the operation is applied successfully.
400 Bad Request: the body or parameters are invalid.
401 Unauthorized: the token is missing or invalid.
403 Forbidden: access is denied in this context.
404 Not Found: the target resource cannot be found.

PATCH/v1/customers/{customer_id}/travel_documents

Resolve the customer account

Optional

Use GET/v1/customers to resolve the customer account.

Prerequisites

Prepare the parameters required by the call. Keep x-api-key and, when the route is customer-scoped, a valid bearer token.

Calling CURL

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  -H "accept-language: en-US" \
  "https://api.clubmed.com/v1/customers"

Example answer

[
  {
    "id": "customer-1",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
  }
]

info: Use the returned customer identifiers to continue with traveler and travel-document operations on the correct account.

Response codes

200 OK: the expected data is returned.
400 Bad Request: the request is invalid or incomplete.
404 Not Found: the requested resource cannot be found.

GET/v1/customers