High-level overview

The University-initiated enrolment flow is used when a partner university needs to enrol one of their students on a degree or program within FutureLearn. In particular it is used to enrol students that have applied for a degree or program directly through the university's own application and enrolment portals (as opposed to through the FutureLearn degree and program pages where the FutureLearn initiated enrolment flow is more appropriate).

The flow starts with the partner university making a call to the FutureLearn partners API to check for an organisation membership (the record that essentially represents a student at the university) with a particular university ID.

If no matching organisation membership exists, the university calls the partners API again to create the organisation membership. The API responds with a unique FutureLearn invitation link that the university forwards to the student as part of a welcome email.

The university then makes further calls to the FutureLearn partners API to create the relevant degree and program enrolments. If the organisation membership is already linked to a FutureLearn account, those enrolments are activated immediately without requiring any action from the student. Otherwise activation of the enrolments is deferred until the student has followed the invitation link to link their organisation membership to a FutureLearn account.

When the student clicks on the FutureLearn invitation link in the welcome email from the university, they are asked to sign in or register for a FutureLearn account. They are also asked to consent to the account being linked to their university ID and to FutureLearn sharing certain types of data with the university.

Assuming that the student does give their consent, the organisation membership and enrolments are linked the chosen FutureLearn account and the student is taken to the degree or program landing page to start their learning.

 

Definitions

Entities

Entity	Description
Degree	A degree level qualification offered through FutureLearn (e.g. Graduate Certificate or Masters). Made up of programs
Degree enrolment	A learner’s enrolment on a degree in FutureLearn
Learner	A user of the FutureLearn platform
Program	A collection of FutureLearn courses. Equivalent to what a university may call a module or unit
Program run	A run (instance or offering) of a program starting on a specific date
Program enrolment	A learner’s enrolment on a program run in FutureLearn
Organisation membership	A record that links a learner to an organisation
Single program enrolment	A program enrolment that is not linked to a degree enrolment (for universities that allow students to enrol on a program without enrolling on a degree)
Student	A learner that is enrolled at the university and whose FutureLearn account is linked via an organisation membership to their university ID

 

Identifiers

Identifiers	Description
Degree code	The alphanumeric code assigned to a degree by the university (e.g. ‘MA01’). No two degrees by the university can have the same degree code.
Degree enrolment UUID	The unique identifier assigned to a degree enrolment by FutureLearn No two degree enrolments on the FutureLearn platform can have the same degree enrolment UUID
Degree UUID	The unique identifier assigned to a degree by FutureLearn No two degrees on the FutureLearn platform can have the same degree UUID
External learner ID	See ‘University ID’
Learner UUID	The unique identifier assigned to a learner by FutureLearn No two learners on the FutureLearn platform can have the same learner UUID
Organisation membership UUID	The unique identifier assigned to an organisation membership by FutureLearn No two organisation memberships on the FutureLearn platform can have the same organisation membership UUID
Program code	The alphanumeric code assigned to a program by the university (e.g. ‘MA101’) No two programs by the university can have the same program code
Program enrolment UUID	The unique identifier assigned to a program enrolment by FutureLearn No two program enrolments on the FutureLearn platform can have the same program enrolment UUID
Program run code	The alphanumeric code assigned to a program run by the university (e.g. ‘2017.02’) No two runs of the same program can have the same program run code
Program run UUID	The unique identifier assigned to a program run by FutureLearn No two program runs on the FutureLearn platform can have the same program run UUID
Program UUID	The unique identifier assigned to a program by FutureLearn No two programs on the FutureLearn platform can have the same program UUID
University ID	The unique identifier assigned to the student by the university No two students at the same university can have the same university ID In the API, the university ID is referred to as the ‘External learner ID’ as it can also refer to an employee ID or similar in other use case

 

In general, the API uses UUID to identify entities. ‘Find’ endpoints are provided to allow consumers to resolve these UUIDs from university assigned codes if necessary.

General principles

