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-03T00: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: Thu, 03 Apr 2025 03:05:59 GMT
GET https://api.startexam.com/v2/sessions?center=mycenter&modifiedSince=2025-04-03T00: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: Thu, 03 Apr 2025 03:05:59 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-03T03:05:29Z",
  "continuationToken": null,
  "results": [
    {
      "participantId": "d6e32472-2fa7-45be-8c2b-da4451ded4b6",
      "testId": "938aafa6-1915-4330-8afd-386eafc32694",
      "testTitle": "MBA Preparation",
      "started": "2025-04-02T17:05:29Z",
      "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-02T18:05:29Z",
      "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": "e73d9594-002a-436f-86f0-f8cd22ffc31b",
      "testId": "73268b0f-e8c9-4bc3-9583-37a69b2be0b2",
      "testTitle": "MBA Examination",
      "started": "2025-04-02T18:05:29Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2025-04-02T18:05:29Z",
      "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": "50b4066e-5c2c-46e9-8c94-0db213a5f9a7",
      "testId": "f3b740c5-6b40-4c07-9ed4-b55d0b4f2c50",
      "testTitle": "MBA Preparation",
      "started": "2025-04-02T17:05:29Z",
      "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-02T18:05:29Z",
      "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": "0faa1bbd-2147-4c80-bf56-4294c1f20c0c",
      "testId": "9fd6b2b8-1d2f-4568-8aaa-ca2955ae4744",
      "testTitle": "MBA Examination",
      "started": "2025-04-02T18:05:29Z",
      "isFinished": false,
      "autoClosed": false,
      "elapsedTime": null,
      "score": null,
      "maxScore": null,
      "percent": null,
      "scaleLevel": null,
      "manualScoring": "required",
      "modified": "2025-04-02T18:05:29Z",
      "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-03T03:05:29Z",
  "continuationToken": null,
  "results": []
}

Try Method