Creating and updating guest data on reservations

Every reservation has:

• one main guest — the person who books and receives the confirmation, sent as the guest object;
• zero or more fellow guests — the other people staying, sent as the guests array.

Where to send guest data

The same guest and guests structures are accepted on:

Authenticate as usual with your API key in the X-Api-Key header.

Creating a reservation with a guest

POST /api/reservations/?organization=1000
X-Api-Key: your-api-key
Content-Type: application/json

{
  "guest": {
    "salutation": "male",
    "firstName": "Johnny",
    "surname": "Cash",
    "email": "[email protected]",
    "phoneNumber": "+31612345678",
    "address": "Akkerstraat",
    "addressNo": "143",
    "postalCode": "5293AJ",
    "locality": "Gemonde",
    "country": "NL",
    "locale": "nl",
    "birthDate": "1992-07-02"
  },
  "guests": [
    {
      "firstName": "June",
      "surname": "Carter",
      "birthDate": "1994-03-11"
    }
  ]
}

The response contains the stored reservation, including the guest with the id that Recranet assigned. Keep that id if you want to refer to the guest later.

Updating guest data

PUT /api/reservations/{id} applies a partial update to the main guest: only the keys you send are changed, everything else stays as it is.

{
  "guest": {
    "email": "[email protected]",
    "phoneNumber": "+31687654321"
  }
}

To detach the guest from a reservation, send guest as null or as an empty object. This removes the link between the reservation and the guest; the guest record itself is kept.

{
  "guest": null
}

Fellow guests

The guests array is a full replacement, not a partial update. Recranet clears the existing list and rebuilds it from what you send, so always send every fellow guest that should remain on the reservation.

• Include a fellow guest's id to update that existing record instead of creating a new one.
• Send "guests": [] to remove all fellow guests.
• The number of fellow guests may not exceed numOfPersons - 1 (the main guest counts as a person). For a reservation that is part of a group reservation, the limit is numOfPersons. Exceeding it returns 400 Bad Request.

{
  "guests": [
    { "id": 4001, "firstName": "June", "surname": "Carter" },
    { "firstName": "Rosanne", "surname": "Cash", "birthDate": "2016-05-24" }
  ]
}

Guest fields

Which fields an organization actually asks for differs per organization, and so does which of them are mandatory. Recranet does not enforce that configuration when you create a reservation through the API, so validate your own booking form.

Custom fields

Besides the fields above, an organization can define its own guest fields, for example a question about how the guest found them, or a dietary preference. You send those values in the customFields object, keyed by the internal name of the field:

{
  "guest": {
    "firstName": "Johnny",
    "surname": "Cash",
    "customFields": {
      "how-did-you-find-us": "Recommended by friends",
      "dietary-preference": "Vegetarian"
    }
  }
}

Points to keep in mind:

• The key is the field's internal name, which stays the same even when the organization renames the visible label. Ask Recranet support for the names of the custom fields of the organization you integrate with.
• For a field with a fixed list of options, send exactly one of the configured option strings, character for character. Options are not translated.
• customFields replaces the whole set of custom values for that guest. Send all known values together; if you send only one key, the others are cleared. Leaving customFields out of the payload keeps the stored values untouched.
• An unknown key is accepted without an error, but the value then shows up in Recranet without a matching field. Copy the names exactly.

Clearing values

Sending null clears the stored value for email, municipality and birthDate. For the other fields, null is ignored: send an empty string to clear them.

One exception worth knowing: sending iban clears the stored bic, because a BIC belongs to a specific account. Send both together when you have them.

Linking an existing guest

Send guest.id to link a reservation to a guest record that already exists. This requires an API user with manager permissions; for other API users the id is ignored and a new guest record is created.

Recranet keeps its own duplicate detection: guests that share, for example, an email address or a name and date of birth are grouped in the dashboard, where staff can merge them. You do not need to look up existing guests yourself to avoid duplicates.