• Students won’t receive any emails from the FutureLearn platform until they’ve been introduced to FutureLearn by the university. The invitation link to sign in or register with FutureLearn is therefore sent by the university and not FutureLearn.
• As little personal information about the student as possible is transferred from the university to FutureLearn. Only the university ID is required for the flow to work. Additional information such as the first name, last name and email can be provided to pre-populate the FutureLearn registration form for students but the flow does not depend on it.
• Learners are encouraged to have a single FutureLearn account for life. They can link an existing FutureLearn account to their university ID if they wish to, or register for a new FutureLearn account with any email address of their choice.
• The university should not have to wait for the student to accept their FutureLearn invitation in order to be able to create the student’s degree and program enrolments.
• Each program enrolment is linked to at most one degree enrolment.
• The university should not be required to keep track of any FutureLearn-specific identifiers, although certain steps in the flow can be skipped if the university is able to add FutureLearn organisation membership and enrolment UUIDs to their student records.

Scenarios

The University-initiated enrolment flow is designed to cover the following scenarios. A sequence diagram for each one can be found in the sequence diagrams appendix.

 

ID	Description
S1	The university needs to enrol a student on one or more programs as part of a degree. The student does not yet have a FutureLearn account
S2	The university needs to enrol a student on one or more programs as part of a degree The student has an existing FutureLearn account but that account has yet to be linked to their university ID The student is not yet enrolled on the degree in FutureLearn
S3	The university needs to enrol a student on one or more programs as part of a degree The student has an existing FutureLearn account and that account is already linked to their university ID The student is not yet enrolled on the degree in FutureLearn
S4	The university needs to enrol a student on one or more programs as part of a degree The student has an existing FutureLearn account and that account is already linked to their university ID The student is already enrolled on the degree in FutureLearn
S5	The university needs to enrol a student on a program that the student is taking without enrolling on a degree (single program-enrolment) The student does not yet have a FutureLearn account
S6	The university needs to enrol a student on a program that the student is taking without enrolling on a degree (single program-enrolment) The student has an existing FutureLearn account but that account has yet to be linked to their university ID
S7	The university needs to enrol a student on a program that the student is taking without enrolling on a degree (single program-enrolment) The student has an existing FutureLearn account and that account is already linked to their university ID

 

API endpoints and webhooks

The FutureLearn-initiated enrolment flow utilises a number of endpoints from the FutureLearn partners API.

 

ID	Name	Purpose
EP10	Find organisation membership	Checking whether a particular university ID is already linked to a learner and obtaining the corresponding organisation membership UUID if it is
EP26	Create organisation membership invitation	Creating an organisation membership for a particular university ID
EP22	Find degree	Getting a degree UUID from a degree code
EP23	Find degree enrolment	Checking whether a student is enrolled on a degree in FutureLearn and obtaining the degree enrolment UUID if they are
EP12	Create degree enrolment	Enrolling a student on a degree in FutureLearn
EP15	Find program run	Getting a program run UUID from a program and program run code
EP16	Find program enrolment	Checking whether a student is enrolled on a program run in FutureLearn and obtaining the program enrolment UUID if they are
EP11	Create program enrolment	Enrolling a student on a program in FutureLearn
WH1	Organisation membership accepted	Notifying the university that the student has linked their university ID to a FutureLearn account
WH3	Degree enrolment activated	Notifying the university that, as a result of the associated organisation membership being accepted, a deferred degree enrolment has been activated
WH2	Program enrolment activated	Notifying the university that, as a result of the associated organisation membership being accepted, a deferred program enrolment has been activated

 

Authentication

All API methods are authenticated with a JWT bearer token. Please refer to the Partner API authentication document at the bottom of this article for further information.

Walkthroughs

In these walkthroughs, {JWT-Token} represents the bearer token for the request.

Not all of the steps illustrated are mandatory. In particular certain steps may be redundant if the university keeps track of FutureLearn organisation membership and enrolment UUIDs in its student records system.

Finding or creating an organisation membership

1. If the university does not already have an organisation membership UUID for the student in the student records system, the university can use the find organisation membership API endpoint (EP10) to search for a matching organisation membership.

 

Request Assuming ‘12345678’ is the university ID (external learner ID) GET https://api.futurelearn.com/partners/organisation_memberships/find?external_learner_id=12345678 Authorization: Bearer {JWT-token}

Response Example 1: No organisation membership exists with the specified university ID HTTP/1.1 404 Not Found Example 2: A matching organisation membership is found HTTP/1.1 302 Found Location: https://api.futurelearn.com/partners/organisation_memberships/429b0… {   "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d",   "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…" }

 

