Inviting Schools

OpenAPI definition

To streamline your onboarding process, we have created an API that allows you to programmatically invite a school to share data with your application. Schools can trigger this process themselves from within your application.

Using the API to invite schools initiates the standard onboarding process which will send an invitation email to schools allowing them to begin the authorisation flow.

Note: An example C# solution is linked at the end of this guide that should help you work through the API integration work. The solution is commented with detail about what is going on and what things mean.

Authenticate

Requests to the invitation API need to be signed with an Authorization header containing an Idaas token.

The Idaas token is generated via the Xporter STS service using your Application Management secret. Refer to the Authentication section for details on how to generate your Idaas token.

Authorization: Idaas {STSToken} 

Invite

Construct your request to the /SchoolRegister endpoint with the following details:

API Endpoint: https://xporter.groupcall.com/api/Manage/SchoolRegister HTTP Method: POST

Headers:

Content-Type: application/json
Authorization: Idaas {STSToken} 

Example POST Body: The JSON object below is an example of the object that you would POST to the API:

{
    "RegistrationType": "Test",
    "Schools": [
        {
            "LeaCode": "330",
            "DfesCode": "2005",
            "SchoolName": "1001 Primary School",
            "SchoolContactFirstName": "David",
            "SchoolContactLastName": "Smith",
            "SchoolContactEmail": "[email protected]",
            "SchoolContactPhone": "0700000000",
            "PartnerApplicationId": "dev.rebellion.com",
            "PartnerName": "Rebellion",
            "PartnerRegisteredEmail": "[email protected]"
            "ScopesToAuthorise": null,
            "AuthParams": null,
            "WeAcceptGroupcallUsagePolicy": true
        }
    ]
}

POST Object Fields

InviteSchool

Field	Type	Example	Description
RegistrationType	String	Live / Test	Set option to determine API action for development or production
Schools	Schools[]	{SequenceOf Schools}	School object defined as per example below contained in an array

Schools

Field	Type	Description	Required?
LeaCode	String	Local Authority code for the school	Mandatory
DfesCode	String	Establishment code for the school	Mandatory
SchoolName	String	Name of the school	Mandatory
SchoolContactFirstName	String	First Name of the school contact who should be expecting to be contacted	Mandatory
SchoolContactLastName	String	Last Name of the school contact who should be expecting to be contacted	Mandatory
SchoolContactEmail	String	Email address of the school contact	Mandatory
SchoolContactPhone	String	Phone number of the school contact (If this is a mobile, it can be used for self service resets)	Mandatory
PartnerApplicationId	String	PartnerId of the application the school is being invited to	Mandatory
PartnerName	String	Display name of the application	Mandatory
PartnerRegisteredEmail	String	Email address listed as Activation Email under partner settings for the application	Mandatory
WeAcceptGroupcallUsagePolicy	Boolean	Set this to true to indicate that you as a partner are confirming that the details provided are accurate and you are not misusing the API to create false registrations	Mandatory
ScopesToAuthorise	String	Provide subset of your application scopes	Optional
AuthParams	String	Provide additional options to assist your application process	Optional

RegistrationType

Value	Description
Live	Will trigger invitation process using supplied details
Test	Will simulate invitation without triggering process in Xporter

Test your intivation API integration by passing Test as the RegistrationType. No invites will be generated and no changes will be committed to Xporter platform, so it is safe to use for validating your code.

Extended Options

Field	Example	Description
ScopesToAuthorise	Students,School	Provide subset of your application scopes
AuthParams	{"InternalId":234353}	Pass arbitrary string containing information that we will pass back to you during the authorisation POST. This might be useful for identifying a school by your internal Id or specifying a location that your app can interpret and perform a specific additional action. The property accepts any string value up to 4KB in size and will return it to you URL encoded.

Example Response:

