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-03-24T00: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: Mon, 24 Mar 2025 10:10:54 GMT
GET https://api.startexam.com/v2/sessions?center=mycenter&modifiedSince=2025-03-24T00: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: Mon, 24 Mar 2025 10:10: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: 1790

{
  "modifiedUntil": "2025-03-24T10:10:24Z",
  "continuationToken": null,
  "results": [
    {
      "participantId": "bca41692-e85e-49e9-8535-5fbedea1ea67",
      "testId": "6dbfe428-e369-45f7-8047-aa7c380f60c4",
      "testTitle": "MBA Preparation",
      "started": "2025-03-24T00:10:24Z",
      "isFinished": true,
      "autoClosed": true,
      "elapsedTime": "00:33:00",
      "score": 17.0,
      "maxScore": 20.0,
      "percent": 85.0,
      "scaleLevel": "Average Knowledge",
      "manualScoring": "notRequired",
      "modified": "2025-03-24T01:10: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": "c4625835-63cf-401b-9f67-a9f0c394bea8",
      "testId": "0f7d0bcb-4b99-46d5-90e9-4be93b54f5e1",
      "testTitle": "MBA Examination",
      "started": "2025-03-24T01:10:24Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2025-03-24T01:10: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: 1792

{
  "modifiedUntil": null,
  "continuationToken": "se02331582210410564987",
  "results": [
    {
      "participantId": "6cb28494-e418-4e5d-89eb-6b94ecd11dd8",
      "testId": "acac24da-1204-4cfa-8c93-feca2f06749c",
      "testTitle": "MBA Preparation",
      "started": "2025-03-24T00:10:24Z",
      "isFinished": true,
      "autoClosed": true,
      "elapsedTime": "00:33:00",
      "score": 17.0,
      "maxScore": 20.0,
      "percent": 85.0,
      "scaleLevel": "Average Knowledge",
      "manualScoring": "notRequired",
      "modified": "2025-03-24T01:10: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": "fdda04c5-aef2-4c2a-a453-8ca66178d584",
      "testId": "e4906e72-ffe8-4158-9639-4d1b3dcef47a",
      "testTitle": "MBA Examination",
      "started": "2025-03-24T01:10:24Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2025-03-24T01:10: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: 91

{
  "modifiedUntil": "2025-03-24T10:10:24Z",
  "continuationToken": null,
  "results": []
}

Try Method