Introduction

This article describes enhancements to the Aeries API that were developed for Escape Technology for their human resources system to sync staff data to Aeries.  These enhancements are technically available to any vendor with appropriate permissions, though great caution must be exercised when adding, updating, or deleting information using the Aeries API. Vendors must also be mindful of state reporting requirements pertaining to these data.


Main API Documentation

Please refer to the Aeries API Full Documentation for more information about the Aeries API.  Version 4 (V4) of the Aeries API has not yet been fully released. Once a complete set of V4 endpoints is ready for publication, the main API documentation will be updated. In the meantime, separate documentation is being provided to appropriate vendors as V4 endpoints are added and updated.


Error Messages

As much as possible, human-readable errors will be returned by the endpoints described below. If the HTTP status code in the response indicates an error (code 400 or above), the response body should be parsed for the detailed error message.


Errors may occur for several reasons. Attempting to retrieve a single object that does not exist will result in a 404 Not Found error. A violation of other business rules or key constraints in a POST or PUT request will result in a 400 Bad Request error. For example, attempting to create a new staff job assignment with a non-existent Staff ID will generate an error.


Error Example (JSON):


{
    "Message": "Invalid Staff ID"
}


Error Example (XML):


<Error>
    <Message>Invalid Staff ID</Message>
</Error>


Staff Information

Revision:

  • Updated to V4, added new fields, and added endpoint for HRID lookup.  New endpoints for create and update.

Security Area:

  • "Staff Data"

URL(s):

  • /api/v4/staff/{StaffID}
    • StaffID (optional) – The Aeries District Staff ID (numeric).
  • /api/v4/staff/hrid/{HRID}
    • HRID (required) - The Human Resources system ID (alphanumeric)


Query String Filters:

  • Most fields below can be passed as query string filters to limit the records returned.  
    • Example: ?primaryaeriesschool=994&fulltimepercentage=100
    • Example: ?username=JohnSmith
    • The date fields will accept “null” as a comparison; e.g., ?leavedate=null

Notes:

  • If Staff ID is not passed, all staff records in the district will be returned.


Example Staff Information Results:


[
    {
        "Gender": "F",
        "EducationLevelCode": "4",
        "EthnicityCode": "",
        "RaceCode1": "",
        "RaceCode2": "",
        "RaceCode3": "",
        "RaceCode4": "",
        "RaceCode5": "",
        "PositionStatusCode": "1",
        "TotalYearsOfEduService": 12,
        "TotalYearsInThisDistrict": 12,
        "PreviousLastName": "",
        "PreviousFirstName": "Julia",
        "PreviousMiddleName": "",
        "NameSuffix": "",
        "Address": "1234 Teacher lane",
        "AddressCity": "Eagle Rock",
        "AddressState": "CA",
        "AddressZipCode": "98765",
        "AddressZipExt": "1234",
        "HomePhone": "7779983475",
        "EmergencyContactName": "Edward Acosta",
        "EmergencyContactPhone": "7779983475",
        "ID": 994605,
        "FirstName": "Heather",
        "LastName": "Acosta",
        "MiddleName": "",
        "BirthYear": 1962,
        "BirthDate": null,
        "FullTimePercentage": 100,
        "HireDate": "2009-08-31T00:00:00",
        "LeaveDate": null,
        "InactiveStatusCode": "",
        "StateEducatorID": "",
        "UserName": "teacher",
        "EmailAddress": "nowhere@aeries.com",
        "PrimaryAeriesSchool": 994,
        "NetworkLoginID": "",
        "AlternateEmailAddress": "",
        "HumanResourcesSystemID": "fox",
        "CellPhone": "",
        "NotificationPreferenceCode": "1",
        "Title": "",
        "SchoolAccessPermissions": [
            {
                "SchoolCode": 994,
                "ReadOnlyAccess": false,
                "CommunicationGroup": true
            }
        ],
        "ExtendedProperties": []
    }
]


Field Documentation:


