Bookings¶

Creating and updating bookings¶

URL

/v1/booking/{AgentBookingId}

HTTP Method

PUT

Client Library Message Name

Booking.PutBookingRequest

You should PUT details of your booking to the booking service to create or update a booking. The details of the booking should include your own unique id for the booking. The first time you PUT a booking with a specific ID we’ll create a new booking record in our system. When you need to update the booking then you just need to PUT the updated booking details with the same ID you specified when the booking was created and we’ll perform the update.

We’ll do some basic validation of your booking such as checking that all the required fields are filled in and that you’ve provided valid country codes. If the booking passes basic validation we’ll return an empty HTTP 200 OK response to let you know that we’ve handed the booking off to our back-end system for further processing; see Sample Response - Passed Basic Validation for a sample of this. If a booking fails validation then we’ll return a message that describes why the booking failed validation along with a HTTP 404 Invalid code; see Sample Response - Failed Basic Validation for a sample of this.

Our back-end system will do some more complex validation such as checking that the course you requested is offered by the desired centre at the required start date. You should register to be notified of bookings that fail validation and display the validation message to the member of staff that is responsible for the booking so they can fix the issue and resubmit the booking. You can see a sample of this notification in the Invalid booking notification section. Notifications are made using our Notifications system. This system allows you to be notified using a message over HTTP or to have an HTML email sent directly to the member of staff with details of the validation failure.

You can also register to be notified when our back-end system has finished creating the booking in our student management system by setting up a New booking notification.