{
    [
        {
            "LeaCode": "202",
            "DfesCode": "2001",
            "Status": "OK",
            "Message": "Update"
        },
        {
            "LeaCode": "891",
            "DfesCode": "2788",
            "Status": "OK",
            "Message": "Update"
        }, 
        {
            "LeaCode": "320",
            "DfesCode": "2076",
            "Status": "OK",
            "Message": "Update"
        }
    ]
}

Understanding the Response

For a successful request you will receive a HttpCode 200 and a Schools objects containing an array of objects with the following properties:

• LeaCode: The Local Authority code for the school
• DfesCode: The establishment number of the school
• Status: Whether the request was successful
  • OK
  • Error
• Message: The action performed for the school registration
  • On OK: Update
  • On Error example: Partner Application Id does not match the header

Schools that return a status of OK will appear in your Pending Authorisation view in the Management portal and will be invited to use Xporter on Demand for your application.

Invited schools enter the standard automated on-boarding process where they will be automatically provided all of the information required to authorise your application so you can begin accessing data. You can track the progress of the invitation in the Pending Authorisation view in the Management Portal.

C# Example

Create the classes

public  class RegisterSchool  {
    public  string RegistrationType { get; set; }
    public List<School> Schools { get; set; }  
}
    
public  class School  {
    public  string LeaCode { get; set; }
    public  string DfesCode { get; set; }
    public  string SchoolName { get; set; }  
    public  string SchoolContactFirstName { get; set; }
    public  string SchoolContactLastName { get; set; }
    public  string SchoolContact { get; set; }
    public  string SchoolContactEmail { get; set; }
    public  string SchoolContactPhone { get; set; }
    public  string PartnerApplicationId { get; set; }
    public  string PartnerName { get; set; }
    public  string PartnerRegisteredEmail { get; set; }
    public  string ScopesToAuthorise { get; set; }
    public  string AuthParams { get; set; }
    public  bool WeAcceptGroupcallUsagePolicy { get; set; } 
}

Set the property values

• Note This example contains only mandatory fields

var school1 = new School() {

    LeaCode = "202", 
    DfesCode = "2001", 
    SchoolName = "Example Primary School", 
    SchoolContactFirstName = "David",
    SchoolContactLastName = "Smith",
    SchoolContactEmail = "dsmith@exampleps.sch.uk,
    SchoolContactPhone = "0700000000",
    PartnerApplicationId = "xyz.testing.com",
    PartnerName = "Xyz Testing",
    PartnerRegisteredEmail = "[email protected]",
    WeAcceptGroupcallUsagePolicy = true
};

Create the RegisterSchool object, setting the RegistrationType:

    var registerSchool = new RegisterSchool() {
        Schools = new List <School>(),
        RegistrationType = "Test"
    };

Add schools and serialise to JSON

    registerSchool.Schools.Add(school1);
    var json = JsonConvert.SerializeObject(registerSchool);

Now we have the JSON object in memory, we need to create the rest of the POST Header values including the Authorization Header.

Example C# POST

var request = (HttpWebRequest)WebRequest.Create(“https://xporter.groupcall.com/api/Manage/SchoolRegister“);
    
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("ApplicationId", "xyz.testing.com");

request.Headers.Add("Authorization", "Idaas" + STSToken);

using (StreamWriter writer = new StreamWriter(request.GetRequestStream()))
{
    writer.Write(json);
    writer.Flush();
    writer.Close();
}

using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
{
    using (StreamReader responseReader = new StreamReader(response.GetResponseStream()))
    {
    var responseString = responseReader.ReadToEnd();
        }
}

PHP Example

Example PHP POST

try {
    $response = $client->request("post", "https://xporter.groupcall.com/api/Manage/SchoolRegister", array(
        "headers" => array(
            "Content-Type" => "application/json",
            "ApplicationId" => $applicationId,
            "Authorization" => "Idaas " . $STSToken,
        ),
        "body" => $json
    ));
    echo "Response: " . $response->getBody();
} 
catch (GuzzleHttp\Exception\ClientException $e) {
}