StartExam API

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: 2025-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=2025-04-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: Sat, 26 Apr 2025 11:28:38 GMT
GET https://api.startexam.com/v2/sessions?center=mycenter&modifiedSince=2025-04-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: Sat, 26 Apr 2025 11:28:38 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: 1790

{
  "modifiedUntil": "2025-04-26T11:28:08Z",
  "continuationToken": null,
  "results": [
    {
      "participantId": "ce28bad0-499e-4aea-81a9-0634d71b6e02",
      "testId": "2f6c7378-91ed-4872-878a-26d41c37c7bc",
      "testTitle": "MBA Preparation",
      "started": "2025-04-26T01:28:08Z",
      "isFinished": true,
      "autoClosed": true,
      "elapsedTime": "00:33:00",
      "score": 17.0,
      "maxScore": 20.0,
      "percent": 85.0,
      "scaleLevel": "Average Knowledge",
      "manualScoring": "notRequired",
      "modified": "2025-04-26T02:28:08Z",
      "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": "8e77c0ca-2d8c-4494-98b9-dfc315990fab",
      "testId": "10aba5e9-59e5-4f50-b6ed-2b86a6f05582",
      "testTitle": "MBA Examination",
      "started": "2025-04-26T02:28:08Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2025-04-26T02:28:08Z",
      "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: 1792

{
  "modifiedUntil": null,
  "continuationToken": "se02331582210410564987",
  "results": [
    {
      "participantId": "deff3a0a-29f4-4c61-b2a7-9e98419eb2d0",
      "testId": "0f3afa51-8daf-4f1e-b939-e5d11fc34b24",
      "testTitle": "MBA Preparation",
      "started": "2025-04-26T01:28:08Z",
      "isFinished": true,
      "autoClosed": true,
      "elapsedTime": "00:33:00",
      "score": 17.0,
      "maxScore": 20.0,
      "percent": 85.0,
      "scaleLevel": "Average Knowledge",
      "manualScoring": "notRequired",
      "modified": "2025-04-26T02:28:08Z",
      "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": "2f54c730-cd87-4f42-8983-5779625ca1da",
      "testId": "6a223e86-8275-4a98-b68b-3d8236e4457f",
      "testTitle": "MBA Examination",
      "started": "2025-04-26T02:28:08Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2025-04-26T02:28:08Z",
      "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: 91

{
  "modifiedUntil": "2025-04-26T11:28:08Z",
  "continuationToken": null,
  "results": []
}

Try Method