External systems

Your integration can ask us to send a feedback request automatically. Our system will decide how to process your request based on existing user preferences.


When you create a new feedback request the details that you provide are stored by us internally for a short amount of time, which is normally a maximum of 28 days. This ensures that we do not send multiple feedback requests more than once, to avoid accidentally spam.

The basic steps to issue a feedback request from an external system are:
 

  • 1

    Construct a POST request to our dedicated endpoint

    Get your application ready to create a POST request to the External Feedback Request endpoint. PHP users can take advantage of cURL for this purpose, whilst .NET users can use the System.Web.HttpRequest class. The endpoint is accessible at https://api-v6.workingfeedback.co.uk/request-feedback/external.
  • 2

    Supply your API key and the required information

    In the request header, provide your API key as a standard header value (apikey: XXXXXX). In the POST body, provide at least the minimum variables required in JSON format.Please see the table below for the full list of variables.
  • 3

    Execute the request and check the return status

    Your application should evaluate both the HTTP status code and the returned JSON to determine whether or not the request was successful.

 

Complete list of acceptable variables

The below list covers both the required and the optional variables that this endpoint will accept. These should be supplied in JSON format. Code examples are provided at the bottom of this page.

Property Required Default Description
identifier yes N/A A container for companyID, which is a 1-8 digit integer type (obtained from Working Feedback) used to identify the business. See the code examples below.
requests yes N/A An array of individual FeedbackRequest objects as described below. A minimum of 1 request is required for submission. You can submit a maximum of 65,534 requests in a single API call.

 

FeedbackRequest object properties

The below list shows the accepted properties for each FeedbackRequest object in your JSON request. Note that you must supply at least one form of contact method (either email or mobile), although we highly recommend including both where possible to allow the system to automatically select the best method.

Property Required Default Description
name yes N/A The name of the person who should receive the feedback request (e.g Joe Bloggs)
email depend N/A The email address that the feedback request should be sent to (e.g [email protected]). If this value is blank, a value must be provided for mobile.
mobile depend N/A The mobile number that the feedback request should be sent to (e.g 07123456789). If this value is blank, a value must be provided for email.
description no N/A If this value is set, it is used to pre-fill the title of the review on the feedback form presented to the end user.
treatmentType no NHS For dentists, set this to "PRIVATE" if the feedback request is regarding a private dental treatment, or "NHS" if it is an NHS dental treatment. Value is ignored if specified company is not a dentist.
custom_field_1 no N/A
NEW
You can now optionally attach up to 10 custom fields to your feedback requests. These can contain any data type permitted in JSON (integer, string, etc) up to 1000 characters. If the feedback request is completed by the recipient, these custom fields will be attached to the final review and are shown in reports.
custom_field_2 no N/A Optional metadata. See note on custom_field_1.
custom_field_3 no N/A Optional metadata. See note on custom_field_1.
custom_field_4 no N/A Optional metadata. See note on custom_field_1.
custom_field_5 no N/A Optional metadata. See note on custom_field_1.
custom_field_6 no N/A Optional metadata. See note on custom_field_1.
custom_field_7 no N/A Optional metadata. See note on custom_field_1.
custom_field_8 no N/A Optional metadata. See note on custom_field_1.
custom_field_9 no N/A Optional metadata. See note on custom_field_1.
custom_field_10 no N/A Optional metadata. See note on custom_field_1.

 

Code Examples

There are no platform specific code examples for this functionality. However, an example POST body is included for reference purposes.

copy
						

{
  "identifier": {
    "companyID": 4849405
  },
  "requests": [
    {
      "name": "Joe Bloggs",
      "email": "[email protected]",
      "mobile": "07123456789", 
      "treatmentType": "PRIVATE", 
      "description": "Recent appointment with Dr Jennifer Simpson", 
      "custom_field_1": 12345, 
      "custom_field_2": "STAFF",
      "custom_field_3": "This is a test"
    },
    {
      "name": "Jane Smith",
      "email": "[email protected]",
      "mobile": "07987654321",
      "treatmentType": "NHS"
    }
  ]
}
					

 

Return Values

This endpoint returns a selection of HTTP status codes depending on the result of the calling request.

Code Meaning
200 The request was successful. You should check the resulting JSON document to see the individual status of each feedback request that you sent.
401 The business detected from the supplied identification data is not an active subscriber of the Working Feedback service. Only paying customers can send feedback requests.
403 The supplied API key explicitly does not have permission to access this feature. The request was not successful.
404 We could not identify your business from the identification data you supplied. This may mean that the email address, postcode, or telephone number that we have on our system does not match.
500 An internal system error occured during processing on our servers. The request was not successful. This is normally a temporary issue which is resolved by repeating the request a few minutes later. If known, the exact reason for the failure is returned as a JSON document which you can inspect to retrieve the error description.

 

Example JSON response

An example of a successful submission and response is shown below for reference purposes.

copy
						

{
  "results": [
    {
      "methodSent": "SMS to 07123456789",
      "statusText": "The SMS feedback request was sent successfully",
      "statusCode": "201",
      "name": "Liam Crayden"
    }
  ]
}