2. If no matching organisation membership is found, the university uses the create organisation membership invitation API endpoint (EP26) to instruct FutureLearn to create a new organisation membership for the student. The first name, last name and email address are all optional, but if they are provided, they’ll be used to prepopulate the registration form when the student later creates their FutureLearn account.

 

Request Assuming ‘12345678’ is the university ID (external learner ID).

Example 1 (university ID only) POST https://api.futurelearn.com/partners/organisation_membership_invitations Authorization: Bearer {JWT-token} {   "external_learner_id": "12345678" } Example 2 (with additional personal information) POST https://api.futurelearn.com/partners/organisation_membership_invitations Authorization: Bearer {JWT-token} {   "external_learner_id": "12345678",   "first_name": "Ada",   "last_name": "Lovelace",   "email": "ada.lovelace@example.com"

Response HTTP/1.1 201 Created Location: https://api.futurelearn.com/partners/organisation_membership_invitations/9324c… {   "uuid": "9324c409-ceb5-4e48-9410-36ef198c4ac0",   "href": "https://api.futurelearn.com/partners/organisation_membership_invitations/9324c…",   "external_learner_id": "12345678",   "first_name": "Ada",   "last_name": "Lovelace",   "email": "ada.lovelace@example.com",   "url": "https://futurelearn.com/invitations/sfhewryefdfsfsdkf3",   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d",     "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…" }   }

 

3. If the university has subscribed to the organisation membership accepted webhook, when the student finally links their university ID to a FutureLearn account, FutureLearn will notify the university when the organisation membership has been linked to a FutureLearn account. The university acknowledges the notification with an HTTP success response code (e.g. '202 Accepted').

 

Request Assuming https://subscriber.example.ac.uk/organisation_membership_accepted is the endpoint the university has subscribed to the organisation membership accepted webhook. POST https://subscriber.example.ac.uk/organisation_membership_accepted/ {   "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d",   "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…" }

Response HTTP/1.1 202 Accepted

 

Finding or creating a degree enrolment

1. If the university does not keep track of degree UUIDs, the university can use the find degree API endpoint (EP22) to search for a degree by degree code.

Request Assuming MA01 is the degree code. GET https://api.futurelearn.com/partners/degrees/find?degree_code=MA01 Authorization: Bearer {JWT-token}

Response Example 1: No matching degree exists HTTP/1.1 404 Not Found Example 2: A matching degree exists HTTP/1.1 302 Found Location: https://api.futurelearn.com/partners/degrees/fa6ee… {   "uuid": "fa6eee01-420d-4caf-b55a-3211488ee33b",   "href": "https://api.futurelearn.com/partners/degrees/fa6ee…" }

 

2. If the university does not already have a degree enrolment UUID for the student’s enrolment on the degree in the student records system, the university can use the find degree enrolment API endpoint (EP23) to search for a matching enrolment.

 

Request Assuming 429b0599-8d6a-4b40-8c05-84c4b25dc52d is the organisation membership UUID and fa6eee01-420d-4caf-b55a-3211488ee33b is the degree UUID. GET https://api.futurelearn.com/partners/degree_enrolments/find?organisation_membership_uuid=429b0599-8d6a-4b40-8c05-84c4b25dc52d&degree_uuid=fa6eee01-420d-4caf-b55a-3211488ee33b Authorization: Bearer {JWT-token}

Response Example 1: No matching degree enrolment exists HTTP/1.1 404 Not Found Example 2: A matching degree enrolment exists HTTP/1.1 302 Found Location: https://api.futurelearn.com/partners/degree_enrolments/07838… {   "uuid": "07838a90-de17-404f-a908-b978f66cafef",   "href": "https://api.futurelearn.com/partners/degree_enrolments/07838…"

 

3. If no matching degree enrolment is found, the university uses the create degree enrolment API endpoint (EP23) to instruct FutureLearn to create a new degree enrolment for the student. If the organisation membership is already linked to a learner (i.e. the student has linked their university ID to a FutureLearn account) the enrolment will be activated immediately. Otherwise activation of the enrolment will be deferred until the organisation membership is linked to a learner.

 

Request Assuming 429b0599-8d6a-4b40-8c05-84c4b25dc52d is the organisation membership UUID and fa6eee01-420d-4caf-b55a-3211488ee33b is the degree UUID.POST https://api.futurelearn.com/partners/degree_enrolments Authorization: Bearer {JWT-token} {   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d"   },   "degree": {     "uuid": "fa6eee01-420d-4caf-b55a-3211488ee33b"   } }

