© 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.

SIMS 8 - V3 APIs - Sample Code Overview (New)

This sample code is intended for use initially on our Freemium Sandbox.  In order to access any data in SIMS 8 / DeX you will need:

Item Location
Client ID Baked in to the sample code
Secret Baked in to the sample code
Organisation ID Baked in to the sample code
Subscription Key Please obtain this from partner support

In addition, the client needs to be linked to organisation and a user needs to be created and granted permission in SIMS 8 / DeX.

Everything is ready except for the need to obtain a subscription key from Partner Support.

The credentials are limited to a particular organisation

The permission grant is read only

The subscription key is attributable to the organisation requesting the key and bound by our fair usage policy.  We reserve the right to revoke subscription keys to protect our systems, IP and/or our customers. 

Every developer will have an opinion on how to consume web APIs; this application is intended to be the lowest common denominator to show principles and strip calls down to their bare essentials in a 'Postmanesque' theme. The code is available here.


Configuration Information.

 public void SetCredentialsPostV2Upgrade()
                Folder = @"c:\temp\SIMSTestFree";

                arq = new PostitCommon.AuthRequest();
                bearerToken = null;
                arq.Scopes = "partnerserverapplication partner";
                arq.STS = "https://sts.sims.co.uk/connect/token";
                // This section needs to be replaced with values supplied by partner support
                // partner.support@capita.co.uk 
                // NB: a sand box for SIMS 8 is required in advance 
                // NB2: Charges may apply.
                arq.OCP_APIM_Key = "REQUEST YOUR OWN";
                // Each partner has their own subscription key above
                // [March 2021 Sandbox Update]
                arq.Client_ID = "sas-simsprimary-09415ca0-a803-41b1-9e25-3e5a6516ddf3";
                arq.Organisation_ID = "80ceb191-734c-4c60-aabe-70ff0e38c4e5";
                arq.Secret = "VEG5uVpf9vNQgRPT";
                // Replacement section ends
                // If you have the right values above then the code that follows should 'just work!'

                // Get a token

                bearerToken = new PostitCommon.BearerToken(arq, Program.httpClient);

In order to test the application, you will need to replace 'REQUEST YOUR OWN' with the subscription key provided by partner support.

The code uses .Net Core but could really be any language and is based on simple http calls.  

In addition we need to pass in the Client Secret and API Manager (OCP_APIMKey) Subscription Key in order to be able to be allowed access to the data APIs:

    public class AuthRequest
        public string STS { get; set; }
        public string Client_ID { get; set; }
        public string Secret { get; set; }
        public string Organisation_ID { get; set; }
        public string Scopes { get; set; }
        public string OCP_APIM_Key { get; set; }


Having collated the Authorisation request, we need to create an http client and make a post call to get an access token.

            // Get a token
            HttpClient httpClient = new HttpClient();
            PostitCommon.BearerToken bt = new PostitCommon.BearerToken(arq, httpClient);

Which under the hood looks like this:

using System.Web.Script.Serialization;
    public class BearerToken
        public string Token = "";
        public BearerToken(AuthRequest arq, HttpClient httpClient)
            string grant_type = "client_credentials";
            string client_id = arq.Client_ID; 
            string client_secret = arq.Secret;
            var form = new Dictionary<string, string>
                    {"grant_type", grant_type},
                    {"client_id", client_id},
                    {"client_secret", client_secret},
                    { "scope", arq.Scopes },
                    { "acr_values","orgselected:"+arq.Organisation_ID }

            var httpClientResponseTask = httpClient.PostAsync(arq.STS, new FormUrlEncodedContent(form));
            var result = httpClientResponseTask.Result;
            var responseStringTask = result.Content.ReadAsStringAsync();
            string responseString = responseStringTask.Result;
            var JSONObj = new JavaScriptSerializer().Deserialize<Dictionary<string, string>>(responseString);
            Token = JSONObj["access_token"];

NB: Error handling is slim to non - existent but the aim is to keep it simple.

This then returns a JWT (JSON Web Token) which is then used to make calls to the SIMS 8/Primary APIs.

The sample uses the token to  get a primary class and uses a serialize / deserialize model via NewtonSoft.Json to consume the response from the call.

            string _PrimaryClassName = "ELM";
            #region Mission #1 - Get Primary class
            AnnounceCallStart("Get LearnerGroups", CallInfo.v3APIs + "Learner/V3/LearnerGroups");
            PostitCommon.Call c1 = new PostitCommon.Call(CallInfo.v3APIs + "Learner/V3/LearnerGroups");
            string resp = c1.Execute(callInfo.bearerToken.Token, httpClient, callInfo.arq.OCP_APIM_Key);
            Guid PrimaryClassID = Guid.Empty;
            if (ErrorCheck.test(resp))
                var _Groups = Newtonsoft.Json.JsonConvert.DeserializeObject<ODataResponse<LearnerGroup>>(resp);
                AnnounceCallEnd("Get LearnerGroups", _Groups.Value.Count);
                // Now pick the class that we want from the response.
                foreach (LearnerGroup g in _Groups.Value)
                    if (g.GroupType == "PrimaryClass" && g.ShortName == _PrimaryClassName)
                        PrimaryClassID = g.ExternalID;

                if (PrimaryClassID == Guid.Empty)
                    throw new Exception("Couldn't get a Primary Class");

Further examples follow...

  • Getting pupils in the class
  • Getting attendance codes
  • getting attendance marks

Full code is provided.  The use of .Net Core and Newtonsoft.Json are subject to the owner's licensing requirements. 


Related resources for SIMS Primary / SIMS 8

SIMS 8 - APIs – V3 - Release Notes (1st Feb 2021)

Release Notes for SIMS Primary APIs V3.


SIMS 8 - APIs - Version 3

The version three APIs expand the API coverage (both read and write) previously available. Integrators should code against V3 rather than V2.


SIMS 8 - Coding Examples

Examples of how to read and write SIMS 8 data