Get Sessions

Method returns sessions which were modified since specified date and time.

Method can be used to sync sessions results between StartExam and external system by schedule:

  • Call method by schedule. Every 10 minutes is recommended.
  • First time use some historical constant modifiedSince that makes sense, for example: 2021-01-01T00:00:00Z
  • After each successful request save modifiedUntil.and use it in the next request as modifiedSince parameter.
  • Never use your own Utc.Now() as modifiedSince parameter to avoid data loss and 400 errors.
  • Use retry logic - if server is unavailable, wait for some time and call again using latest saved modifiedUntil.

Method returns maximum 500 sessions in one response and supports paging with continuation token:

  • If continuationToken is returned by server instead of modifiedUntil, it means that server has more pages to return.
  • Don't wait and do a next request using original filters and received continuationToken as a parameter.
  • For every new page server returns new continuationToken, so use it only once to avoid endless loops.
  • After everything is synced, server returns modifiedUntil instead of continuationToken. Save it as usual. Paging finished.

Request Information

Scheme

GET https://api.startexam.com/v2/sessions?center={center}&modifiedSince={modifiedSince}&continuationToken={continuationToken}

URI Parameters

  • center - center unique name. The value can be retrieved from the center details page.
  • modifiedSince - date and time since which all new and modified sessions should be retrieved, UTC, ISO 8601.
  • continuationToken - ask next 500 sessions from the server using token from previous response, string.

Body Parameters

None.

Request Examples

GET https://api.startexam.com/v2/sessions?center=mycenter&modifiedSince=2021-09-26T00:00:00Z HTTP/1.1
Host: api.startexam.com
Accept: application/json; charset=utf-8
Authorization: SharedKey 99:f52JP7GQd0xqrBzMO1NWTNVGzLENymgdUXu/Ie++NX4=
Content-Type: application/json; charset=utf-8
Date: Sun, 26 Sep 2021 16:14:54 GMT
GET https://api.startexam.com/v2/sessions?center=mycenter&modifiedSince=2021-09-26T00:00:00Z&continuationToken=se02331582210410564987 HTTP/1.1
Host: api.startexam.com
Accept: application/json; charset=utf-8
Authorization: SharedKey 99:f52JP7GQd0xqrBzMO1NWTNVGzLENymgdUXu/Ie++NX4=
Content-Type: application/json; charset=utf-8
Date: Sun, 26 Sep 2021 16:14:54 GMT

Date and Authorization headers are constructed in the standard way.

Response Information

HTTP status code

200 OK, 400 Bad Request, etc. according the response processing guide.

Content-Type

Json.

Content

  • modifiedUntil - last successful sync time, UTC, ISO 8601. Should be saved and used as modifiedSince in the next request.
    If server has more data to return = NULL.
  • continuationToken - token to request next page of data, string.
    If server has no more data to return = NULL.
  • results - array of test sessions, can be empty if there is nothing new.
    • participantId - participant id, guid.
    • testId - test id, guid.
    • testTitle - test title, string.
    • started - session started date-time in UTC, ISO 8601.
    • isFinished - session finished flag, true/false.
    • autoClosed - participant has left system and session was closed automatically by timeout, true/false.
    • elapsedTime - testing time, HH:MM:SS, nullable.
    • score - participant score, double, nullable.
    • maxScore - maximum possible score, double, nullable.
    • percent - percent, double with 2 decimals, nullable.
    • scaleLevel - participant level from Test settings, nullable.
    • manualScoring - manual scoring status. Supported values: unknown, notRequired, required, completed.
    • modified - participant modified date-time in UTC, ISO 8601.
    • participantData - personal data of a participant.

If a participant hasn't finished a session, some fields (elapsedTime, score, maxScore, percent, scaleLevel, outcomes) will be not returned as nullable.

Response Examples

Example 1: Server returns some results and modifiedUntil which means there are no more sessions, everything synced. Client must save modifiedUntil.
Example 2: Server returns some results and continuationToken which means there are more sessions. Client must request a new page with this continuationToken.
Example 3: Server returns no results and modifiedUntil which means there are no new sessions, everything synced. Client must save modifiedUntil.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1861

{
  "modifiedUntil": "2021-09-26T16:14:24Z",
  "continuationToken": null,
  "results": [
    {
      "participantId": "840cd4fb-3c83-4f33-85b4-1dc9a9c44ebf",
      "testId": "a6c7f0af-88ea-4108-9cf7-0f254b971020",
      "testTitle": "MBA Preparation",
      "started": "2021-09-26T06:14:24Z",
      "isFinished": true,
      "autoClosed": true,
      "elapsedTime": "00:33:00",
      "score": 17.0,
      "maxScore": 20.0,
      "percent": 85.0,
      "scaleLevel": "Average Knowledge",
      "manualScoring": "notRequired",
      "modified": "2021-09-26T07:14:24Z",
      "participantData": [
        {
          "name": "First Name",
          "value": "John"
        },
        {
          "name": "Last Name",
          "value": "Lennon"
        },
        {
          "name": "Email",
          "value": "lennon@gmail.com"
        },
        {
          "name": "My Custom Field Name",
          "value": "000000001"
        }
      ]
    },
    {
      "participantId": "dce3d19c-601a-4074-95ad-37f94081bf37",
      "testId": "a83c4055-f0f3-4115-be90-1a05a2f95667",
      "testTitle": "MBA Examination",
      "started": "2021-09-26T07:14:24Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2021-09-26T07:14:24Z",
      "participantData": [
        {
          "name": "First Name",
          "value": "Frank"
        },
        {
          "name": "Last Name",
          "value": "Sinatra"
        },
        {
          "name": "Email",
          "value": "frank@sinatra.com"
        },
        {
          "name": "My Custom Field Name",
          "value": "000000002"
        }
      ]
    }
  ]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1863

{
  "modifiedUntil": null,
  "continuationToken": "se02331582210410564987",
  "results": [
    {
      "participantId": "9597f277-0e28-467b-acf4-c57af0fd1946",
      "testId": "06b941b5-c466-45fa-b1e8-d6a999bf6b70",
      "testTitle": "MBA Preparation",
      "started": "2021-09-26T06:14:24Z",
      "isFinished": true,
      "autoClosed": true,
      "elapsedTime": "00:33:00",
      "score": 17.0,
      "maxScore": 20.0,
      "percent": 85.0,
      "scaleLevel": "Average Knowledge",
      "manualScoring": "notRequired",
      "modified": "2021-09-26T07:14:24Z",
      "participantData": [
        {
          "name": "First Name",
          "value": "John"
        },
        {
          "name": "Last Name",
          "value": "Lennon"
        },
        {
          "name": "Email",
          "value": "lennon@gmail.com"
        },
        {
          "name": "My Custom Field Name",
          "value": "000000001"
        }
      ]
    },
    {
      "participantId": "aab25253-b3d0-4eb2-80c4-aaf0d4a1241f",
      "testId": "f7d1a451-eeae-48d2-bc15-a3d5e6854f4a",
      "testTitle": "MBA Examination",
      "started": "2021-09-26T07:14:24Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2021-09-26T07:14:24Z",
      "participantData": [
        {
          "name": "First Name",
          "value": "Frank"
        },
        {
          "name": "Last Name",
          "value": "Sinatra"
        },
        {
          "name": "Email",
          "value": "frank@sinatra.com"
        },
        {
          "name": "My Custom Field Name",
          "value": "000000002"
        }
      ]
    }
  ]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 95

{
  "modifiedUntil": "2021-09-26T16:14:24Z",
  "continuationToken": null,
  "results": []
}

Try Method