Response Example 1: The degree enrolment was activated immediately as the organisation membership is already linked to a learner HTTP/1.1 201 Created Location: https://api.futurelearn.com/partners/degree_enrolments/07838… {   "uuid": "07838a90-de17-404f-a908-b978f66cafef",   "href": "https://api.futurelearn.com/partners/degree_enrolments/07838…",   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d"     "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…"   },   "degree": {     "uuid": "fa6eee01-420d-4caf-b55a-3211488ee33b",     "href": "https://api.futurelearn.com/partners/degrees/fa6ee…"   },   "status": "active" }  Example 2: Activation of the degree enrolment has been deferred until the organisation membership is linked to a learner HTTP/1.1 201 Created Location: https://api.futurelearn.com/partners/degree_enrolments/07838… {   "uuid": "07838a90-de17-404f-a908-b978f66cafef",   "href": "https://api.futurelearn.com/partners/degree_enrolments/07838…",   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d"     "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…"  },   "degree": {     "uuid": "fa6eee01-420d-4caf-b55a-3211488ee33b",     "href": "https://api.futurelearn.com/partners/degrees/fa6ee…"   },   "status": "deferred"  }

 

4. If activation of the degree enrolment was deferred and the university has subscribed to the degree enrolment activated webhook, when the student finally links their university ID to a FutureLearn account, FutureLearn will notify the university of the activation of the degree enrolment. The university acknowledges the notification with an HTTP success response code (e.g. '202 Accepted').

 

Request Assuming https://subscriber.example.ac.uk/degree_enrolment_activated is the endpoint the university has subscribed to the degree enrolment activated webhook. POST https://subscriber.example.ac.uk/degree_enrolment_activated/ {   "uuid": "07838a90-de17-404f-a908-b978f66cafef",   "href": "https://api.futurelearn.com/partners/degree_enrolments/07838…" }

Response HTTP/1.1 202 Accepted

 

Finding or creating a program enrolment

If the university does not keep track of program run UUIDs, the university can use the find program run API endpoint (EP15) to search for a program by program and program run code.

 

Request Assuming MA101 is the program code and 2017.01 is the program run code. GET https://api.futurelearn.com/partners/program_runs/find?program_code=MA101&program_run_code=2017.01 Authorization: Bearer {JWT-token}

Response Example 1: No matching program run exists HTTP/1.1 404 Not Found  Example 2: A matching program run exists HTTP/1.1 302 Found Location: https://api.futurelearn.com/partners/program_runs/26875… {   "uuid": "26875b20-fe07-4781-bfc3-01960b849fde",   "href": "https://api.futurelearn.com/partners/program_runs/26875…" }

 

2. If the university does not already have a program enrolment UUID for the student’s enrolment on the program in the student records system, the university can use the find program enrolment API endpoint (EP16) to search for a matching enrolment.

 

Request Assuming 429b0599-8d6a-4b40-8c05-84c4b25dc52d is the organisation membership UUID and 26875b20-fe07-4781-bfc3-01960b849fde is the program run UUID. GET https://api.futurelearn.com/partners/program_enrolments/find?organisation_membership_uuid=429b0599-8d6a-4b40-8c05-84c4b25dc52d&program_run_uuid=26875b20-fe07-4781-bfc3-01960b849fde Authorization: Bearer {JWT-token}

Response Example 1: No matching program enrolment exists HTTP/1.1 404 Not Found  Example 2: A matching program enrolment exists HTTP/1.1 302 Found Location: https://api.futurelearn.com/partners/program_enrolments/85db9… {   "uuid": "85db915f-a944-4e41-8357-76f4862b3b77",   "href": "https://api.futurelearn.com/partners/program_enrolments/85db9…" }

 

3. The university uses the create program enrolment API endpoint (EP11) to instruct FutureLearn to create a new program enrolment for the student. If the organisation membership is already linked to a learner (i.e. the student has linked their university ID to a FutureLearn account) the enrolment will be activated immediately. Otherwise activation of the enrolment will be deferred until the organisation membership is linked to a learner.

 