Name
Aeries Table.Column
Description
Address
STF.AD
The staff member's street address
AddressCity
STF.CY
The city
AddressState
STF.ST
The state abbreviation
AddressZipCode
STF.ZC
The zip code
AddressZipExt
STF.ZX
The zip code extension
AlternateEmailAddress
STF.AEM
An alternate email address.
BirthDate
STF.BD
Date of Birth
BirthYear
STF.BY
(obsolete) Year of birth
CellPhone
STF.CP
Mobile phone number
EducationLevelCode
STF.EL
The staff member's highest level of completed education
EmailAddress
UGN.EM
The staff member’s email address. (Will pull from STF.EM if UGN.EM is blank)
EmergencyContactName
STF.ECN
The name of the staff member's emergency contact
EmergencyContactPhone
STF.ETL
The phone number of the staff member's emergency contact
EthnicityCode
STF.ETH
“Y” or “N” Hispanic indicator
FirstName
STF.FN
The staff member’s first name
FullTimePercentage
STF.TP
The staff member’s full-time employment percentage
Gender
STF.SX
The staff member’s gender
HireDate
STF.HD
The staff member’s hire date
HomePhone
STF.TL
The staff member's home phone number
HumanResourcesSystemID
STF.HRID
An identifier for the staff member in an external Human Resources management system. While Aeries staff IDs are numeric, this field accepts all text characters.
ID
STF.ID
The Aeries District Staff ID
InactiveStatusCode
STF.TG
Any value other than blank indicates the staff member is inactive.
LastName
STF.LN
The staff member’s last name
LeaveDate
STF.LD
The date the staff member’s employment terminated.
MiddleName
STF.MN
The staff member’s middle name
NameSuffix
STF.SF
The staff member's name suffix
NetworkLoginID
STF.NID
The staff member’s network login ID. This may be used by the district for any purpose they choose, such as an Active Directory account.
NotificationPreferenceCode
STF.NP
The staff member’s Aeries Communications notification preference.
PositionStatusCode
STF.PS
The staff member's position status (e.g., tenured, probationary, substitute)
PreviousFirstName
STF.FNP
The staff member's previous first name
PreviousLastName
STF.LNP
The staff member's previous last name
PreviousMiddleName
STF.MNP
The staff member's previous middle name
PrimaryAeriesSchool
STF.PSC
The Aeries school code of the school where the staff member is primarily employed.
RaceCode1
STF.RC1
The staff member's first reported race
RaceCode2
STF.RC2
The staff member's second reported race
RaceCode3
STF.RC3
The staff member's third reported race
RaceCode4
STF.RC4
The staff member's fourth reported race
RaceCode5
STF.RC5
The staff member's fifth reported race
CommunicationGroup
USR.CG
Indicates whether the user should be included in school-wide communications for this school in the Aeries Communications system.
ReadOnlyAccess
USR.RO
Indicates whether this user has read-only access to the Aeries system for this school code. If True, the user is not permitted to make ANY changes to data when logged-in to this school code.
SchoolCode
USR.SC
The Aeries school code to which this user has access.
StateEducatorID
STF.SID
For certificated employees, the Statewide Educator ID issued by the state authority.
Title
STF.TI
The staff member’s title.
TotalYearsInThisDistrict
STF.TYD
The total years of service the staff member has to the current district/LEA.
TotalYearsOfEduService
STF.TYS
The total years of educational service the staff member has performed for ANY employer.
UserName
UGN.UN
The staff member’s username for the Aeries SIS.

Extended Properties:

  • CommunicationDistrictAdmin
  • AllowPostingToGeneralDistrictLevelCommunicationGroups
  • AllowPostingToGeneralSchoolLevelCommunicationGroups
  • AllowPostingToStaffSpecificDistrictLevelCommunicationGroups
  • AllowPostingToStaffSpecificSchoolLevelCommunicationGroups


Staff Information - Create


Security Area:

  • "Staff Data" - Insert

URL(s):

  • POST /api/v4/staff

Notes:

  • After a successful request, this end point returns HTTP status code 201, and the response body contains the "Staff" object that was just created.

POST Payload Object:

  • “StaffUpdate” object


“StaffUpdate” Object Definition:

Name 
Data Type 
Notes 
ID
Int32
The Aeries district staff ID. Some customers enable an option to auto-generate new staff IDs.  In this case, ID will be ignored.  Otherwise, it is REQUIRED.
FirstName
String
Max length: 20
LastName
String
Max length: 50
MiddleName
String
Max length: 20
BirthYear
Int16

BirthDate
Date

FullTimePercentage
Int16

HireDate
Date

LeaveDate
Date

InactiveStatusCode
String
Max length: 1
StateEducatorID
String
Max length: 10
EmailAddress
String
Max length: 255
PrimaryAeriesSchool
Int16