{
            "AgentBookingId": "X8347848",
    "Booking": {
        "AgentOfficeCode": "2983",
        "AgentContact": {
            "FirstNames": "Anna",
            "LastName": "Polishchuk",
            "Email": "anna.polishchuk@agentcompany.com"
        },
        "SchoolCode": "S333",
        "LanguageLevel": "Intermediate",
        "Student": {
            "FirstNames": "Bobby",
            "LastName": "Smith",
            "PassportNumber": "4823 909 9838",
            "PassportIssuingCountryIsoCode": "ES",
            "DateOfBirth": "1993-02-20",
            "Gender": "Male",
            "CountryOfBirthIsoCode": "ES",
            "NationalityIsoCode": "ES",
            "Email": "bobby@example.com",
            "Telephone": "+34 93 412 46 02",
            "Mobile": "+34 09 456 888",
            "Address": {
                "Line1": "Torre Espacio",
                "Line2": "Paseo de la Castellana 259D",
                "City": "Madrid",
                "StateProvince": "",
                "PostalCode": "28046",
                "CountryIsoCode": "ES"
            },
            "EmergencyContact": {
                "Name": "Jane Smith",
                "Phone": "+34 09 123 233",
                "Relationship": "Mother"
            }
        },
        "Courses": [
            {
                "CourseCode": "C92",
                "DateFrom": "2016-03-14",
                "NumberOfWeeks": 3
            }
        ],
        "Accommodation": [
            {
                "AccommodationCode": "A78",
                "DateFrom": "2016-03-13",
                "NumberOfWeeks": 3
            }
        ],
        "OptionalExtras": [
            {
                "Quantity": "1",
                "OptionalExtraCode": "E33"
            }
        ],
        "Transfers": [
            {
                "TransferCode": "TRN88"
            }
        ],
        "SpecialRequirements": {
            "Allergies": "Allergic to nuts"
        }
    }
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Content-Length: 2

{}

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Cache-Control: no-cache
Content-Length: 321

<PutBookingResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/EcEnglish.Api.ServiceContract.Booking">
  <MessageId
    i:nil="true" xmlns="http://schemas.datacontract.org/2004/07/EcEnglish.Api.ServiceContract" />
</PutBookingResponse>

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Content-Length: 461

{
  "ResponseStatus": {
    "ErrorCode": "StringLength",
    "Message": "'FirstNames' must be between 0 and 100 characters",
    "Errors": [
      {
        "ErrorCode": "StringLength",
        "FieldName": "FirstNames",
        "Message": "'FirstNames' must be between 0 and 100 characters"
      },
      {
        "ErrorCode": "Required",
        "FieldName": "DateOfBirth",
        "Message": "'DateOfBirth' is required"
      }
    ]
  }
}

HTTP/1.1 400 Bad Request
Content-Type: application/xml; charset=utf-8
Cache-Control: no-cache
Content-Length: 846

<ErrorResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.servicestack.net/types">
  <ResponseStatus>
    <ErrorCode>StringLength</ErrorCode>
    <Message>'FirstNames' must be between 0 and 100 characters</Message>
    <StackTrace i:nil="true" />
    <Errors>
      <ResponseError>
        <ErrorCode>StringLength</ErrorCode>
        <FieldName>FirstNames</FieldName>
        <Message>'FirstNames' must be between 0 and 100 characters</Message>
      </ResponseError>
      <ResponseError>
        <ErrorCode>Required</ErrorCode>
        <FieldName>DateOfBirth</FieldName>
        <Message>'DateOfBirth' is required</Message>
      </ResponseError>
    </Errors>
    <Meta xmlns:d3p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays" i:nil="true" />
  </ResponseStatus>
</ErrorResponse>

Invalid booking notification¶

You should register to be notified via our Notifications system about bookings that have failed validation and hence will not be loaded into our student management system. These validation messages are designed to make sense to business users and will have messages such as:

Start date 02/03/2015 isn’t a valid start date for General English and Brighton

You can choose to receive these messages as a HTTP message using JSON or XML, or to have an HTML email send directly to the user with details of the validation failure.

POST /your-url HTTP/1.1
Host: www.yoursite.com
Content-Type: application/json; charset=utf-8
Accept: application/json
X-EC-NotificationKey: secret-notification-key
Content-Length: 205

{
  "Topic": "Booking:Invalid",
  "AgentBookingId": "X8347848",
  "ValidationMessages": [
    {
      "Message": "02-10-2015 isn't a valid start date to 'General English' in 'Brighton'"
    }
  ]
}

POST /your-url HTTP/1.1
Host: www.yoursite.com
Content-Type: application/xml; charset=utf-8
Accept: application/xml
X-EC-NotificationKey: secret-notification-key
Content-Length: 501

<BookingInvalidNotificationMessage xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/EcEnglish.Api.ServiceContract.Booking">
  <AgentBookingId>X8347848</AgentBookingId>
  <Topic>Booking:Invalid</Topic>
  <ValidationMessages>
    <BookingValidationMessage>
      <Message>02-10-2015 isn't a valid start date to 'General English' in 'Brighton'</Message>
    </BookingValidationMessage>
  </ValidationMessages>
</BookingInvalidNotificationMessage>

New booking notification¶

You can register to be notified via our Notifications system when we’ve finished creating a new booking in our student management system. You’ll get a notification like the example below for each booking thats been processed.

You can also choose to have these details sent to a member of staff by email.

POST /your-url HTTP/1.1
Host: www.yoursite.com
Content-Type: application/json; charset=utf-8
Accept: application/json
X-EC-NotificationKey: secret-notification-key
Content-Length: 67

{
  "Topic": "Booking:Success",
  "AgentBookingId": "X8347848"
}

POST /your-url HTTP/1.1
Host: www.yoursite.com
Content-Type: application/xml; charset=utf-8
Accept: application/xml
X-EC-NotificationKey: secret-notification-key
Content-Length: 402

<BookingSuccessNotificationMessage xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/EcEnglish.Api.ServiceContract.Booking">
  <AgentBookingId>X8347848</AgentBookingId>
  <EcEnglishBookingId>0</EcEnglishBookingId>
  <EcEnglishStudentId>0</EcEnglishStudentId>
  <Topic>Booking:Success</Topic>
</BookingSuccessNotificationMessage>