API Documentation

A simple RESTful JSON web API to create and manage A2E assessments.

Your Access Token (or API Key) is available in the Account Administration section.

Assessment

Organisation

Create an Assessment

URL: 

https://us.esherhouse.org/v2/assessments

HTTP Method: 

POST

Parameters:

access_token
Your Access Token (or API Key)
Example: "MQvCGNFqxWeURhtHRt43ySa0"
type
Assessment Type (belongs to your Organisation)
Example: "Education", "Apprenticeship", "Employment"
candidate_id
Candidate ID
Example: "123456789", "ABC3XY07R"
name
Name
Example: "John Han", "Peter Chen"
email
Email
Example: "your-email@domain.com"

Successful response:

HTTP Code: 

200 OK

Content: 

{
  "assessment": {
    "token": "qRddQPQ8oQTohTxxh4fXSTXC",
    "stage": null,
    "rating": "N/A",
    "probability": "N/A",
    "completed_at": null,
    "created_at": "2024-12-27 00:00:00 UTC",
    "updated_at": "2024-12-27 00:00:00 UTC",
    "organisation_credit_balance": 1,
    "creator": {
      "email": "example@example.com",
      "first_name": "George",
      "surname": "Jungle"
    },
    "jobseeker_id": "10000001",
    "jobseeker_name": "Jane",
    "scores": null,
    "site": {
      "name": "Sydney"
    },
    "assessment_type": {
      "name": "Type"
    },
    "status": "Not Completed",
    "exercise": null,
    "exercises": [

    ]
  }
}
Error responses:

HTTP Code: 

401 Unauthorized

Content: 

nil
Sample cURL code:
curl -H "Content-Type: application/json" -X POST --data '{"access_token": "ND1sSWNNmXgut8u2P7W6wwby","type":"Education"}' "https://us.esherhouse.org/v2/assessments"

View an Assessment

URL: 

https://us.esherhouse.org/v2/assessments/{token}

HTTP Method: 

GET

Parameters:

token
The unique assessment token
Example: "qRddQPQ8oQTohTxxh4fXSTXC"
access_token
Your Access Token (or API Key)
Example: "MQvCGNFqxWeURhtHRt43ySa0"

Successful response:

HTTP Code: 

200 OK

Content: 

{
  "assessment": {
    "token": "qRddQPQ8oQTohTxxh4fXSTXC",
    "stage": null,
    "rating": "N/A",
    "probability": "23%",
    "completed_at": "2024-12-27 01:16:38 UTC",
    "created_at": "2024-12-27 00:00:00 UTC",
    "updated_at": "2024-12-27 00:00:00 UTC",
    "organisation_credit_balance": 1,
    "creator": {
      "email": "example@example.com",
      "first_name": "George",
      "surname": "Jungle"
    },
    "jobseeker_id": "10000001",
    "jobseeker_name": "Jane",
    "scores": {
      "total_matrix_points": 23
    },
    "site": {
      "name": "Sydney"
    },
    "assessment_type": {
      "name": "Type"
    },
    "status": "Completed",
    "exercise": null,
    "exercises": [
      {
        "name": "HIGHLY LIKELY TO SUCCEED",
        "path": "/exercise/xxxExamplexxx",
        "answers_url": null,
        "percentage_completed": 0,
        "completed_at": null,
        "due_on": "2025-02-07",
        "motivation": "Doing this will make you a better person."
      }
    ]
  }
}
Error responses:

HTTP Code: 

401 Unauthorized

Content: 

nil

HTTP Code: 

404 Not Found

Content: 

{"error":"RecordNotFound"}
Sample cURL code:
curl -H "Content-Type: application/json" -X GET --data '{"access_token": "ND1sSWNNmXgut8u2P7W6wwby"}' "https://us.esherhouse.org/v2/assessments/qRddQPQ8oQTohTxxh4fXSTXC"

Retrieve Assessments

URL: 

https://us.esherhouse.org/v2/assessments/?created_at[from]={from_date}&created_at[to]={to_date}

HTTP Method: 

GET

Parameters:

created_at[from]
From Date. e.g: "2018-01-01"
created_at[to]
To Date. e.g: "2018-01-31"
completed_at[from]
From Date. e.g: "2018-01-01"
completed_at[to]
To Date. e.g: "2018-01-31"
per_page
Return results per request. e.g: 5 (optional)
page
Return results page per request. e.g: 1 (optional)
access_token
Your Access Token (or API Key). e.g: "MQvCGNFqxWeURhtHRt43ySa0"