NetworkLoginID
String
Max length: 255
AlternateEmailAddress
String
Max length: 255
HumanResourcesSystemID
String
Max length: 255
CellPhone
String
Max length: 10 numbers.  If other characters are passed, only numbers will be kept.
Title
String
Max length: 100
Gender
String
Max length: 1
EducationLevelCode
String
Max length: 2
EthnicityCode
String
Max length: 1
RaceCode1
String
Max length: 3
RaceCode2
String
Max length: 3
RaceCode3
String
Max length: 3
RaceCode4
String
Max length: 3
RaceCode5
String
Max length: 3
PositionStatusCode
String
Max length: 2
TotalYearsOfEduService
Int16

TotalYearsInThisDistrict
Int16

PreviousLastName
String
Max length: 50
PreviousFirstName
String
Max length: 50
PreviousMiddleName
String
Max length: 50
NameSuffix
String
Max length: 10
Address
String
Max length: 55
AddressCity
String
Max length: 30
AddressState
String
Max length: 2
AddressZipCode
String
Max length: 5
AddressZipExt
String
Max length: 4
HomePhone
String
Max length: 10 numbers.  If other characters are passed, only numbers will be kept.
EmergencyContactName
String
Max length: 50
EmergencyContactPhone
String
Max length: 10 numbers.  If other characters are passed, only numbers will be kept.


Example POST Payload:

{
    "ID": 994902,
    "FirstName": "Somebody",
    "LastName": "Know",
    "MiddleName": "I",
    "BirthYear": 1985,
    "BirthDate": "1985-01-01",
    "FullTimePercentage": 100,
    "HireDate": "2017-07-01",
    "LeaveDate": null,
    "InactiveStatusCode": "",
    "StateEducatorID": "9949990000",
    "EmailAddress": "teacher994999@aeries.com",
    "PrimaryAeriesSchool": 994,
    "NetworkLoginID": "",
    "AlternateEmailAddress": "",
    "HumanResourcesSystemID": "994999",
    "CellPhone": "",
    "Title": "Mr.",
    "Gender": "M",
    "EducationLevelCode": "4",
    "EthnicityCode": "N",
    "RaceCode1": "700",
    "RaceCode2": "",
    "RaceCode3": "",
    "RaceCode4": "",
    "RaceCode5": "",
    "PositionStatusCode": "1",
    "TotalYearsOfEduService": 12,
    "TotalYearsInThisDistrict": 1,
    "PreviousLastName": "",
    "PreviousFirstName": "",
    "PreviousMiddleName": "",
    "NameSuffix": "",
    "Address": "123 Fake St",
    "AddressCity": "Eagle Rock",
    "AddressState": "CA",
    "AddressZipCode": "99999",
    "AddressZipExt": "1234",
    "HomePhone": "8883245363",
    "EmergencyContactName": "Aeries Software",
    "EmergencyContactPhone": "8883245363"
}


Staff Information - Update


Security Area:

  • "Staff Data" - Update

URL(s):

  • PUT /api/v4/staff/{StaffID}
    • StaffID (required) - the Aeries district Staff ID

