© 2018 Capita Business Services Ltd. All rights reserved.

Capita Education Software Solutions is a trading name of Capita Business Services Ltd. Our Registered office is 30 Berners Street, London, W1T 3LR and our registered number is 02299747. Further information about Capita plc can be found in our legal statement.

DeX OData - LearnerPersonals - GET

Read is supported in DeX OData and SIMS 8 V3 APIs. 

This API is the main API for getting basic data about a learner, the data available is shown below.

There is an alternative read only information domain / API call to consider (when available) is Learner Identifiers which is intended to provide browsing facilities for Learners. This may be quicker to use in some circumstances.  

Learners contain, leavers or past students, current students and future students. The enrolment status dictates which of these apply and do consider that a learner may have been a future student, then a current student, then a leaver and then back to being a current student before leaving again. Learner Personals is not easily filtered for 'current students'.

Example Call

<Stem>/V1/LearnerPersonals?$top=30&$skip=220 (SIMS8)
https://seli00apm01.azure-api.net/dex/Learner/odata/V3/LearnerPersonals (DeX OData)

See here for Stem URLs for SIMS 8.

Sample code is available here.

API Definition

 #region Learner Personal
    public class TLearnerPersonal
    {

        /// <summary>
        /// The unique identifier for the Learner
        /// </summary>
        public Guid ExternalID;
        /// <summary>
        /// The known as forename of the learner
        /// </summary>
        public string PreferredForename;
        /// <summary>
        /// The known as or preferred surname of a learner
        /// </summary>
        public string PreferredSurname;
        /// <summary>
        /// Gender description of the learner
        /// </summary>
        public string GenderCategory;
        /// <summary>
        /// The age of the learner in months
        /// </summary>
        public Nullable<DateTime> DateOfBirth;
        public Nullable<DateTime> DateOfDeath;
        public string LegalForename;
        public string LegalMiddleNames;
        public string LegalSurname;
        public string QuickNote;
        public string Photograph;
        public Nullable<bool> BirthCertificateSeen;
        public TGenderRef Gender;
        public TTitleRef Title;
    }
    public class TResourceProviderRef : TReferenceClass { }
    public class TTitleRef : TReferenceClass { }
    public class TGenderRef : TReferenceClass { }
    #endregion Learner Personal

Example Output

{
  "@odata.context": "https://pm-svc-api-supershim-staging.azurewebsites.net/ThirdParty/Learner/OData/V1/$metadata#LearnerPersonals",
  "value": [
    {
      "ExternalID": "05abc13e-c35c-4cbf-8337-24bf76e9cb89",
      "PreferredForename": "Mike",
      "PreferredSurname": "Jackson",
      "LegalForename": "Mike",
      "LegalMiddleNames": null,
      "LegalSurname": "Jackson",
      "DateOfBirth": "2012-01-01T00:00:00Z",
      "DateOfDeath": null,
      "QuickNote": null,
      "BirthCertificateSeen": null,
      "Photograph": null,
      "Title": null,
      "Gender": {
        "ExternalID": "6b535f9b-6841-4402-9409-5beafacba485",
        "Type": "Learner.Lookup.Gender"
      }
    },
   ...

How does this differ from V2 (SIMS 8 only)?

The Call

Call Required:  https://pmapis.azure-api.net/sp-api-partner-live/V2/Learner/Learners?$expand=Personal($expand=Gender)

NB: A further expand would be needed to include 'Title' in V2 because all lookups must be explicitly included.

Differences

Photo URL is provided and can be used to obtain the photograph in V3 it was not available in V2.

The data does not have a 'Personal' sub-block in V3 but it does in V2.

External lookup locations are inclued as a Type

IsDeleted is only returned in change tracking APIs, V2 has change tracking as a function on the call whereas V3 has a separate end point.

V2 Output

{
    "value": [
        {
            "IsDeleted": false,
            "ExternalID": "2cea37cb-dbb5-4ebb-b1f9-89770752c53b",
            "Personal": {
                "IsDeleted": false,
                "ExternalID": "2cea37cb-dbb5-4ebb-b1f9-89770752c53b",
                "QuickNote": null,
                "PreferredForename": "Dawid",
                "PreferredSurname": "Machowski",
                "BirthCertificateSeen": false,
                "LegalForename": "Dawid",
                "LegalMiddleNames": null,
                "LegalSurname": "Machowski",
                "DateOfBirth": "2010-06-12T00:00:00Z",
                "DateOfDeath": null,
                "Gender": {
                    "IsDeleted": false,
                    "ExternalID": "4c8eaf6a-6cd1-45f2-9227-54b9d9ab05bc"
                }
            }
        }, ...