Add a traveler
POST/v1/trips/{tripId}/travelers
Adds one passenger to the trip, last unless position says otherwise (0 = first). Any field may be sent; the whole passenger is validated as the Travelers drawer does. The trip's travelers headcount caps the roster (422 pax_exceeded: raise it with PATCH /trips/{tripId} first). A trip still nueva, propuesta_enviada or rechazada with no passengers takes none (422 roster_locked). On a reservada trip a passenger with a new email gets the app-access email. Undo with POST /changes/{changeId}/revert within 30 days, while nobody has edited the passenger since. An access email the write queued is not recalled.
Permissions: travelers:write · Kind: write · Cost: 1 unit · MCP tool add_traveler
Undoable: the response carries Bymundi-Change-Id; revert it with POST /v1/changes/{changeId}/revert.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
tripId |
uuid | yes |
Body
| Field | Type | Required | Description |
|---|---|---|---|
position |
integer | 0 = first on the booking. Past the end = last. 0–39 | |
title |
"mr" | "mrs" | "ms" | "mstr" | "miss" | null | Form of address; the app derives one from sex and age when empty. | |
firstName |
string | null | ||
lastName1 |
string | null | Surname(s) as on the passport — the app asks for both surnames here. | |
lastName2 |
string | null | A second surname stored separately (older passengers); usually null. | |
birthDate |
string | null | ||
sex |
"m" | "f" | null | ||
nationality |
string | null | ||
docType |
"dni" | "nie" | "passport" | "other" | null | ||
docNumber |
string | null | ||
docExpiry |
string | null | ||
docCountry |
string | null | The country that issued the document. | |
email |
email | null | ||
phone |
string | null | ||
address |
object | null | ||
address.line1 |
string | null | yes | |
address.line2 |
string | null | yes | |
address.postalCode |
string | null | yes | |
address.city |
string | null | yes | |
address.region |
string | null | yes | |
address.country |
string | null | yes | |
taxId |
string | null |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
object |
"traveler" | yes | |
id |
uuid | yes | |
tripId |
uuid | yes | |
position |
integer | yes | |
title |
"mr" | "mrs" | "ms" | "mstr" | "miss" | null | yes | |
firstName |
string | null | yes | |
lastName1 |
string | null | yes | |
lastName2 |
string | null | yes | |
birthDate |
string | null | yes | |
sex |
"m" | "f" | null | yes | |
nationality |
string | null | yes | |
docType |
"dni" | "nie" | "passport" | "other" | null | yes | |
docNumber |
string | null | yes | |
docExpiry |
string | null | yes | |
docCountry |
string | null | yes | |
email |
string | null | yes | |
phone |
string | null | yes | |
address |
object | null | yes | |
address.line1 |
string | null | yes | |
address.line2 |
string | null | yes | |
address.postalCode |
string | null | yes | |
address.city |
string | null | yes | |
address.region |
string | null | yes | |
address.country |
string | null | yes | |
taxId |
string | null | yes | |
paxType |
"adult" | "child" | "infant" | "unknown" | yes | |
missing |
string[] | yes | |
access |
"invited" | "queued" | "failed" | "no_email" | "not_yet" | null | yes | |
source |
string | yes | |
consentAt |
string | null | yes | |
docsPurgedAt |
string | null | yes | |
createdAt |
string | yes | |
updatedAt |
string | yes |
Errors
Errors are problem details. Besides the refusals described above, any call like this one can return:
invalid_request— Invalid requestunauthorized— Missing or invalid API keyinsufficient_scope— Missing permissionrate_limited— Rate limit reachednot_found— Not foundidempotency_key_reused— Idempotency-Key reusedrequest_in_progress— Request in progress