Skip to content

References

Retrieve Surveys

The GET surveys endpoint enables you to retrieve survey data for completed bookings.

GET /v1/surveys

Note

Surveys are returned in descending order by completion date time.

Request

URL Parameters

Parameter Type Default Value Description Required
completionFrom DateTime 14 days before the current date time Survey completion date time in UTC (ISO 8601) for start of the date range (inclusive). Yes - but only when completionTo is provided
completionTo DateTime The current date time Survey completion date time in UTC (ISO 8601) for end of date range (inclusive). Yes - but only when completionFrom is provided
pageNumber Integer 0 Page number to retrieve (zero-indexed). No
pageSize Integer 200 Number of surveys to return per page. Must be between 1 and 500. No

Warning

The maximum date range between completionFrom and completionTo is 365 days. Requests exceeding this range will return a 400 error.

Sample Request

GET /v1/surveys

GET /v1/surveys?completionFrom=2024-05-01T00:00:00&completionTo=2024-05-31T23:59:59&pageNumber=1&pageSize=500

Response

Field Type Description
surveys Object Array An array of survey objects.
survey.bookingReference String The booking reference.
survey.pickupDateTimeUTC DateTime The pickup timestamp in UTC (ISO 8601).
survey.surveyCompletionDateTimeUTC DateTime The survey completion timestamp in UTC (ISO 8601).
survey.score Integer The score given by the customer (1-5).
survey.rating String POSITIVE if score is 5, NEGATIVE if score is 4 or below.
survey.reasons String Array The reasons provided by the customer for their score.
survey.comment String Additional free-text comments written by the customer.
pageSize Integer The current page size.
currentPage Integer The current page number (zero-indexed).
hasNextPage Boolean true if there are more surveys to retrieve.
nextHref String A link to retrieve the next page of surveys. Use this URL directly for pagination.

HTTP 200 - OK

{
  "surveys": [
    {
      "bookingReference": "11523901",
      "score": 5,
      "rating": "POSITIVE",
      "reasons": [
        "Ease of communication",
        "Instructions for meeting the driver"
      ],
      "comment": "The driver was very friendly and the car was clean",
      "surveyCompletionDateTimeUTC": "2024-08-12T13:31:23",
      "pickupDateTimeUTC": "2024-08-12T12:31:23"
    },
    {
      "bookingReference": "27191328",
      "score": 4,
      "rating": "NEGATIVE",
      "reasons": [
        "The driver was too early",
        "Instructions to find the driver were not clear"
      ],
      "comment": "It was difficult to communicate with the driver",
      "surveyCompletionDateTimeUTC": "2024-08-12T12:31:23",
      "pickupDateTimeUTC": "2024-08-12T11:31:23"
    }
  ],
  "pageSize": 200,
  "currentPage": 0,
  "hasNextPage": true,
  "nextHref": "/v1/surveys?completionFrom=2024-07-29T14:31:23&completionTo=2024-08-12T14:31:23&pageNumber=1&pageSize=200"
}

HTTP 400 - Bad Request

{
  "errorCode": "e152c59d-5327-433c-980b-12f759b6782e",
  "errorMessage": "Min.pageNumber: must be greater than or equal to 0"
}

HTTP 401 - Unauthorized

Further reading