API Guide: Create An Itinerary

Create a private itinerary in one call with POST /v1/itineraries, and retry it safely.

Create a whole itinerary in one call. It is saved as a private draft; the traveller decides whether to share it. The token needs the itineraries:write scope.

Steps

Compose the itinerary. destination needs a name and a coordinate. A stop needs a name, a category and a place. Leave out id on days and stops and the server makes them. Stop categories are beach, landmark, restaurant, cafe, hotel, museum, nature, nightlife, shopping, activity, viewpoint and transport.

Send it with a new Idempotency-Key (a unique value, such as a UUID, that makes a retry safe) and the shape header.

curl -X POST https://api.travelyfe.com/v1/itineraries \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Travelyfe-Itinerary-Shape: clean" \
  -H "Idempotency-Key: 0b7f6c0e-3a55-4a4b-9c52-6f2d1f8f7a01" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Five Days In Lisbon",
    "summary": "Tiles, trams and custard tarts.",
    "destination": {
      "name": "Lisbon, Portugal",
      "coordinate": { "latitude": 38.7223, "longitude": -9.1393 }
    },
    "startDate": "2027-03-10",
    "travellers": 2,
    "currency": "GBP",
    "days": [
      {
        "stops": [
          {
            "name": "Belém Tower",
            "category": "landmark",
            "place": { "coordinate": { "latitude": 38.6916, "longitude": -9.2160 } }
          }
        ]
      }
    ]
  }'

Keep what comes back. The answer is 201 with the itinerary, its new id, an ETag header (the version, needed for later changes) and a Location header with its address. Anything the server could not place or fill is listed in needsAttention.

What You Get

A private itinerary owned by the traveller. A stop sent without a coordinate is placed on the map from its name; one that cannot be found is listed in needsAttention. Flights, hotels, packing items and expenses can be sent in the same call; each gets an id if you leave it out.

If It Doesn't Work

409 duplicateItinerary: the traveller already has an itinerary for that destination and start date. The existing id is in details.itineraryId. Update that one, or add ?allowDuplicate=true.
422 validationFailed: details.field names the field. Common causes: a title over 60 characters, no destination.coordinate, or a body that is not JSON.
403 subscriptionRequired: the body has packing or expenses and the traveller does not have Pro.
413 itineraryTooLarge: the itinerary is over 256 KB.
422 idempotencyKeyReused: you reused a key with a different body.
429 rateLimited: wait the Retry-After seconds.

Limits

Writes count against 60 requests a minute.
A title is at most 60 characters and a summary 240. An itinerary has up to 3 tags, 2 flights and 1 hotel.
A retry with the same Idempotency-Key and body within 24 hours replays the first answer instead of creating a second itinerary.

API Guide: Create An Itinerary

Steps

What You Get

If It Doesn't Work

Limits

Related

On this page