@extends('layouts.app') @section('content')

API Documentation

Generating Access Tokens

Once logged in, you can generate an API token from the dashboard's homepage by clicking on the Generate Token button. When the token is created, it is hashed prior to being stored in the database, so its plain text value can no longer be accessed.

If you lose your token, you can revoke it by clicking on the Revoke Token button and then generate a new one.

Making a Request

The base URL for all endpoints is https://ohfsc.safelincs.co.uk/api/. In order to authenticate a request you must supply your token as a bearer token in the Authorization header, eg: 

Authorization: Bearer {token}

You can specify the type of response you wish to receive by passing the Accept header with a value of application/json for JSON, or application/xml for XML. By default, all requests return JSON when this header isn't supplied.

All successful requests return a HTTP status code of 200 (OK). All unsuccessful requests will return the corresponding status code and, at least, a message. The following is an example of a 422 (Unprocessable Entity) response when the API fails to validate some required request input:

JSON Response


  {
    "message": "The given data was invalid.",
    "errors": {
      "modified_to": [
        "The modified to field is required"
      ]
    }
  }

XML Response


  <?xml version="1.0"?>
  <response>
    <message>The given data was invalid.</message>
    <errors>
      <modified_to>The modified to field is required.</modified_to>
    </errors>
  </response>

Endpoints

GET https://ohfsc.safelincs.co.uk/api/sessions

Returns all sessions which meet the supplied criteria.

Query Parameters

Name Type Required Description
modified_from string Yes The date and time to check for sessions modified from. Format YYYY-MM-DDTHH:MM:SS (eg. 2021-04-01T09:00:00)
modified_to string Yes The date and time to check for sessions modified to. Format YYYY-MM-DDTHH:MM:SS (eg. 2021-04-01T17:00:00)

JSON Response


  {
    "sessions": [
      {
        "id": "923180f5e448b0e3",
        "created_at": "2021-04-01T13:31:15",
        "updated_at": "2021-04-01T13:34:26",
        "score": 15,
        "risk": "High",
        "has_referral": true,
        "referral_complete": true,
        "contacts": {
          "third_party": {
            "email": "john@doe.com",
            "surname": "Surname",
            "forename": "Forename",
            "telephone": "01234567890",
            "concerns": "Additional comments and/or concerns",
          },
          "client": {
            "city": "City",
            "email": "john@doe.com",
            "surname": "Surname",
            "forename": "Forename",
            "postcode": "LN13 9FX",
            "address_1": "Address Line 1",
            "address_2": "Address Line 2",
            "telephone": "01234567890",
            "uprn": "10013049814",
            "consent": "Y"
          },
          "referrer": {
            "role": "Role",
            "email": "john@doe.com",
            "surname": "Surname",
            "forename": "Forename",
            "telephone": "01234567890",
            "organisation": "Organisation",
            "concerns": "Additional comments and/or concerns",
            "consent": "Y"
          }
        },
        "questions": [
          {
            "id": 1,
            "title": "Are you completing this fire safety check for yourself?",
            "body": "Please tell us whether you are answering these questions about your own home or somebody else's home.",
            "options": [
              {
                "id": 2,
                "title": "No – I am completing this check for someone else",
                "body": null,
                "value": null
              },
              ...
            ]
          },
          ...
        ],
      },
      ...
    ],
  }

XML Response


  <?xml version="1.0"?>
  <response>
    <sessions>
      <id>923180f5e448b0e3</id>
      <created_at>2021-04-01T13:31:15</created_at>
      <updated_at>2021-04-01T13:34:26</updated_at>
      <score>15</score>
      <risk>High</risk>
      <has_referral>true</has_referral>
      <referral_complete>true</referral_complete>
      <contacts>
        <third_party>
          <email>john@doe.com</email>
          <surname>Surname</surname>
          <forename>Forename</forename>
          <telephone>01234567890</telephone>
          <concerns>Additional comments and/or concerns</concerns>
        </third_party>
        <client>
          <city>City</city>
          <email>john@doe.com</email>
          <surname>Surname</surname>
          <forename>Forename</forename>
          <postcode>LN13 9FX</postcode>
          <address_1>Address Line 1</address_1>
          <address_2>Address Line 2</address_2>
          <telephone>01234567890</telephone>
          <consent>Y</consent>
        </client>
        <referrer>
          <role>Role</role>
          <email>john@doe.com</email>
          <surname>Surname</surname>
          <forename>Forename</forename>
          <telephone>01234567890</telephone>
          <organisation>Organisation</organisation>
          <concerns>Additional comments and/or concerns</concerns>
          <consent>Y</consent>
        </referrer>
      </contacts>
      <questions>
        <id>1</id>
        <title>Are you completing this fire safety check for yourself?</title>
        <body>Please tell us whether you are answering these questions about your own home or somebody else's home.</body>
        <options>
          <id>2</id>
          <title>No – I am completing this check for someone else</title>
          <body></body>
          <value></value>
        </options>
        ...
      </questions>
      ...
    </sessions>
    ...
  </response>