Successful response:

HTTP Code: 

200 OK

Content: 

{
  "assessments": [
    {
      "token": "qRddQPQ8oQTohTxxh4fXSTXC",
      "stage": null,
      "rating": "N/A",
      "probability": "23%",
      "completed_at": "2024-12-27 01:16:38 UTC",
      "created_at": "2024-12-27 00:00:00 UTC",
      "updated_at": "2024-12-27 00:00:00 UTC",
      "organisation_credit_balance": 1,
      "creator": {
        "email": "example@example.com",
        "first_name": "George",
        "surname": "Jungle"
      },
      "jobseeker_id": "10000001",
      "jobseeker_name": "Jane",
      "scores": {
        "total_matrix_points": 23
      },
      "site": {
        "name": "Sydney"
      },
      "assessment_type": {
        "name": "Type"
      },
      "status": "Completed",
      "exercise": null,
      "exercises": [
        {
          "name": "HIGHLY LIKELY TO SUCCEED",
          "path": "/exercise/xxxExamplexxx",
          "answers_url": null,
          "percentage_completed": 0,
          "completed_at": null,
          "due_on": "2025-02-07",
          "motivation": "Doing this will make you a better person."
        }
      ]
    }
  ]
}

Error responses:

HTTP Code: 

401 Unauthorized

Content: 

nil
Sample cURL code:
curl -H "Content-Type: application/json" -X GET --data '{"access_token": "ND1sSWNNmXgut8u2P7W6wwby", "per_page": 10, "created_at": { "from": "2017-01-01", "to": "2018-01-01"}}' "https://us.esherhouse.org/v2/assessments"

Assessment Callbacks

When an assessment is completed we will send an immediate callback to the URL nominated for your organistation during setup.

The callback content is the finished assessment record encrypted as a JSON Web Token.

Content: 

{"jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhc3Nlc3NtZW50Ijp7InRva2VuIjoiWXlURDVMSmNFa0NjYVNyTjVIdFoyem1LIiwic3RhZ2UiOiJVbnJlZmxlY3RpdmVBY3Rpb24iLCJyYXRpbmciOiJTaWx2ZXIiLCJjb21wbGV0ZWRfYXQiOiIyMDE3LTAzLTAzIDAzOjI3OjAyIFVUQyIsImNyZWF0ZWRfYXQiOiIyMDE3LTAzLTAzIDAzOjI2OjI4IFVUQyIsInVwZGF0ZWRfYXQiOiIyMDE3LTAzLTAzIDAzOjI3OjAyIFVUQyIsIm9yZ2FuaXNhdGlvbl9jcmVkaXRfYmFsYW5jZSI6OTk5OTk5MX19.iv6auvL7pRzSHcUcLV0I3Z_caAllVSxLQG16l0KDrX4"}

The JSON Web Token can be validated using your Access Token and the HS256 algorithm.

Sample Ruby Code:

# using https://github.com/jwt/ruby-jwt
require 'jwt'
JWT.decode(params[:jwt], ENV['API_KEY'], true, { algorithm: 'HS256' })
=>[{"assessment":{"token":"qRddQPQ8oQTohTxxh4fXSTXC","stage":null,"rating":"N/A","probability":"23%","completed_at":"2024-12-27T01:16:38.737Z","created_at":"2024-12-27T00:00:00.000Z","updated_at":"2024-12-27T00:00:00.000Z","organisation_credit_balance":1,"creator":{"email":"example@example.com","first_name":"George","surname":"Jungle"},"jobseeker_id":"10000001","jobseeker_name":"Jane","scores":{"total_matrix_points":23},"site":{"name":"Sydney"},"assessment_type":{"name":"Type"},"status":"Completed","exercise":null,"exercises":[{"name":"HIGHLY LIKELY TO SUCCEED","path":"/exercise/xxxExamplexxx","answers_url":null,"percentage_completed":0,"completed_at":null,"due_on":"2025-02-07","motivation":"Doing this will make you a better person."}]}},{"alg":"HS256"}]

View Your Organisation

URL: 

https://us.esherhouse.org/v2/organisation

HTTP Method: 