Notes:

  • If the Staff ID does not exist, a new record will be created unless the customer has enabled the option to auto-generate new staff IDs.  In this case, an error will be generated if the given Staff ID does not already exist.
  • After a successful request, this end point returns the "Staff" object that was just updated or created. If an existing record was updated, the status code will be 200. If a new record was created, the status code will be 201.
  • If a property is omitted or null, it will be ignored. An empty string is different from a null value. An empty string will overwrite an existing value for string type properties.
    • Exception: If LeaveDate is omitted or null, it will be set to null. (It's important to be able to nullify this field, so we need to assume that the intent is to nullify if it's missing.

PUT Payload Object:

  • “StaffUpdate” object


“StaffUpdate” Object Definition:


The definition is the same that is given with the Staff Information - Create documentation, with the following exception:

  • ID is ignored in the body. The StaffID from the URL is used instead.


Example PUT Payload:

{
    "LeaveDate": "2019-01-31",
    "InactiveStatusCode": "I"
}


Staff Assignments

Revision:

  • New set of endpoints for full CRUD access to Staff Assignments.

Security Area:

  • "Staff Job Assignments"
  • "Staff Assignments (Classified)"

URL(s):

  • /api/v4/staff/{StaffID}/assignments/{AssignmentType}/{SequenceNumber}
    • StaffID (required) - the Aeries district Staff ID
    • AssignmentType (optional) - the type of assignment ("certificated" or "classified").
    • SequenceNumber (optional) - part of the primary key, along with StaffID and AssignmentType.  Uniquely identifies an assignment given a staff ID and assignment type.  If SequenceNumber is passed, then AssignmentType is required.
  • /api/v4/staff/{StaffID}/assignments/date/{year}/{month}/{day}/{AssignmentType}
    • Collection of assignments for a staff ID effective on a specific date
    • StaffID (required) - the Aeries district Staff ID
    • year, month, day (required) - the date parts for the effective date
    • AssignmentType (optional) - the type of assignment ("certificated" or "classified")

Notes:

  • Assignments for certificated and classified staff are stored in two separate Aeries tables.  For the greatest flexibility, these are separate security areas. However, they are both referred to as "assignments" in the API. There is an AssignmentType property of "certificated" or "classified" to distinguish them.  Not all fields are applicable to classified assignments.  These can be identified by the Aeries Table.Column in the field documentation.  If there is no mapping to STA, the field does not apply to classified assignments.


Example Staff Assignments Results:


[
    {
        "AssignmentType": "certificated",
        "ID": 994999,
        "SequenceNumber": 1,
        "JobClassificationCode": "12",
        "FullTimePercentage": 100,
        "NonClassroomBasedJobAssignmentCode1": "",
        "NonClassroomBasedJobAssignmentCode2": "",
        "NonClassroomBasedJobAssignmentCode3": "",
        "NonClassroomBasedJobAssignmentCode4": "",
        "NonClassroomBasedJobAssignmentCode5": "",
        "NonClassroomBasedJobAssignmentCode6": "",
        "NonClassroomBasedJobAssignmentCode7": "",
        "SchoolCode": 994,
        "StartDate": "2018-07-01T00:00:00",
        "EndDate": "2019-06-30T00:00:00"
    }
]


Field Documentation:

Name
Aeries Table.Column
Description
AssignmentType
N/A
"certificated" or "classified".  This is used to distinguish between the two distinct Aeries tables where these data are stored.
EndDate
STJ.ED, STA.ED
The end date of the assignment
FullTimePercentage
STJ.FTE, STA.PT
The full-time employment percentage attributed to this assignment
ID
STJ.ID, STA.ID
The Aeries District Staff ID
JobClassificationCode
STJ.JC, STA.JC
The job classification code for this assignment.
NonClassroomBasedJobAssignmentCode1
STJ.NC1
The first non classroom based job assignment code.  This is used for certificated, non-teaching assignments.
NonClassroomBasedJobAssignmentCode2
STJ.NC2
The second non classroom based job assignment code.  This is used for certificated, non-teaching assignments.
NonClassroomBasedJobAssignmentCode3
STJ.NC3
The third non classroom based job assignment code.  This is used for certificated, non-teaching assignments.
NonClassroomBasedJobAssignmentCode4
STJ.NC4
The fourth non classroom based job assignment code.  This is used for certificated, non-teaching assignments.
NonClassroomBasedJobAssignmentCode5
STJ.NC5
The fifth non classroom based job assignment code.  This is used for certificated, non-teaching assignments.
NonClassroomBasedJobAssignmentCode6
STJ.NC6
The sixth non classroom based job assignment code.  This is used for certificated, non-teaching assignments.
NonClassroomBasedJobAssignmentCode7
STJ.NC7
The seventh non classroom based job assignment code.  This is used for certificated, non-teaching assignments.
SchoolCode
STJ.SCL, STA.SCL
The Aeries school code associated with this assignment
SequenceNumber
STJ.SQ, STA.SQ
The Sequence Number forms part of the primary key.  It has no independent meaning.
StartDate
STJ.SD, STA.SD
The start date of the assignment.


Staff Assignments - Create


Security Area:

  • "Staff Job Assignments" - Insert
  • "Staff Assignments (Classified)" - Insert

URL(s):

  • POST /api/v4/staff/{StaffID}/assignments
    • StaffID (required) – the Aeries district Staff ID

Notes:

  • After a successful request, this end point returns HTTP status code 201, and the response body contains the "StaffJobAssignment" object that was just created.

POST Payload Object:

  • “StaffJobAssignmentUpdate” object


“StaffJobAssignmentUpdate” Object Definition:

Name
Data Type
Notes
AssignmentType
String
REQUIRED The only valid values are "certificated" and "classified".
JobClassification
String
Max length (certificated): 3. Max length (classified): 2
FullTimePercentage
Double
For CA state reporting purposes, should be rounded to the nearest tenth (e.g., 87.5).
NonClassroomBasedJobAssignment1
String
Max length: 4. Does not apply to classified assignments.
NonClassroomBasedJobAssignment2
String
Max length: 4. Does not apply to classified assignments.
NonClassroomBasedJobAssignment3
String
Max length: 4. Does not apply to classified assignments.
NonClassroomBasedJobAssignment4
String
Max length: 4. Does not apply to classified assignments.
NonClassroomBasedJobAssignment5
String
Max length: 4. Does not apply to classified assignments.
NonClassroomBasedJobAssignment6
String
Max length: 4. Does not apply to classified assignments.
NonClassroomBasedJobAssignment7
String
Max length: 4. Does not apply to classified assignments.
SchoolCode
Int16

StartDate
Date

EndDate
Date


Example POST Payload:

{
    "AssignmentType": "certificated",
    "JobClassificationCode": "12",
    "FullTimePercentage": 100,
    "NonClassroomBasedJobAssignmentCode1": "",
    "NonClassroomBasedJobAssignmentCode2": "",
    "NonClassroomBasedJobAssignmentCode3": "",
    "NonClassroomBasedJobAssignmentCode4": "",
    "NonClassroomBasedJobAssignmentCode5": "",
    "NonClassroomBasedJobAssignmentCode6": "",
    "NonClassroomBasedJobAssignmentCode7": "",
    "SchoolCode": 994,
    "StartDate": "2018-07-01",
    "EndDate": null
}



Staff Assignments - Update


Security Area:

  • "Staff Job Assignments" - Update
  • "Staff Assignments (Classified)" - Update

URL(s):

  • PUT /api/v4/staff/{StaffID}/assignments/{AssignmentType}/{SequenceNumber}
    • StaffID (required) - the Aeries district Staff ID
    • AssignmentType (required) - the type of assignment ("certificated" or "classified").
    • SequenceNumber (required) - part of the primary key, along with StaffID and AssignmentType.  Uniquely identifies an assignment given a staff ID and assignment type.

Notes:

  • If the sequence number does not exist, a new record will be created.
  • After a successful request, this end point returns the "StaffJobAssignment" object that was just updated or created. If an existing record was updated, the status code will be 200. If a new record was created, the status code will be 201.
  • If a property is omitted or null, it will be ignored. An empty string is different from a null value. An empty string will overwrite an existing value for string type properties.
    • Exception: If EndDate is omitted or null, it will be set to null. (It's important to be able to nullify this field, so we need to assume that the intent is to nullify if it's missing.


PUT Payload Object:

  • “StaffJobAssignmentUpdate” object


“StaffJobAssignmentUpdate” Object Definition:


The definition is the same that is given with the Staff Assignments - Create documentation, with the following exception:

  • AssignmentType is ignored in the body. The AssignmentType from the URL is used instead.


Example PUT Payload:

{
    "JobClassificationCode": "12",
    "FullTimePercentage": 100,
    "EndDate": null
}


Staff Assignments - Delete


Security Area:

  • "Staff Job Assignments" - Delete
  • "Staff Assignments (Classified)" - Delete

URL(s):

  • DELETE /api/v4/staff/{StaffID}/assignments/{AssignmentType}/{SequenceNumber}
    • StaffID (required) - the Aeries district Staff ID
    • AssignmentType (required) - the type of assignment ("certificated" or "classified").
    • SequenceNumber (required) - part of the primary key, along with StaffID and AssignmentType.  Uniquely identifies an assignment given a staff ID and assignment type.
  • DELETE /api/v4/staff/{StaffID}/assignments/startdate/{year}/{month}/{day}/{AssignmentType}
    • Delete all assignments for a staff ID with a Start Date on or after a specific date.  For example, delete all assignments for the current academic year (2018/07/01).
    • StaffID (required) - the Aeries district Staff ID
    • year, month, day (required) - the date parts for the start date
    • AssignmentType (optional) - limit by the type of assignment ("certificated" or "classified")

Notes:

  • After a successful request, an empty response with HTTP status code 204 will be returned.