The school API

Set up a nightly sync from Google Workspace

About ten minutes, no code to write. A small script in your own Google Workspace reads everyone in your staff OU once a night and tells JustSignup "these are our staff." People in the OU are covered by the school's plan; people who leave it, or whose Google account is suspended, are removed from the school at the next run. Nothing is emailed to anyone by the sync.

1. 1
   Make a JustSignup API key

   Sign in at justsignup.io and open School in the top nav. Open Settings at the bottom of the school page, then API access → New key. Copy the key; it starts with jsk_ and is shown once. If you lose it, revoke it there and make a new one.

2. 2
   Create the script

   Go to script.google.com signed in to your school Google account (you need Workspace admin rights that include reading users) and click New project. Click "Untitled project" at the top left and name it "JustSignup staff sync". Delete everything in Code.gs, paste the script below, and save (the disk icon).

   Code.gs, the whole fileCopy script

   // JustSignup staff sync for Google Workspace.
   // Reads one organizational unit (OU) from your directory and makes the school account match it.
   // Setup steps: https://justsignup.io/help/school-api#workspace
   // Change OU_PATH to your staff OU. The API key goes in Project Settings > Script Properties, not here.
   
   var OU_PATH = "/Staff"; // your staff OU, exactly as shown under Directory > Organizational units; sub-OUs are included
   var BASE = "https://justsignup.io/api/org/v1";
   
   function syncStaff() {
     var key = PropertiesService.getScriptProperties().getProperty("JUSTSIGNUP_API_KEY");
     if (!key) throw new Error("Add JUSTSIGNUP_API_KEY under Project Settings > Script Properties first.");
   
     var members = [];
     var pageToken;
     do {
       var page = AdminDirectory.Users.list({
         customer: "my_customer",
         query: "orgUnitPath='" + OU_PATH + "' isSuspended=false",
         maxResults: 500,
         orderBy: "email",
         pageToken: pageToken
       });
       (page.users || []).forEach(function (u) {
         if (u.archived) return; // archived accounts are no longer staff
         members.push({ email: u.primaryEmail, name: u.name && u.name.fullName ? u.name.fullName : undefined });
       });
       pageToken = page.nextPageToken;
     } while (pageToken);
   
     if (members.length === 0) {
       throw new Error("No active users found in OU " + OU_PATH + ". Check OU_PATH; nothing was changed in JustSignup.");
     }
   
     var res = UrlFetchApp.fetch(BASE + "/members/sync", {
       method: "post",
       contentType: "application/json",
       headers: { Authorization: "Bearer " + key },
       payload: JSON.stringify({ members: members, removeMissing: true }),
       muteHttpExceptions: true
     });
   
     var status = res.getResponseCode();
     var body = res.getContentText();
     if (status !== 200) throw new Error("JustSignup returned " + status + ": " + body);
     var r = JSON.parse(body);
     Logger.log("Synced " + members.length + " staff from " + OU_PATH + ": added " + r.added + ", kept " + r.kept + ", removed " + r.removed);
   }
   
   // Optional: shows who JustSignup currently has under the school. Changes nothing.
   function listStaff() {
     var key = PropertiesService.getScriptProperties().getProperty("JUSTSIGNUP_API_KEY");
     var res = UrlFetchApp.fetch(BASE + "/members", { headers: { Authorization: "Bearer " + key }, muteHttpExceptions: true });
     Logger.log(res.getContentText());
   }
   

3. 3
   Set your staff OU

   Change the one line var OU_PATH = "/Staff"; to the path of the OU your staff are in. Find it in the Google Admin console under Directory → Organizational units. The name at the very top of that page is the root of your organization and is not part of the path: an OU shown as Staff under the root is /Staff, and one nested as Employees → Teachers is /Employees/Teachers. Paths are case-sensitive and start with /. OUs inside the one you name are included.

4. 4
   Put the API key in Script Properties

   In the script editor click the gear icon, Project Settings, in the left sidebar. Under Script Properties click Add script property. Property: JUSTSIGNUP_API_KEY. Value: the jsk_… key from step 1. Click Save script properties. The script reads it from here, so the key is never in the code.

5. 5
   Turn on the Admin SDK

   Back in the editor (the <> icon), find Services in the left sidebar and click the + next to it. Choose Admin SDK API and click Add. Leave the identifier as AdminDirectory.

6. 6
   Run it once by hand

   Pick syncStaff in the function dropdown at the top and click Run. The first run asks for permission: choose your school account, click Advanced, then Go to JustSignup staff sync (unsafe), then Allow. "Unsafe" only means your own script hasn't been through Google's app review. The Execution log at the bottom should end with a line like Synced 42 staff from /Staff: added 42, kept 0, removed 0. In JustSignup, School → People now lists everyone from the OU.

7. 7
   Make it run every night

   Click the clock icon, Triggers, in the left sidebar, then Add Trigger at the bottom right. Function: syncStaff. Event source: Time-driven. Type: Day timer. Pick any hour, for example 2am to 3am. Failure notification: Notify me immediately. Save. From now on the OU is the source of truth for who is in the school account.

If something goes wrong

• No active users found in OU: OU_PATH doesn't match. Check the spelling and capitalization under Directory → Organizational units. Nothing was changed.
• JustSignup returned 401: the key is wrong or was revoked. Make a new one on the school page and update the script property.
• AdminDirectory is not defined: the Admin SDK API service wasn't added (step 5).
• Not Authorized to access this resource/api: the Google account running the script can't read the directory. Run it as a super admin, or give that account an admin role with the Users → Read privilege.
• Want to see what JustSignup has without changing anything? Run listStaff instead and read the execution log.

What a sync does, and doesn't

• It's an upsert. Everyone in the OU ends up a member. People the sync added earlier who are no longer in the OU (left, moved, suspended, archived) are removed on the next run. Adding someone who is already there changes nothing.
• It only removes people it added. People the admin invited by hand, people who joined by link, and the admin are never removed by a sync. Remove those from the school page.
• Nobody's pages are ever wiped. A removed person keeps their account and their sign-up pages, and published pages stay live. They lose the school's plan (their pages fall back to the free plan) and the school's templates.
• The OU is the only door, apart from invitations the admin sends by hand. Students, parents and alumni with school addresses can't join on their own. Keep "open the school to the whole domain" off in school settings.
• New staff get no email from the sync. They sign in at justsignup.io with their school Google account, or the one-time email link, and land under the school. Tell them in your own way.
• Several email domains are fine. The sync adds whatever addresses the OU returns, whichever of your organization's domains they are on.