Skip to main content

The API workflow

This page outline the API call sequence to make use of the TEC SDR APIs.

All these calls assume that you have a valid ESL authentication header that is scoped to the EDUMIS ID for the organisation that you are uploading data for.

Please review the following sequence diagram and refer to the notes below,

API Flow

1. List available Return Periods​

The Returns list itemizes the available month/year submissions that are available to upload data against. This is a simple GET request to list the available Returns

GET /submissions/v1.0/returns

This will return a paginated list of month/year returns

2. Request a Submission Token​

Choose a Return Period to work with and request a submission token to use working with a submission

POST /submissions/v1.0/token/202308

Where 202308 is the ID of the Return Period to submit data against. Please note that there are a set of scenarios where your request for a submission token will be declined, and you should handle the decline gracefully.

The response of this endpoint will include the following properties:

  • submissionToken
  • tokenExpiry - if you attempt to use the token after the token expiry the request wll fail.
  • maxBatchSize - the maximum number if items to include in an upload/delete batch. If you exceed this your request will fail.

3. Upload data​

Using the submissionToken upload data against the following collections:

  • Learners
  • Courses
  • Course Enrolments
  • Course Completions
  • Qualification Completions

An upload is a PUT to the appropriate endpoint with a JSON payload that includes the submissionToken and an array of appropriate objects, i.e.

Each record in the content array MUST have a localId field. This is a unique value that you supply to reference the record when updating or deleting.

The content array must not exceed the maxBatchSize from the token request.

PUT /submissions/v1.0/learners
{
    "submissionToken" : "1234"
    "content" : [
        {
            "localId" : "mylocalId-1",
            ...
        },
        {
            "localId" : "mylocalId-2",
            ...
        }
        ...
    ]
}

Any non 200 http response will indicate that your payload does not conform to the schema or that you have exceeded the maxBatchSize limit.

You may make subsequent calls to continue to upload data. If you reference an existing localId that record will be over written.

4. Delete data

You are able to delete data that you have uploaded by referencing the localId

DELETE /submissions/v1.0/learners
{
    "submissionToken" : "1234"
    "content" : [
        {
            "localId" : "mylocalId-1"
        },
        {
            "localId" : "mylocalId-2",
        }
        ...
    ]
}

5. Validate uploaded data

To request validation of upload data call the validate endpoint with the submissionToken

POST /submissions/v1.0/validate/1234

Requesting validation will block subsequent requests for submission tokens or data manipulations until the validation is complete.

You can track the progress of the validation by calling

GET /submissions/v1.0/validation/1234

6. Reset and start again

If for any reason you wish to start again for a given Return Period, you can delete your submission data and request and new submission token.

Delete token:

DELETE /submissions/v1.0/token/1234/delete

Request a new token:

POST /submissions/v1.0/token/202308