Response Index

Property Type Max Length Path(s) Notes
id string 16 (top level) Hexadecimal string
created_at string 19 (top level) ISO 8601-1:2019 (extended) date
updated_at string 19 (top level) ISO 8601-1:2019 (extended) date
score integer 3 (top level)  
risk string 50 (top level)  
has_referral bool   (top level)  
referral_complete bool   (top level)  
forename string 50 contacts > client
contacts > referrer
contacts > third_party
  
surname string 50 contacts > client
contacts > referrer
contacts > third_party
  
email string 254 contacts > client
contacts > referrer
contacts > third_party
  
telephone string 15 contacts > client
contacts > referrer
contacts > third_party
 May include country calling code (eg. +44). All whitespace is removed
address_1 string 80 contacts > client  
address_2 string 80 contacts > client  
city string 50 contacts > client  
postcode string 8 contacts > client  
consent string 1 contacts > client
contacts > referrer 		 
organisation string 80 contacts > referrer  
role string 80 contacts > referrer  
concerns string 500 contacts > referrer
contacts > third_party 		 
id integer 5 questions
questions > options 		unsigned
title string 200 questions
questions > options 		 
body string 500 questions
questions > options 		 
value string 50 questions > options  

Conditional Response Fields

Name Condition
contacts > client > consent Will only be present in the response if the "No - I am completing this check for someone else" option was selected. This field indicates that the person completing the form has consent to fill in the form on behalf of the client.
contacts > third_party Will only be present in the response if the "No - I am completing this check for someone else" option was selected, and the third party checkbox was checked when populating the referral form.
contacts > referrer Will only be present if the "No - I am completing this check for someone else" option was selected, and any of the following answers were selected for the "How do you know the person you are filling this home fire safety check in for?" question:
  • Registered Carer / Support Worker
  • Approved Referrer / Partner Agency
  • FRS Employee
  • GP / Healthcare Worker
  • Police Officer / Law Enforcement
contacts > referrer > concerns
contacts > third_party > concerns 		Will only be present if the conditions for the parent container is met and the Additional Comments/Concerns input was populated when completing the referral.

Notes

  • ... indicates that the data is repeatable, and can contain multiple records of that type.
  • An option's value will only be populated for options which require user input.

Best Practices

  • When implementing this API call, save modified_to on successful requests, then you pass this as the modified_from for subsequent requests. This means you'll never be requesting data for the same period.
  • Always check if the session already exists using its id, to avoid duplication. Sessions can be modified and therefore may be returned by future requests.

GET https://ohfsc.safelincs.co.uk/api/questions

Returns all possible questions and their options.

JSON Response


  {
    "questions": [
      {
        "id": 1,
        "title": "Are you completing this fire safety check for yourself?",
        "body": "Please tell us whether you are answering these questions about your own home or somebody else's home.",
        "options": [
          {
            "id": 1,
            "title": "Yes – I am completing this check for my own home",
            "body": null
          },
          {
            "id": 2,
            "title": "No – I am completing this check for someone else",
            "body": null
          },
          ...
        ]
      },
      ...
    ]
  }

XML Response


  <?xml version="1.0"?>
  <response>
    <questions>
      <id>1</id>
      <title>Are you completing this fire safety check for yourself?</title>
      <body>Please tell us whether you are answering these questions about your own home or somebody else's home.</body>
      <options>
        <id>1</id>
        <title>Yes – I am completing this check for my own home</title>
        <body></body>
      </options>
      <options>
        <id>2</id>
        <title>No – I am completing this check for someone else</title>
        <body></body>
      </options>
      ...
    </questions>
    ...
  </response>

Response Index

Property Type Max Length Path(s) Notes
id integer 5 questions
questions > options 		unsigned
title string 200 questions
questions > options 		 
body string 500 questions
questions > options 		 

Notes

  • ... indicates that the data is repeatable, and can contain multiple records of that type.

DELETE https://ohfsc.safelincs.co.uk/api/sessions/{id}

Removes all personal identifiable information from a session.

Path Parameters

Name Type Required Description
id string Yes The ID of the session to remove personal identifiable information from.

JSON Response


  {
    "message": "All personal identifiable information was successfully removed.",
    "id": "f4be0c80d894f9da"
  }

XML Response


  <?xml version="1.0"?>
  <response>
    <message>All personal identifiable information was successfully removed.</message>
    <id>13ccc1b0fce0682c</id>
  </response>

Best Practices

  • This API call should be made after successfully processing a session via the GET /sessions call. This will remove all personal identifiable data from a session and prevent it from being retrieved by future requests.
@endsection