Data Verification API

Data Verification API Place holder

 

Purpose

The Data Verification API is a REST API, providing a service to allow authorised consumers to verify key data they hold against. This verification is performed against data held within SIMS for Schools that have opted in to allow the Data Verification service to use their data.

This service does not provide any access to the underlying data.

Conceptual Operation

When a correctly formed request is sent to the API by an authenticated and authorised application, the API will issue a yes/no-based response. This response will also contain a confidence score.

This approach is used to ensure data is not exposed that could be useful to malicious actors, and no access is granted to the underlying data.

The API is scalable to meet demand and is load balanced across multiple UK/EU datacentres.

Basic API information

Security

The API is secured by OAuth 2.0, and each client application accessing the API will need to present a valid access token in the Authorization header of the request. Each access token will need to contain specific scopes, and these scopes will only be granted to clients specifically allowed to call the API.

HTTP Methods

Only the following HTTP method is allowed when using this API:

GET

The following HTTP methods are not allowed by the API, and will be rejected with a 415 method not allowed response, regardless of whether the client is authenticated and authorised or not:

POST

PUT

PATCH 

DELETE

OPTIONS

Constraints

The validation of data by the API is dependent on the accuracy in SIMS as the source of truth, and up to date data synchronisation between SIMS and SIMS ID.

The API will only validate SIMS data for users in Schools that have accepted the GDPR statement for the relevant service that uses the API.

Where an individual’s data record is made up of data controlled and sourced from more the one site, if not all sites opt into sharing data with this service an incomplete record may be available for matching.

API Documentation

API endpoint documentation is available, using Swagger, with the following restrictions:

• The Try It Out function is disabled

Swagger Endpoint location (sample data)

https://simsid-partner-verify.azurewebsites.net/

Semantic versioning

There will only be one endpoint, and the current version is V1. Each breaking change will have an incremented version number, however we will always support current version -1.

Further API information

• The API will only be accessible via HTTPS, using current SSL/TLS versions and standards within SIMS ID
• The API will audit all attempts to access
• Bearer tokens to access the API will be issued by the SIMS ID STS Server, and the API will validate bearer tokens with the SIMS ID STS Server
• Only the GET method will be whitelisted
• Any requests not matching the whitelisted GET method will have a 405 Method not allowed response returned
• Input parameters/objects will not be trusted and always validated for length, range, format and type
• Input parameters will achieve an implicit input validation by using strong types like numbers, booleans, dates, times or fixed data ranges where possible. String inputs will use regexp validation.
• If a bearer token is missing in a request, a 401 unauthorized response will be returned
• If a bearer token is present in a request, but the bearer token is invalid of does not have the required scope permissions, a 403 unauthorised response will be returned
• Unexpected or illegal content will be returned a 400 Bad request response
• If the request size limit is exceeded, reject requests exceeding this limit with HTTP response status 413 Request Entity Too Large.
• If the request does not contain "application/json", the request is rejected with a 406 Not Acceptable response returned.
• Error 500 details (call stacks and other technical details) must not be returned to the calling client. A generic error message must be used.
• The API will send an X-Frame-Options: deny to protect against drag and drop clickjacking attacks in older browsers.
• CORS headers will be disabled as cross-domain calls are not supported in this API
• The API is stateless, to allow for multiple load balanced instances

INPUT Parameters and expected responses

Inputs

Input Methods

Name	Type	Max Length	Required
Parent Contact (Email or Phone)	String	255	Yes
Parent Post Code	String	12	No
Parent Firstname	String	400
Parent Surname	String	400	No
Child Firstname	String	400	No
Child Surname	String	400	No
Child Date of Birth	Date	10	No

No

 

 

Amendments can be made to the required element.

 

 

Responses

200 OK responses will be in the format of:

User Found – the given persons is associated with the child and their is no indication of a 'barring' court order being noted
200 OK
{"response": "yes", "child_score": "X", "parent_score": "X"} 

User Not Found - either the persons are unknown or the parent is not an adult associated the child
200 OK
{"response": "no"}

Confidence Scores

The scores returned in the response for parent and child are confidence scores based on the ability to match supplied data. This allows for further decision making by the consuming service based on “User Found” responses.

Different services will require differing levels of confidence.

Name	Child Points if Matched	Points if Matched
Date of Birth	2.0	N/A
Forename	0.5	0.5
Surname	1.0	1
Post Code	N/A	2

 

Example use.

 

A Parental Satisfaction service is being developed for gathering Net Promoter Score style responses that are attributable to a genuine parent user. The system is not fed with data from SIMS and the school is not involved with the creation of user accounts to preserve independence and impartiality of the system.

Users are able to self-register but there is a requirement to ensure the person filling in the registration is indeed a valid parent at the site.  The system asks for pertinent information from the response on their identity and the identity of their child.  This information is then presented to the Data Verification API to confirm that this is a bona fide application.

The following examples assume that a child match score of >2 is required and a parent match score of >2 is required for a confident match. 

If a parent email address is sent through that is found in SIMS ID, with a matching parent forename, a matching parent surname, a matching child forename and a matching child DoB, the confidence scores returned will be:

Parent -1.5 – Suggested as Not Sufficient

Child – 2.5 – Confident match

If a parent email address is sent through that is found in SIMS ID, with a matching parent forename, a matching parent postcode, a matching child forename and a non-matching child DoB, the confidence scores returned will be:

Parent -2.5 – Confident match

Child – 2.5 – Confident match

If a parent email address is sent through that is found in SIMS ID, with a matching parent forename, a matching parent surname, a matching parent postcode, a matching child forename, a matching child surname, and a non-matching child DoB, the confidence scores returned will be:

Parent -3.5 – Confident match

Child – 1.5 – Suggested as Not Sufficient

The weightings for each matching field is configurable to allow for finalisation during the integration testing phase should further elements be added.