Aptem Webhooks: ILR type

Overview

This webhook sends notifications whenever a learner’s ILR episode is created or updated. It can be used to keep external systems in sync with ILR data in real time.

The payload of an ILR webhook is identical to the payload returned by the GetILR API response:

• familyName

• givenNames

• dateOfBirth

• postcode

• addLine1

• addLine2

• addLine3

• addLine4

• telNo

• email

• sex

• userId

• hesaSex

• hesaEthnicity

• hesaDisabilities

• learnRefNumber

• uln

• ethnicity

• niNumber

• priorAttain

• planLearnHours

• planEEPHours

• mathGrade

• engGrade

• employmentStatus

• employerId

• employmentStartDate

• jobTitle

• contractedHours

• postConsent

• emailConsent

• phoneConsent

• llddAndHealthProblems

• primaryLLDD

• emergencyContactName

• emergencyContactRelationship

• emergencyContactPhone

• emergencyContactEmail

• ukEeaCitizen

• ukEeaResident3Yrs

• ukResidentYrs

• ukWorkPermitRequired

• idEvidence

• countryOfBirth

• countryResidence

• nationality

• standardCode

• totalPrice

• postcodePrior

• epaCode

• totalTrainingPrice

• totalAssessmentPrice

• AND event (“update” or “create”)

Create event

For the CREATE event type, the webhook is sent once a new ILR episode is created for a learner in the tenant.

Note, that each enrollment on a delivery programme, where ILR token is enabled, results into a new ILR episode created for a Learner (excluding re-enrollment case). That said, a Create ILR webhook may be sent for a learner who has already received one, if they are later enrolled onto another delivery programme with the ILR token enabled.

Note: If you enable the ILR token at a programme for the first time, and there are Learners who are already enrolled onto that programme, a Create ILR webhook will be created for these Learners right after a programme change confirmed.

Payload

The payload for Create event type includes “event”:”create” field.

{
  "familyName": "Croyle-Bach",
  "givenNames": "Edmund",
  "dateOfBirth": "2007-06-14",
  "postcode": "IM4 7AR",
  "addLine1": "25 Glen Rd",
  "addLine2": null,
  "addLine3": "Laxey",
  "addLine4": null,
  "telNo": "1234567825",
  "email": "testemail4+r1+loc@email.com",
  "sex": "F - Female",
  "userId": 8,
  "hesaSex": "2",
  "hesaEthnicity": "19",
  "hesaDisabilities": "56",
  "learnRefNumber": "MWS843FEO784",
  "uln": "9999999000",
  "ethnicity": "34",
  "niNumber": "AB123321C",
  "priorAttain": "12",
  "planLearnHours": 0,
  "planEEPHours": 0,
  "mathGrade": "A",
  "engGrade": "A",
  "employmentStatus": "10",
  "employerId": 554466335,
  "employmentStartDate": "2025-04-01",
  "jobTitle": null,
  "contractedHours": 40,
  "postConsent": 0,
  "emailConsent": 0,
  "phoneConsent": 0,
  "llddAndHealthProblems": [
    93
  ],
  "primaryLLDD": 93,
  "emergencyContactName": null,
  "emergencyContactRelationship": null,
  "emergencyContactPhone": null,
  "emergencyContactEmail": null,
  "ukEeaCitizen": true,
  "ukEeaResident3Yrs": false,
  "ukResidentYrs": null,
  "ukWorkPermitRequired": null,
  "idEvidence": "test",
  "countryOfBirth": null,
  "countryResidence": null,
  "nationality": "170",
  "standardCode": 6,
  "totalPrice": 0,
  "postcodePrior": "LD1 5AF",
  "epaCode": "EPA0007",
  "totalTrainingPrice": null,
  "totalAssessmentPrice": null,
  "event": "create"
}

Update event

For the UPDATE event type, the Webhook is sent when any field of learner’s ILR episode is updated. This includes: 

• Any changes to ILR fields including updates from the Onboarding Wizard ILR step.

• Re-saving the learner’s ILR even with no changes introduced.

• Updating or re-saving the learner’s current programme where ILR token is enabled.

The Update ILR webhook will also be triggered in case ILR is changed via updates from other places in the system, including:

• ILR episode status is updated (signed, pending, etc.)

• EDRS number is set or updated for Learner's Employer Organisation

• ILR is updated via process automation trackers (aims added or updated, employment status record(s), learner address)

Note that if an ILR episode linked to the learner’s previous programme is updated or re-saved by the administrator (from the ILR page), this will trigger an update ILR webhook for the learner as well.

Payload

The payload for Update event type includes “event”:”update” field.

{
  "familyName": "Croyle-Bach",
  "givenNames": "Edmund",
  "dateOfBirth": "2007-06-14",
  "postcode": "IM4 7AR",
  "addLine1": "25 Glen Rd",
  "addLine2": null,
  "addLine3": "Laxey",
  "addLine4": null,
  "telNo": "1234567825",
  "email": "testemail4+r1+loc@email.com",
  "sex": "F - Female",
  "userId": 8,
  "hesaSex": "2",
  "hesaEthnicity": "19",
  "hesaDisabilities": "56",
  "learnRefNumber": "MWS843FEO784",
  "uln": "9999999000",
  "ethnicity": "34",
  "niNumber": "AB123321C",
  "priorAttain": "12",
  "planLearnHours": 0,
  "planEEPHours": 0,
  "mathGrade": "A",
  "engGrade": "A",
  "employmentStatus": "10",
  "employerId": 554466377,
  "employmentStartDate": "2026-03-15",
  "jobTitle": null,
  "contractedHours": 35,
  "postConsent": 0,
  "emailConsent": 0,
  "phoneConsent": 0,
  "llddAndHealthProblems": [
    93
  ],
  "primaryLLDD": 93,
  "emergencyContactName": null,
  "emergencyContactRelationship": null,
  "emergencyContactPhone": null,
  "emergencyContactEmail": null,
  "ukEeaCitizen": true,
  "ukEeaResident3Yrs": false,
  "ukResidentYrs": null,
  "ukWorkPermitRequired": null,
  "idEvidence": "test",
  "countryOfBirth": null,
  "countryResidence": null,
  "nationality": "170",
  "standardCode": 6,
  "totalPrice": 0,
  "postcodePrior": "LD1 5AF",
  "epaCode": "EPA0007",
  "totalTrainingPrice": null,
  "totalAssessmentPrice": null,
  "event": "update"
}

Delete event

For DELETE event type, the Webhook is not supported.