Request Example 1: Creating a program enrolment that is linked to a degree enrolment Assuming 429b0599-8d6a-4b40-8c05-84c4b25dc52d is the organisation membership UUID, 26875b20-fe07-4781-bfc3-01960b849fde is the program run UUID, and 07838a90-de17-404f-a908-b978f66cafe is the degree enrolment UUID. POST https://api.futurelearn.com/partners/program_enrolments Authorization: Bearer {JWT-token} {   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d"   },   "program_run": {     "uuid": "26875b20-fe07-4781-bfc3-01960b849fde"   },   "degree_enrolment": {     "uuid": "07838a90-de17-404f-a908-b978f66cafef"    } } Example 2: Creating a single program enrolment Assuming 429b0599-8d6a-4b40-8c05-84c4b25dc52d is the organisation membership UUID and 26875b20-fe07-4781-bfc3-01960b849fde is the program run UUID. POST https://api.futurelearn.com/partners/program_enrolments Authorization: Bearer {JWT-token} {   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d"   },   "program_run": {     "uuid": "26875b20-fe07-4781-bfc3-01960b849fde"   } }

Response Example 1: The program enrolment was activated immediately as the organisation membership is already linked to a learner. HTTP/1.1 201 Created Location: https://api.futurelearn.com/partners/program_enrolments/85db9… {   "uuid": "85db915f-a944-4e41-8357-76f4862b3b77",   "href": "https://api.futurelearn.com/partners/program_enrolments/85db9…",   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d"     "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…"   },   "program_run": {     "uuid": "26875b20-fe07-4781-bfc3-01960b849fde",     "href": "https://api.futurelearn.com/partners/program_runs/26875…"   },   "degree_enrolment": {     "uuid": "07838a90-de17-404f-a908-b978f66cafef",     "href": "https://api.futurelearn.com/partners/degree_enrolments/07838…"    },   "status": "active" } Example 2: Activation of the program enrolment has been deferred until the organisation membership is linked to a learner. HTTP/1.1 201 Created Location: https://api.futurelearn.com/partners/program_enrolments/85db9… {   "uuid": "85db915f-a944-4e41-8357-76f4862b3b77",   "href": "https://api.futurelearn.com/partners/program_enrolments/85db9…",   "organisation_membership": {     "uuid": "429b0599-8d6a-4b40-8c05-84c4b25dc52d"     "href": "https://api.futurelearn.com/partners/organisation_memberships/429b0…"   },   "program_run": {     "uuid": "26875b20-fe07-4781-bfc3-01960b849fde",     "href": "https://api.futurelearn.com/partners/program_runs/26875…"   },   "degree_enrolment": {     "uuid": "07838a90-de17-404f-a908-b978f66cafef",     "href": "https://api.futurelearn.com/partners/degree_enrolments/07838…"    },   "status": "deferred" }

 

4. If activation of the program enrolment was deferred and the university has subscribed to the program enrolment activated webhook, when the student finally links their university ID to a FutureLearn account, FutureLearn will notify the university of the activation of the degree enrolment. The university acknowledges the notification with an HTTP success response code (e.g. '202 Accepted').

 

 

Request Assuming https://subscriber.example.ac.uk/program_enrolment_activated is the endpoint the university has subscribed to the program enrolment activated webhook. POST https://subscriber.example.ac.uk/program_enrolment_activated/ {   "uuid": "85db915f-a944-4e41-8357-76f4862b3b77",   "href": "https://api.futurelearn.com/partners/program_enrolments/85db9…" }

Response HTTP/1.1 202 Accepted

 

Inviting the student to link their university ID to a FutureLearn account

1. If a new organisation membership was created, once all of the necessary degree and program enrolments have been created, the university sends a welcome email to the student incorporating the invitation URL returned by the create organisation membership invitation API endpoint (EP26).
2. When the student clicks on this link they are taken to the FutureLearn website where they are asked to sign in or register for a new FutureLearn account. That account is then linked to their university ID and the deferred enrolments activated.

 

Document control

Rev	Date	Author	Changes
0.1	03/10/2017	AM and SF	Initial draft for internal and external feedback.
0.2	24/11/2017	SF	Use create organisation membership invitation endpoint instead of create organisation membership
1.0	01/12/2017	SF	Added find program enrolment step.
1.1	08/12/2017	SF	Remove `learner` attribute from program enrolment entity; `organisation_membership` should be used instead.