Skip to content

SFTP learner uploads

SFTP is a secondary, partial way in: it creates learners from a scheduled CSV file, for source systems that can only emit a batch export and cannot call an API. Reach for it only after webhooks and the API, because it does one job and stops there.

  • It is one-way in. It pushes learners into Cognassist and nothing more.
  • It does not read any data out: no assessment results, no evidence, no support records, no reconcile of learners you already hold.
  • It is not available for everything. It creates learners, and only learners.

So SFTP is a limited fallback for getting learners in when you cannot call the API. It is not a complete integration on its own. For the primary, event-driven path (webhooks first, the API for everything else, polling only as a fallback), start at planning your integration, and use keep in sync to compare webhooks, polling, and this file.

In plain terms: you drop a correctly formatted CSV onto a Cognassist file server, and every learner in it is created automatically. This page assumes you are comfortable with an SFTP client such as WinSCP or FileZilla, or the command line.

An SFTP upload always creates, so do not also create the same learners through the API

SFTP does not match, update, or de-duplicate against learners that already exist, and neither does the API's create call. Load the same people over SFTP and through POST /v1/learners and you get duplicate learner records. Choose one route as the system of record for creating a given learner, and keep your own clientReference unique on your side so two sources cannot both create the same person. Matching against learners Cognassist already holds is an API job: see reconcile against your system.

Get access

Request SFTP through the single get access route, saying you need SFTP access for learner uploads. There is no self-service form; if you are already working with a Cognassist account manager or onboarding contact, they can raise the request for you. Once it is processed, Cognassist issues the connection credentials described in connect and upload.

Choose a template

Learners are uploaded with one of two CSV templates, depending on the kind of account you have. Download the one that matches, fill it in using the field rules below, and keep the header row exactly as supplied.

Each column carries the same learner data you would send when creating a learner through the API. The CSV has its own accepted values and casing, which differ from the API in a few places, so follow the table below for the file rather than the API examples. For the API's own field schema and enums, see the API reference.

CSV field rules (accepted values and casing for the file)

This is the one place the field rules are specific to the CSV. Where a value differs from the API, that is called out in the row.

Field Rule for the CSV
First Name Not empty; no other rules.
Last Name Not empty; no other rules.
Gender Lowercase male or female, or blank if you prefer not to disclose it. The CSV expects lowercase; the API's gender field uses its own accepted values and casing (see the API reference).
Date Of Birth DD/MM/YYYY or DD/MM/YY.
Email Address A valid email address, for example example@email.com. This is also the learner's invite address.
Post Code A valid UK postcode, with a space between the elements.
Client Reference Mandatory. Your own stable reference for this learner, in any format. This is the primary key you own and keep unique to avoid duplicates. Maps to the API's clientReference. Your organisation is a single client with one SFTP connection.
Programme Level Mandatory for Apprenticeships and education accounts. The learner's current level of education, or the value for Adult Education Budget. Maps to the API's programmeLevel (an integer 1 to 7, optional on the API).
Tutor Email Address A valid email that belongs to a currently registered tutor in your organisation. The tutor must already exist before the upload runs.
Mobile Number Optional. No international dialling code. Either 11 digits starting with 07, or 10 digits starting with 7 (dropping the leading 0).
End Date Optional, Apprenticeships and education accounts only. The learner's fixed course end date, if known, in DD/MM/YYYY or DD/MM/YY.
Programme Type Optional. Internal or External, otherwise blank. Applied only if your administrator has enabled programme types.

Tutors must exist first. Each learner is assigned to a tutor by email, and that tutor must already be set up in Cognassist. Tutors cannot be created from a file or from the API, so provision them first; a row with an unrecognised tutor email will not create its learner. This is the same tutor dependency that applies to API creates, described in create and manage learners.

Connect and upload

Once your request is processed, Cognassist provides connection credentials. Use them to connect securely to the Cognassist file server from an SFTP client or a command shell, then place your correctly formatted CSV in the root directory the session opens at. Transferring the file is the only action needed: the upload triggers automatically as soon as the transfer completes, and you can view the outcome of each upload on the Learner import history page in the Cognassist platform.

Mapping the credentials to your SFTP client

Cognassist supplies three values. Map them as follows.

Credential How to use it
Connection The Host name in your client's connection settings.
User Name The User name in your client, or the username part of a command-shell request in the form username@hostname.
Password Sits next to the User name in your client. From a command shell you are prompted for it after you submit the connection request.

Treat these credentials as secret. Anyone who holds them can add learners to your estate, so do not share them outside your organisation or with anyone inside it who should not create learners. If they are ever lost or compromised, contact Cognassist through the get access route as soon as possible: we can re-supply the connection and user name, or issue a new password.

When SFTP is the right choice

SFTP suits an estate whose source system can produce a file but cannot make or receive API calls, which is common for on-premises further-education systems. Before you commit, keep its two boundaries in mind:

  • It is create-only and one-directional. It puts learners in. It does not send results, evidence, or any data back out, and it does not update or reconcile existing learners. For all of that, use the API and webhooks: see keep in sync.
  • It creates learners, not staff. Tutors are provisioned in the app, never from the file, and every learner row needs a tutor email that already exists.

If you also want people to sign in to the Cognassist web platform with your own identity provider, that is configured separately: see single sign-on.