GET

Parameters:

access_token
The unique organisation access token
Example: "ND1sSWNNmXgut8u2P7W6wwby"

Successful response:

HTTP Code: 

200 OK

Content: 

{"organisation":{"name":"Master","credit_count":100,"callback_url":"","assessment_types":["Workers Compensation","PaTH"],"created_at":"2018-04-09T16:26:55.102+10:00","updated_at":"2018-04-12T14:12:30.973+10:00"}}%
Error responses:

HTTP Code: 

401 Unauthorized

Content: 

nil
Sample cURL code:
curl -H "Content-Type: application/json" -X GET --data '{"access_token": "ND1sSWNNmXgut8u2P7W6wwby"}' "https://us.esherhouse.org/v2/organisation"

Set Organisation callback

URL: 

https://us.esherhouse.org/v2/organisation

HTTP Method: 

PUT

Parameters:

access_token
The unique organisation access token
Example: "ND1sSWNNmXgut8u2P7W6wwby"
organisation[callback_url]
Callback url when surveys get updated
Example: "https://my.site/callback"

Successful response:

HTTP Code: 

200 OK

Content: 

{
  "organisation": {
    "name": null,
    "credit_count": 1,
    "callback_url": "https://my.site/callback",
    "assessment_types": [

    ],
    "errors": {
    },
    "created_at": "2024-12-27 00:00:00 UTC",
    "updated_at": "2024-12-27 00:00:00 UTC"
  }
}
Error responses:

HTTP Code: 

422 Unprocessable Entity

Content: 

{
  "organisation": {
    "name": null,
    "credit_count": 1,
    "callback_url": "https://my.site/callback",
    "assessment_types": [

    ],
    "errors": {
      "callback_url": [
        "is invalid"
      ]
    },
    "created_at": "2024-12-27 00:00:00 UTC",
    "updated_at": "2024-12-27 00:00:00 UTC"
  }
}
Sample cURL code:
curl -H "Content-Type: application/json" -X PUT --data '{"access_token":"ND1sSWNNmXgut8u2P7W6wwby","organisation":{"callback_url":"https://my.site/callback"}}' "https://us.esherhouse.org/v2/organisation"

Download Coaching Guide

Coaching Guide is available when an assessment is completed.

URL: 

https://us.esherhouse.org/v2/assessments/{token}/coaching_guide

HTTP Method: 

GET

Parameters:

token
The unique assessment token
Example: "qRddQPQ8oQTohTxxh4fXSTXC"
access_token
Your Access Token (or API Key)
Example: "MQvCGNFqxWeURhtHRt43ySa0"

Successful response:

HTTP Code: 

200 OK

Content: 

{"path":"coaching_guide_path","error":""}
Error responses:

HTTP Code: 

401 Unauthorized

Content: 

nil

HTTP Code: 

404 Not Found

Content: 

{"path":"","error":"Coaching Guide is not available"}
Sample cURL code:
curl -H "Content-Type: application/json" -X GET --data '{"access_token": "ND1sSWNNmXgut8u2P7W6wwby"}' "https://us.esherhouse.org/v2/assessments/qRddQPQ8oQTohTxxh4fXSTXC/coaching_guide"

Download Assessment Attachment

Assessment Attachment is available whether an assessment is completed or not and if it was uploaded by admin(glo).

URL: 

https://us.esherhouse.org/v2/assessments/{token}/attachment

HTTP Method: 

GET

Parameters:

token
The unique assessment token
Example: "qRddQPQ8oQTohTxxh4fXSTXC"
access_token
Your Access Token (or API Key)
Example: "MQvCGNFqxWeURhtHRt43ySa0"
attachment_name
Attachment Name
Example: "Some Attachment Name"

Successful response:

HTTP Code: 

200 OK

Content: 

{"path":"assessment_attachment_path",}
Error responses:

HTTP Code: 

401 Unauthorized

Content: 

nil

HTTP Code: 

404 Not Found

Content: 

{"error":"Attachment is not available"}
Sample cURL code:
curl -H "Content-Type: application/json" -X GET --data '{"access_token": "MQvCGNFqxWeURhtHRt43ySa0", "attachment_name": "Some Attachment Name"}' "https://us.esherhouse.org/v2/assessments/qRddQPQ8oQTohTxxh4fXSTXC/attachment"