API

Pages

SAM Spectra API Documentation

The SAM Spectra API allows third party vendors access to view and modify data in SAM Spectra. The specific data that can be viewed and/or modified is limited to the rights given by the school district. To interact with the API, you will need a vendor key from Central Access Corporation and a customer key from the school district. Each of these keys is a unique MD5 hash.

The API is a REST-based service that can be accessed with the following URL format:

districturl/Webservices/API.svc/{EntityName}?token={CustomerToken}&vendor={VendorToken}

This API supports GET requests to view data and POST requests to insert/update data. All data received from the API will be in JSON format. All data sent to it through POST requests should be in JSON format as well. All data sent via POST requests should be in a JSON array, even if sending just one object. All fields do not have to be present in the JSON object for it to be accepted. When sending a POST request, if the data should not be updated (or is not being used for matching), the field can be omitted from the object entirely or a NULL can be sent for the value. An empty string (for string data types) or a 0 (for int data types) is not a NULL. Please reference the descriptions of each object for information about individual fields (as well as what fields are used for matching).

PageIndex and PageSize are optional parameters that can be passed in the request header. These parameters are only valid for GET requests. They allow the caller to limit the number of results returned in one API call. When limiting the result size, the results will be split over several “pages”. The PageIndex parameter allows the caller to specify which page they would like. After the pages are generated for a particular token and page size, they will not be regenerated for 30 minutes unless page index of 1 is requested again. Requesting a page index of 1 forces a regeneration of the pages. These results are saved for 30 minutes to hopefully reduce the time for API calls of indexes greater than 1 for a given page size. Valid values for PageSize are any integer greater than 0. If no value is passed (or if 0 is passed), unlimited page size is assumed. Valid values for PageIndex will vary by page size, but any integer 1 or greater is valid.

The valid values for EntityName are:

1. Students – student data – array of Student objects.

2. Contacts – parent/guardian data – array of Contact objects.

3. Employees – employee data – array of Employee objects.

4. Classes – course and roster data (GET requests only) – array of CourseSection objects.

5. TermGrades – term grade data – array of TermGradeCourse objects.

6. Assignments – assignment(daily grade) data – array of AssignmentCourse objects.

7. Schools – school data for the district (GET requests only) – array of School objects.

8. Users – SAM Spectra user data – array of User Objects.

9. Attendance – daily attendance data for students (GET requests only) – array of AttendanceRecord objects.

a. Filtering Attendance Records: Attendance records are pulled for a maximum of 7 days at a time to reduce the size of the data set. By default, the Attendance endpoint will pull records for the previous 7 days from the current date. The date range can be controlled by passing in two optional parameters via the request header: BeginDate and EndDate. Each of these parameters should have a value that is a string representation of a date (mm/dd/yyyy is preferred – most formats should work, though). Please note that EndDate can be a maximum of 7 days after BeginDate.

10. Discipline – Discipline incidents for students (GET requests only) – array of discipline incident objects

a. Filtering Discipline Records: By default, the Discipline endpoint will pull records for the previous 30 days from the current date. The date range can be controlled by passing in two optional parameters via the request header: BeginDate and EndDate. Each of these parameters should have a value that is a string representation of a date (mm/dd/yyyy is preferred – most formats should work, though).

11. StandardizedTests – Standardized tests for students (GET requests only) – array of StandardizedTest objects.

12. HistoryStudents – Historical data for students (GET requests only) – array of HistoryStudent objects.

a. Filtering HistoryStudent Records: By default, the HistoryStudent endpoint will pull records with the SessionStartDate within the previous 1 year from the current date. The date range can be controlled by passing in two optional parameters via the request header: BeginDate and EndDate. Each of these parameters should have a value that is a string representation of a date (mm/dd/yyyy is preferred – most formats should work, though). Please note that EndDate can be a maximum of 1 year after BeginDate.

13. HistoryAttendance – Historical students’ attendance (GET requests only) – array of HistoryAttendance objects.

a. Filtering HistoryAttendance Records: By default, the HistoryAttendance endpoint will pull records with the AttendanceDate within the previous 1 year from the current date. The date range can be controlled by passing in two optional parameters via the request header: BeginDate and EndDate. Each of these parameters should have a value that is a string representation of a date (mm/dd/yyyy is preferred – most formats should work, though). Please note that EndDate can be a maximum of 1 year after BeginDate.

When sending a request, an API_Result object will be returned. This object will have two arrays as properties: Data and Errors. The result will also have properties for PageIndex and PageSize. When sending a GET requests, the Data field will be populated with the requested data, and the Errors field will be populated with any errors encountered during the request. For POST requests, the Data field will not be populated. The Errors field will be populated with any errors encountered while updating or inserting the data. When sending a POST request, the data in the body of the request should be an array of one of the above listed entity types. Please see below for a full property list for each object. Remember that you can only view and/or update fields that are allowed based on your customer token. The district controls these rights. Any fields marked “used for matching” are used in conjunction with the other “used for matching” fields to determine the data being referenced. All fields are not required to match a student, but the more data provided, the easier the match will be. Also remember that any field can be left null in addition to the valid values provided. If left null, the default behavior is to not update/insert that field. Any exceptions regarding default values when inserting new data will be noted. All defaults only occur if valid data is not provided.

Student

• StudentID – integer – Internal SAM Spectra Student ID. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching. If inserting a new student, this value must be null.

• FirstName – string – Student’s first name. Used for matching. FirstName is required to insert a student.

• MiddleName – string – Student’s middle name. Used for matching.

• LastName – string – Student’s last name. Used for matching. LastName is required to insert a student.

• PreferredName – string – Student’s preferred name.

• School – school object (see later object reference) – Student’s current school. Used for matching. Required to insert a new student.

• CurrentlyEnrolled – boolean – Student’s current enrollment status.

• StateCode – string – Student’s state code (MSIS code). Used for matching.

• SSN – string – Student’s Social Security Number. Invalid if not in the format ###-##-#### or #########. Used for matching.

• DOB – string – Student’s date of birth. String value of a date. Preferred format is mm/dd/yyyy. Most date formats will work, though. DOB is required to insert a new student.

• SPEDStatus – boolean – Student’s special education status. Will default to false.

• GiftedStatus – string – Student’s gifted status. Will default to not applicable. o Valid Values (others can vary by district):

▪ Academically Gifted (or A)

▪ Creatively Gifted (or C)

▪ Intellectually Gifted (or I)

▪ Artistically Gifted (or R)

▪ Not Applicable (or NA)

• GiftedStatusDescription – string – Student’s gifted status description. Will default to not applicable.

• Status504 – boolean – Student’s 504 status. Will default to false.

• Race – string – Student’s race. Will default to White. o Valid Values:

▪ White (or W)

▪ Black (or B)

▪ Asian (or AS)

▪ Hispanic (or H)

▪ American Indian (or NA)

▪ Pacific Islander (or PI)

• Gender – string – Student’s gender. Will default to Male. o Valid Values:

▪ Male (or M)

▪ Female (or F)

• ADAGrade – string – Student’s ADA grade. Will default to the first ADA Grade in the district lookup. o Valid Values are any grade level.

• ADAGradeDescription – string – Student’s ADA grade description (long name). Will default to the first ADA Grade in the district lookup.

o Valid Values are any grade level description.

o Not required to set grade level when POSTing student data.

• ChronoGrade – string – Student’s chrono grade. Will default to the first Chrono Grade in the district lookup. o Valid Values are any Chrono Grade level (Pre-K through 12)

• ChronoGradeDescription – string – Student’s chrono grade description (long name). Will default to the first Chrono Grade in the district lookup.

o Valid Values are any Chrono Grade level description (Pre-K through 12) o Not required to set grade level when POSTing student data.

• BirthCity – string – Student’s birth city.

• BirthState – string – Student’s birth state. Should be a two-letter state code.

• BirthCounty – string – Student’s birth county.

• BirthCountry – string – Student’s birth country.

• BirthCertificateNumber – string – Student’s birth certificate number.

• BirthCertificateVerifiedBy – string – Initials of the person who verified the student’s birth certificate.

• CountryOfCitizenship – string – Student’s country of citizenship.

• Township – string – Student’s township info.

• Range – string – Student’s range info.

• Section – string – Student’s section info.

• ImmunizationDate – string – Date of student’s immunization code. Preferred format is mm/dd/yyyy. Most date formats will work, though.

• ImmunizationCode – string – Student’s immunization code. o Valid Values:

▪ Non-Compliant (or N)

▪ Compliant (or C)

▪ Exempted (or E)

▪ Temporary (or T)

▪ Provisional (or P)

• ImmunizationVerifiedBy – string – Initials of the person who verified the student’s immunization records.

• ResidingDistrict – string – Name or district code of the student’s residing district.

• TransportingDistrict – string – Name or district code of the student’s transporting district.

• TransportationCode – string – Student’s transportation code. o Valid Values:

▪ Transported pupils living in district (or A1)

▪ Living out of district-transported by this district (or A2)

▪ Living out of district-transported by another district (or A3)

▪ Non-transported pupils (or A4)

TransportationCodeDescription – string – Student’s transportation code description. This field will actually hold the full description of the transportation code. The above field will hold just the code (A1, A2, etc.); however, when making a POST request, you can put the code or description in either field.

o Valid Values:

▪ Transported pupils living in district (or A1)

▪ Living out of district-transported by this district (or A2)

▪ Living out of district-transported by another district (or A3)

▪ Non-transported pupils (or A4)

• TransportationMethod – string – Student’s transportation method.

o Valid Values:

▪ Unknown (or an empty string)

▪ Bus

▪ Car Rider

▪ Drive

▪ Walk

• TransportationMode – string – Student’s transportation mode.

o Valid Values:

▪ Non-transported (or N)

▪ Transported (or T)

• TransportationModeDescription – string – Student’s transportation mode description. This field will hold the full description of the transportation mode. The above field will hold just the code (T or N); however, when making a POST request, you can put the code or description in either field.

o Valid Values:

▪ Non-transported (or N)

▪ Transported (or T)

• AMBus – string – Student’s AM bus number. Valid values will vary by district.

• PMBus – string – Student’s PM bus number. Valid values will vary by district.

• AMBusRoute – string – Student’s AM bus route.

• PMBusRoute – string – Student’s PM bus route.

• BusStop – string – Student’s bus stop.

• HRTeacherFirstName – string – First name of the student’s homeroom teacher.

• HRTeacherMiddleName – string – Middle name of the student’s homeroom teacher.

• HRTeacherLastName – string – Last name of the student’s homeroom teacher.

• HRTeacherID – integer – Internal SAM employee ID of the student’s homeroom teacher. When updating homeroom teacher, this ID is the preferred method of employee matching; however, the above name fields can be populated and the API will attempt to match the correct employee.

• CounselorFirstName – string – First name of the student’s counselor.

• CounselorMiddleName – string – Middle name of the student’s counselor.

• CounselorLastName – string – Last name of the student’s counselor.

• CounselorID – integer – Internal SAM employee ID of the student’s counselor. When updating counselor, this ID is the preferred method of employee matching; however, the above name fields can be populated and the API will attempt to match the correct employee.

• AdvisorFirstName – string – First name of the student’s homeroom teacher.

• AdvisorMiddleName – string – Middle name of the student’s advisor.

• AdvisorLastName – string – Last name of the student’s advisor.

• AdvisorID – integer – Internal SAM employee ID of the student’s advisor. When updating advisor, this ID is the preferred method of employee matching; however, the above name fields can be populated and the API will attempt to match the correct employee.

• FoodServiceCode – string – Student’s food service code. Will default to None.

o Valid Values:

▪ None (or an empty string)

▪ Direct Certified (or D)

▪ Free (or F)

▪ Paid (or P)

▪ Reduced (or R)

• LunchNumber – string – Student’s lunch number.

• LunchBalance – decimal – Student’s current lunch balance. Valid values are any decimal number between -999.99 and 999.99 up to two decimal places.

• CareerPath – string – Student’s career path. Valid values will vary by district.

• DiplomaPathway – string – Student’s diploma pathway. Valid values vary by district, but are usually the below.

o Valid Values:

▪ Traditional (or T)

▪ Career (or C)

▪ District (or D)

• iCAP – string – Student’s iCAP. Valid values will vary by district.

• OriginalGraduationDate – string – Student’s original graduation date. String value of a date. Preferred format is mm/dd/yyyy. Most date formats will work, though.

• PII – boolean – Student’s PII (personally identifiable information) release status. Will default to false.

• CEIS – boolean – Student’s CEIS status. Will default to false.

• Immigrant – boolean – Student’s immigrant status. Will default to false.

• ImmigrantYear1 – boolean – Student’s immigrant year 1 status. Will default to false. • ImmigrantYear2 – boolean – Student’s immigrant year 2 status. Will default to false.

• ImmigrantYear3 – boolean – Student’s immigrant year 3 status. Will default to false.

• EarlyChildhoodProgramType – string – Student’s early childhood program type.

o Valid Values:

▪ Family/Friend Care (or FFC)

▪ Head Start (or HS)

▪ Home

▪ Licensed Child Care Center (or LCCC)

▪ Pre-Kindergarten (Private) (or PKPrivate)

▪ Pre-Kindergarten (Public) (or PKPublic)

• EarlyChildhoodProgramName – string – Student’s early childhood program name.

• EarlyChildhoodProgramLocation – string – Student’s early childhood program location.

• AtRiskFactors – array of AtRiskFactor objects (see later object reference) – Student’s at-risk factors.

• Addresses – array of Address objects (see later object reference) – Student’s addresses.

• PhoneNumbers – array of PhoneNumber objects (see later object reference) – Student’s phone numbers.

• EmailAddresses – array of EmailAddress objects (see later object reference) – Student’s email addresses.

• EntryExit – array of EntryExit objects (see later object reference) – Student’s entry exit codes (GET requests only).

• YearEntering9th – integer – The year that a student first entered the ninth grade or the year they are predicted to enter the ninth grade (GET requests only).

• MultiRace – boolean – Student’s MultiRace flag (GET requests only).

• CumulativeGPA – decimal – The Cumulative GPA for a student calculated after a school’s end of year process (GET requests only).

• CumulativeQPA – decimal – The Cumulative QPA for a student calculated after a school’s end of year process (GET requests only).

• TeachingType – string – The Teaching Type for a student.

o Valid Values:

▪ N/A

▪ Hybrid

▪ Traditional

▪ Virtual

Contact

• ContactID – integer – Internal SAM Spectra Contact ID. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching. If inserting a new contact, this value must be null.

• StudentID – integer – Internal SAM Spectra Student ID. This field must have the value of a valid student ID to update or insert contacts. Currently, this is the only method of student matching available for contact data.

• FirstName – string – Contact’s first name. This field will be used for matching if ContactID is null. FirstName is required when inserting a new contact.

• MiddleName – string – Contact’s middle name. This field will be used for matching if ContactID is null.

• LastName – string – Contact’s last name. This field will be used for matching if ContactID is null. LastName is required when inserting a new contact.

• Prefix – string – Contact’s name prefix.

• Suffix – string – Contact’s name suffix.

• Occupation – string – Contact’s occupation.

• PrimaryLanguage – string – Contact’s primary language

• Military – string – Contact’s military affiliation. Will default to N/A.

o Valid Values:

▪ N/A (or an empty string)

▪ Active Duty (or AD) ▪ National Guard (or NG)

• Employer – string – Contact’s employer.

• Education – string – Contact’s education.

o Valid Values:

▪ Unknown (or an empty string)

▪ No School Completed (or 01)

▪ Nursery School (or 02)

▪ Kindergarten (or 03)

▪ 1^st, 2^nd, 3^rd, or 4^th (or 04)

▪ 5^th, 6^th, 7^th, or 8^th grade (or 05)

▪ 9^th grade (or 06)

▪ 10^th grade (or 07)

▪ 11^th grade (or 08)

▪ 12^th grade, No Diploma (or 09)

▪ High School Completer (GED, Certificate) (or 10)

▪ High School Graduate (or 11)

▪ Post Graduate (or 12)

▪ Postsecondary award, certificate, or diploma (less than one year) (or 13)

▪ Postsecondary award, certificate, or diploma (more than or equal to one year) (or 14)

▪ Some College but No Degree (or 15)

▪ Some Graduate School, but No Degree (or 18)

▪ First Professional Degree (or 19)

▪ Doctoral Degree (or 20)

▪ Other (or 99)

• CheckInOut – boolean – Contact’s ability to check the student in/out. Will default to false.

EmergencyContact – boolean – Contact is an emergency contact for the student. Will default to false.

• ResidesWith – boolean – Student resides with this contact. Will default to false.

• NoContact – boolean – Contact is not allowed any contact or interaction with the student. Will default to false.

• ReceivesMail – boolean – Contact receives mail. Will default to false.

• Sequence – integer – Sequence for this contact. Starts at 1. Contacts with a sequence of 1 can be considered the primary contact for the student.

• Relationship – string – Contact’s relationship to the student. Valid values will vary by district. Will default to the first value in the district’s relationship lookup table if a valid relationship is not provided when inserting a new contact. Usually, this value is ‘Mother’ or ‘Father’.

• Addresses – Array of Address objects (see later object reference) – Contact’s addresses.

• PhoneNumbers – Array of PhoneNumber objects (see later object reference) – Contact’s phone numbers.

• EmailAddresses – Array of EmailAddress objects (see later object reference) – Contact’s email addresses.

Employee

• EmployeeID – integer – Internal SAM Spectra Employee ID. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching. If inserting a new employee, this value must be null.

• FirstName – string – Employee’s first name. This field will be used for matching if EmployeeID is null. FirstName is required when inserting a new employee.

• MiddleName – string – Employee’s middle name. This field will be used for matching if EmployeeID is null.

• LastName – string – Employee’s last name. This field will be used for matching if EmployeeID is null. LastName is required when inserting a new employee.

• PreferredFirstName – string – Employee’s preferred first name.

• PreferredLastName – string – Employee’s preferred last name.

• Prefix – string – Employee’s name prefix.

• Suffix – string – Employee’s name suffix.

• DOB – string – Employee’s date of birth. String value of a date. Preferred format is mm/dd/yyyy. Most date formats will work, though.

• EmployeeNumber – string – Employee’s employee number. This field will be used for matching if EmployeeID is null.

• SSN – string – Employee’s social security number. Invalid if not in the format ###-##-#### or #########. This field will be used for matching if EmployeeID is null.

• Gender – string – Employee’s gender. Will default to Male.

o Valid Values:

▪ Male (or M)

▪ Female (or F)

• Race – string – Employee’s race. Will default to White.

o Valid Values:

▪ White (or W)

▪ Black (or B)

▪ Asian (or AS)

▪ Hispanic (or H)

▪ American Indian (or NA)

▪ Pacific Islander (or PI)

• HireStatus – string – Employee’s hire status. Will default to Full-time.

o Valid Values:

▪ Full-time (or F)

▪ Part-time (or P)

▪ Temporary (or T)

• HireDate – string – Employee’s hire date. String value of a date. Preferred format is mm/dd/yyyy. Most date formats will work, though.

• TerminationDate – string – Employee’s termination date. String value of a date. Preferred format is mm/dd/yyyy. Most date formats will work, though. The Employees endpoint will return all employees who are currently employed or have been terminated in the last 30 days.

CurrentlyEmployed – boolean – Indicates whether the employee is currently employed. The Employees endpoint will return all employees who are currently employed or have been terminated in the last 30 days. Positions – array of EmployeePosition objects (see later object reference).

• Endorsements – array of EmployeeEndorsement objects (see later object reference).

Credentials – array of EmployeeCredential objects (see later object reference).

NationalCertDate – string – Employee’s national certificate date. String value of a date. Preferred format is mm/dd/yyyy. Most date formats will work, though.

• LicenseNumber – string – Employee’s license number.

• LicenseType – string – Employee’s license type. Will default to Regular if other valid license info is provided. o Valid Values:

▪ 40-Day Provisional (or 40Day)

▪ Initial License (or Init)

▪ Regular (or Reg)

▪ Interim/Emergency (or EMGY)

▪ Interim/Substitute (or Sub) ▪ Interim Reciprocal (or Rec)

• LicenseStatus – string – Employee’s license status. Will default to Active if other valid license info is provided. o Valid Values:

▪ Active

▪ Expired

▪ Suspended

▪ Revoked

• Addresses – Array of Address objects (see later object reference) – Employee’s addresses.

• PhoneNumbers – Array of PhoneNumber objects (see later object reference) – Employee’s phone numbers.

• EmailAddresses – Array of EmailAddress objects (see later object reference) – Employee’s email addresses.

EmployeePosition

• School – school object (see later reference) – The school at which the employee has this position. Required for inserting or updating positions. Used for matching positions (to avoid duplication).

• Department – string – The department for this position. Valid values will vary by district. Will default to the first value in the district’s department lookup table.

• PositionTitle – string – The title of the position. Valid values will vary by district. Required when inserting or updating positions. Used for matching positions (to avoid duplication).

• PositionType – string – The type of the position. Will default to Certified. o Valid Values:

▪ Certified (or C)

▪ Non-Certified (or NC)

• StartDate – string – A string representation of the employee’s start date at this position. Preferred format is mm/dd/yyyy. Most formats will work, though. Will default to today’s date.

• PrimaryPosition – Boolean – Indicates whether this position is marked as the employee’s primary position or not. There should only be one primary position per employee.

• ActivePosition – Boolean – Indicates whether this position is marked as active or not.

EmployeeCredential

• CredentialType – string – The type of the credential. Required for inserting credentials. o Valid Values:

▪ Associate of Arts Degree (or AA)

▪ Associate of Science Degree (or AS)

▪ Bachelor of Arts Degree (or BA)

▪ Bachelor of Science (or BS)

▪ Master of Arts Degree (or MA)

▪ Master of Science Degree (or MS)

• CredentialDescription – string – The description of the credential. Will default to an empty string.

• DateReceived – string – The string representation of the date that the employee received the credential. Preferred format is mm/dd/yyyy. Most formats will work, though. Will default to today’s date.

EmployeeEndorsement

• EndorsementClass – string – The endorsement class. Required to insert endorsements. o Valid Values:

▪ Undergraduate (or A)

▪ Masters (or AA)

▪ Specialist (or AAA)

▪ Doctorate (or AAAA)

• Endorsement – string – The actual endorsement. Valid values will vary by district. Required to insert endorsements.

• HighlyQualified – boolean – Indicates whether the employee is highly qualified. Will default to false.

• StartDate – string – The string representation of the start date for the endorsement. Preferred format is mm/dd/yyyy. Most formats will work, though. Required to insert endorsements.

• ExpirationDate – string – The string representation of the expiration date for the endorsement. Preferred format is mm/dd/yyyy. Most formats will work, though. Required to insert endorsements. Must be after the StartDate.

CourseSection

SectionID – integer – Internal SAM section ID.

• CourseID – integer – Internal SAM course ID.

School – school object (see later object reference) – CourseSection’s school. CourseName – string – CourseSection’s course name.

• CourseShortName – string – CourseSection’s short name.

• CourseCode – string – CourseSection’s course code.

• StateCourseCode – string – CourseSection’s state course code.

• Section – string – CourseSection’s section number.

• Period – string – CourseSection’s period.

• TeacherID – integer – Internal SAM employee ID of the CourseSection’s teacher.

• TeacherLastName – string – Last name of the CourseSection’s teacher.

• TeacherFirstName – string – First name of the CourseSection’s teacher.

• TeacherMiddleName – string – Middle name of the CourseSection’s teacher.

• CarnegieUnit – string – CourseSection’s course Carnegie unit.

• ScheduleTermID – integer – Internal ID for the course’s term. This ID is unique per schedule and term.

• StartDate – string – The start date of the CourseSection. String value of a date. Preferred format is mm/dd/yyyy. Most date formats will work, though.

• EndDate – string – The end date of the CourseSection. String value of a date. Preferred format is mm/dd/yyyy.

Most date formats will work, though.

• CourseTerm – string – CourseSection’s course term name.

• CourseType – string – CourseSection’s course type.

• Classification – string – CourseSection’s classification.

• SubjectArea – string – CourseSection’s subject area.

• LowGradeLevel – string – CourseSection’s lowest grade level taught.

• LowGradeLevelDescription – string – CourseSection’s lowest grade level taught description (long name).

• HighGradeLevel – string – CourseSection’s highest grade level taught.

• HighGradeLevelDescription – string – CourseSection’s highest grade level taught description (long name).

• Roster – array of RosterEntry objects (see later object reference) – CourseSection’s roster.

• CourseCredits – string – Indicates the number of credit hours earned of the CourseSection.

RosterEntry

• StudentID – integer – Internal SAM Spectra student ID.

• StudentFirstName – string – Student’s first name.

• StudentMiddleName – string – Student’s middle name.

• StudentLastName – string – Student’s last name.

• RosterStatus – string – Student’s roster status for the CourseSection.

• RosterActive – boolean – Indicates whether the roster status is an active or inactive status.

• RosterStatusLastChanged – string – A string representation of the date of the last update to this student’s roster status for this class.

TermGradeCourse

• SectionID – integer – The SAM Spectra Internal Section ID for this particular course section. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching. Please note that new courses and sections cannot be inserted – only grades for existing course sections.

• School – school object (see later object reference) – The course section’s school. Used for matching if SectionID is null.

• CourseName – string – The course section’s name. Used for matching if SectionID is null.

• CourseShortName – string – The course section’s short name. Used for matching if SectionID is null.

• CourseCode – string – The course section’s course code. Used for matching if SectionID is null. Will match either the local or state course code on POST requests.

• SectionNumber – string – The course section’s section number. Used for matching if SectionID is null.

• TeacherLastName – string – The course section teacher’s last name. Used for matching if SectionID is null.

• Grades – array of TermGrade objects (see later object reference) – The term grades for the course section.

• SubjectArea – string – The course’s subject area

TermGrade

StudentID – integer – The SAM Spectra Internal Student ID for this term grade. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching.

StudentStateCode – string – Student’s state code. Used for matching if StudentID is null. StudentLastName – string – Student’s last name. Used for matching if StudentID is null.

• StudentFirstName – string – Student’s first name. Used for matching if StudentID is null.

• CarnegieUnit – string – The Carnegie unit of the term grade.

• Term – string – the Term name of the term grade.

• GradeNumeric – string – A string representation of the numeric version of the term grade. When updating/inserting term grades, prefer to send numeric grades if possible. A valid grade is required in either this or the GradeAlpha field to insert Term Grades. If both GradeNumeric and GradeAlpha do not have a valid grade, ExamScore must have a valid grade or an error will be returned.

• GradeAlpha – string – The alpha version of the term grade. A valid grade is required in either this or the GradeNumeric field to insert Term Grades. If both GradeNumeric and GradeAlpha do not have a valid grade, ExamScore must have a valid grade or an error will be returned.

• ExamScore – string – The student’s term exam score for the specified term (Carnegie unit). A valid grade is required in this field to insert term exam grades. Exam scores can be a string representation of the numeric grade or letter grade. If ExamScore does not have a valid grade, either GradeNumeric or GradeAlpha must have a valid grade or an error will be returned.

• Incomplete – boolean – Indicates whether this term should be marked as incomplete for the student.

• IsFinal – boolean – Indicates whether this is the final grade for the course. This cannot be updated via a POST request. It is automatically calculated based on the Carnegie of the grade and the Carnegie of the course.

• CreditHoursAttempted – string – Indicates the number of credit hours attempted for this course. (GET requests only)

• CreditHoursEarned – string – Indicates the number of credit hours earned for this course. (GET requests only)

AssignmentCourse

SectionID – The SAM Spectra Internal Section ID for this particular course section. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching. Please note that new courses and sections cannot be inserted – only assignments and grades for existing course sections.

• School – school object (see later object reference) – The course section’s school. Used for matching if SectionID is null.

• CourseName – string – The course section’s name. Used for matching if SectionID is null.

• CourseShortName – string – The course section’s short name. Used for matching if SectionID is null.

• CourseCode – string – The course section’s course code. Used for matching if SectionID is null. Will match either the local or state course code on POST requests.

• SectionNumber – string – The course section’s section number. Used for matching if SectionID is null.

• TeacherLastName – string – The course section teacher’s last name. Used for matching if SectionID is null.

• Assignments – array of Assignment objects (see later object reference) – The assignments for the course section.

Assignment

AssignmentID – integer – The internal SAM Spectra Assignment ID for this assignment. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching. If a new assignment is being inserted, this value must be null.

ExternalAssignmentID – integer – An external assignment ID that can be stored in SAM Spectra. Designed to store an ID from a third-party piece of software (such as an LMS). Will be used for matching if the AssignmentID is null. This value is not required to insert a new assignment. If this value is not null and non-zero, it is required to be unique within the district’s database.

• AssignmentDate – string – A string representation of the assignment date. Preferred format is mm/dd/yyyy. Most formats will work, though. Used for matching if AssignmentID is null and no match is found for the ExternalAssignmentID (or no ExternalAssignmentID is given). Required to insert a new assignment.

• AssignmentType – string – The assignment type of the assignment. Valid values will vary by district. Will attempt to default to a valid value. If this fails, it will be defaulted to an invalid value that the district will have to modify.

• Title – string – The title of the assignment. Used for matching if AssignmentID is null and no match is found for the ExternalAssignmentID (or no ExternalAssignmentID is given). Required for inserting a new assignment.

• Comments – string – Teacher comments or notes about the assignment as a whole.

• AssignmentWeight – string – The weight of the assignment. Valid values are decimals greater than 0. Will default to 1.000.

• PassingScore – string – The passing score of the assignment. Valid values are decimals greater than 0. Will default to 60.

• PossiblePoints – string – The possible points for the assignment. Valid values are non-negative decimals. Will default to 100.

• BonusPoints – string – The number of bonus points allowed for the assignment. Valid values are non-negative decimals. Will default to 0.

• DoNotFactorIntoTermAverage – Boolean – Indicates whether this assignment should be factored into the calculated term average or not. If this property is set to true, the assignment will not be factored into the term average. Will default to false.

• Grades – array of AssignmentGrade objects (see later object reference) – the student grades for the assignment.

AssignmentGrade

• StudentID – integer – The SAM Spectra Internal Student ID for this assignment grade. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching.

• StudentStateCode – string – Student’s state code. Used for matching if StudentID is null.

• StudentLastName – string – Student’s last name. Used for matching if StudentID is null.

• StudentFirstName – string – Student’s first name. Used for matching if StudentID is null.

• Grade – string – The assignment grade. If numeric, must not be more than PossiblePoints + BonusPoints. If numeric and greater than PossiblePoints + BonusPoints, a grade of ERR will be inserted. The (invalid) grade passed will be placed in the assignment comments for the teacher to address and correct. If non-numeric, must be a valid Alpha Grade. This will vary by section.

• Comments – string – Teacher comments about this student’s grade.

School

SchoolID – The internal SAM Spectra School ID of the school. If a value is sent to this field, it will be the only field used for matching school. This is the preferred method of matching.

• SchoolCode – string – The school code of the school. Used for matching if SchoolID is null. Cannot be updated via API.

• SchoolName – string – The name of the school. Used for matching if SchoolID is null. Cannot be updated via API.

• SchoolTypeCode – string – The code for the type of school (83 for High School). Cannot be updated via API.

• SchoolTypeDescription – string – The type of school Cannot be updated via API.

• PrincipalID – integer – Internal SAM employee ID of the School’s principal. Cannot be updated via API.

• PrincipalLastName – string – Last name of the School’s principal. Cannot be updated via API.

• PrincipalFirstName – string – First name of the School’s principal. Cannot be updated via API.

• PrincipalMiddleName – string – Middle name of the School’s principal. Cannot be updated via API.

• Terms – array of Term objects (see later object reference) – A list of the school’s terms or grading periods.

Cannot be updated via API.

• Addresses – array of Address objects (see later object reference) – School’s addresses.

• PhoneNumbers – Array of PhoneNumber objects (see later object reference) – School’s phone numbers.

• Calendar – Array of Calendar objects (see later object reference) – School days (GET requests only).

Term

• ScheduleTermID – integer – The internal SAM Spectra ID for the term. This ID is unique per schedule and term.

• TermName – string – The user-defined term name.

• ShortCode – string – A two-character standardized name for the term based on the Carnegie Unit.

• CarnegieUnit – string – The Carnegie Unit for the term.

• BeginDate – string – A string representation of the term’s begin date.

• EndDate – string – A string representation of the term’s end date.

• ReportingOnly – boolean – A boolean indicating if the term is reporting only. A reporting only term is one that is purely calculated based on other terms (ex. S1 can be a reporting only term made up of T1 and T2 averages). Non-reporting only terms are “Gradebook Terms” or terms in which gradebook assignments can be given. In non-reporting only terms, the assignments in the term determine the term’s average.

• IsLocked – boolenan – A Boolean indicating if a term is locked from being edited.

User

UserID – integer – The internal SAM Spectra User ID for the user. If a value is sent in this field, it will be the only field used for matching. This is the preferred method of matching. If inserting a new user, this value must be null.

Username – string – The Username for the user. Usernames are unique for the district. Will be used for matching if UserID is null.

• UserDescription – string – The User Description for the user. Free text field used for any special user notes or descriptions. Can be left blank if desired.

• Enabled – boolean – Indicates whether the user is currently enabled.

• Password – string – The user’s password. This field will always be blank when exporting from SAM. This field can only be used to update a user’s SAM password. Plain text or MD5-encrypted strings can be sent in this field. Obviously, we’d prefer you send pre-encrypted passwords. If that’s not possible, we can encrypt it before updating the database entry. Remember that if you send pre-encrypted passwords, you must use the MD5 encryption algorithm.

• PasswordIsEncrypted – boolean – Value indicating whether the string sent in the Password field has already been MD5 encrypted. If this value is false, and a value is sent in the Password field, that value will be MD5 encrypted before being stored in the database. Obviously, we’d prefer you send pre-encrypted passwords. If that’s not possible, we can encrypt it before updating the database entry. Remember that if you send preencrypted passwords, you must use the MD5 encryption algorithm.

• MustChangePasswordOnNextLogin – boolean – Value indicating whether the user will be forced to change their password on their next login.

• EmployeeID – integer – ID indicating to which employee this user belongs. Should reference a value in the Employees endpoint. Will be used for matching if UserID is null.

• EmailAddress – EmailAddress object (see later object reference) – User’s email address. Users can only have one email address in SAM Spectra.

Address

AddressID – The internal SAM Spectra Address ID of the address. If a value is sent to this field, it will be the only field used for matching. If inserting a new address, this value must be null.

• AddressType – string – The type of the address. Valid values will vary by district, but usually include the below types.

o Valid Values

▪ Residence Address (or A1)

▪ Mailing Address (or A2)

▪ Business Address (or A3)

• PrimaryAddress – boolean – Indicates whether this is the primary address for the parent entity.

• Line1 – string – Address Line 1. Used for matching if AddressID is null.

• Line2 – string – Address Line 2.

• City – string – Address City. Used for matching if AddressID is null.

• State – string – Address State. Should be a two-character state code.

• ZipCode – string – Address Zip Code. Invalid if not 5 digits, 9 digits, or 10 digits including the dash.

PhoneNumber

• PhoneNumberID – integer – The internal SAM Spectra Phone Number ID of the phone number. If a value is sent to this field, it will be the only field used for matching. If posting a new phone number, this value must be null.

• PhoneType – string – The type of the phone number. Valid values will vary by district, but usually include the below types.

o Valid Values:

▪ Home

▪ Work

▪ Cellular (or Cell)

• PrimaryPhone – boolean – Indicates whether this is the primary phone number for the parent entity.

• AreaCode – string – The 3-digit area code of the phone number. Used for matching if PhoneNumberID is null.

• PhoneNumber – string – The 7-digit phone number. Must be in format ###-#### or #######. Used for matching if PhoneNumberID is null.

• AIMSequence – string – A number indicating which order the number should be called in a notification system. Blank if the number does not wish to be contacted.

• MessageFormat – string – The message type the number wishes to receive. Values include “Phone” or “Txt Msg”.

EmailAddress

EmailID – integer – The internal SAM Spectra email address ID of the email address. If a value is sent to this field, it will be the only field used for matching. If inserting a new email address, this value must be null.

PrimaryEmail – boolean – Indicates whether this is the primary email address for the parent entity. EmailAddress – string – The actual email address. Used for matching if EmailID is null.

• AIMSequence – string – A number indicating which order the email should be contacted in a notification system. Blank if the email does not wish to be contacted.

AtRiskFactor

• AtRiskCode – string – The At-Risk code for this student At-Risk Factor o Valid values can vary by district, but the following are always valid on every district

▪ LE – Limited English

▪ HMLS – Homeless

▪ MIG – Migrant

▪ FSTR – Foster Care

▪ ND – Neglected/Delinquent

• AtRiskDescription – string – The description of the At-Risk code for this student At-Risk Factor.

EntryExit

• Code – string – The enrollment code for the student.

• Description – string – The description of the above code.

• CodeDate – string – The date the code was given. Format is mm/dd/yyyy.

• IsEntryCode – boolean – Indicates whether the code is an entry or an exit code.

• SchoolCode – string – The code for the school the code is for.

• SchoolID – string – The internal SAM Spectra School ID of the school the code is for.

• SchoolName – string – The name of the school the code is for.

• ADAGrade – string – The grade that the student was when the code was given.

Calendar

• CalendarDate – string – The day a school has on the calendar. Format is mm/dd/yyyy.

o BellSchedule – string – The full schedule object including start and stop times

▪ Name – string – Bell Schedule name

▪ Period – string – period of the bell schedule

▪ BeginTime – string – string variant of the start time

▪ BeginTimeActual – date- date format of start time

▪ EndTime – string – string variant of the end time

▪ EndTimeActual – date – date format of end time

▪ InstructionalMinutes – int16 – number of minutes available for a specific schedule

• StudentDay– boolean– Indicates if the day has students attending classes.

• TeacherDay – boolean – Indicates if the day will have teachers working.

AttendanceRecord

AttendanceRecordID – integer – The internal SAM Spectra Attendance Record ID for this attendance record. StudentID – integer – The SAM Spectra Internal Student ID for this attendance record.

StudentLastName – string – Student’s last name.

StudentFirstName – string – Student’s first name.

• StudentMiddleName – string – Student’s middle name.

• School – school object (see previous object reference) – The school attached to this attendance record.

• AttendanceDate – string – String representation of the attendance record date.

• AttendanceCode – string – The attendance code given for the student for this date.

• AttendanceCodeDescription – string – The full description of the attendance code given to the student for this date.

• AttendanceStatus – string – The excused status for this attendance record. Will be either E or U.

• AttendanceStatusDescription – string – The description of the excused status for this attendance record. Will be either Excused or Unexcused.

• ReasonCode – string – The reason code for this attendance record.

• ReasonCodeDescription – string – The full description of the reason code for this attendance record.

• Comments – string – Teacher comments or notes about the attendance as a whole.

• PercentPresent – decimal – The percent of their instructional schedule for this day that the student was present.

Will be a decimal value between 0 and 100.

• LastUpdated – string – The date and time the attendance record was last updated.

Discipline

• IncidentID – integer – The internal SAM Spectra Discipline Incident ID for the discipline incident.

• IncidentDate – string – String representation of the Discipline Incident Date. Format is mm/dd/yyyy.

• IncidentType – string – The type of Discipline Incident. Can only be DISTRICT or State.

• ReportedDate – string – String representation of the date the Discipline Incident was entered. Format is mm/dd/yyyy.

• Comments – string – Notes about the incident.

• PoliceNotified – boolean – If the police were involved in the incident.

• Restraint_Mechanical – boolean – If mechanical restraint was used during the incident event.

• Restraint_Physical – boolean – If physical restraint was used during the incident event.

• School – school object (see earlier object reference) – The school where the incident happened.

• Location – string– Where the incident happened.

• OtherLocation – string – Extra location data.

• DisciplineEntities– array of DisciplineEntity objects (see later object reference) – Entities that were a part of this Discipline Incident.

DisciplineEntity

IncidentID – integer The internal SAM Spectra Discipline Incident ID for the discipline incident.

RoleType – string – The role of the entity in the incident. Possible role types include Instigator, Reporter, Participant.

EntityIncidentID – integer – The internal SAM Spectra Discipline Incident ID for the Discipline Entity.

• Comments – string – Notes about the entity.

• Infraction – string – The infraction the entity committed for this discipline incident.

• IsStateCode – boolean – Indicates whether the infraction code is reported to the state or not.

• InfractionCode – string – The infraction code.

• WeaponType – string – The weapon used in this discipline incident if applicable.

• DisciplineEntityType – string – The type of entity. Values are Student, Employee, and Other.

• EntityID – integer – The internal SAM Spectra ID number for the entity. Can link to employees or students based on the DisciplineEntityType. There is no link for Other.

• FirstName – string – The entities first name.

• MiddleName – string – The entities middle name.

• LastName – string – The entities last name.

• DisciplineActions – array of DisciplineActions objects (see later object reference) – Actions taken for these entities.

DisciplineAction

• ActionID – integer – The internal SAM Spectra Discipline Action ID for this action.

• EntityIncidentID – integer– The internal SAM Spectra Entity ID for this action.

• BeginDate – string – String representation of the date this action begins. Format is mm/dd/yyyy.

• EndDate – string – String representation of the date this action ends. Format is mm/dd/yyyy.

• AdministratorID – integer – The internal SAM Spectra EmployeeID that administered this action for this entity.

• AdministratorFirstName – string – The first name of the employee that administered this action.

• AdministratorMiddleName – string – The middle name of the employee that administered this action.

• AdministratorLastName – string – The last name of the employee that administered this action.

• WasParentNotified – boolean – Indicates if the parents were told about this action for this entity.

• Comments – string – Notes about this action.

• ActionCode – string – The code for this action.

• IsStateCode – boolean – Indicates whether the infraction code is reported to the state or not. • Description – string – The action code description

Standardized Tests

StandardizedTestID integer – The internal SAM Spectra Test ID for this test.

CompositeScore – string – The composite score for this test.

StudentID – integer – The internal SAM Spectra Student ID for this test. FirstName – string– The student’s first name.

• MiddleName – string– The student’s middle name.

• LastName – string– The student’s last name.

• GradeLevel – string – The students grade level when the test was taken.

• TestID – integer – The internal SAM Spectra Test Template ID for this type of test.

• TestName – string – The SAM Spectra Test Template Name for this type of test.

• MaxCompositeScore – string – The maximum values a composite score can be.

• PassingCompositeScore – string – The minimum value a composite score can be for the student to be considered passing.

• PassFail – string – The “Pass” or “Fail” value calculated by SAM. This can also be a blank string if the score is not numeric, or there is no PassingCompositeScore.

• TestYear – string – The year this test was taken.

• TestYearAdd – string – Additional information about when this test was taken.

• Scale – array of scale objects (see later object reference) – Additional scale scores for this test.

Scale

• StandardizedTestScaleID – integer – The internal SAM Spectra Scale ID for this test.

• ScaleScore – string – The score achieved for this scale.

• ScaleID – integer – The internal SAM Spectra Scale Template ID for this type of scale and test.

• ScaleName – string – The name of this scale.

• ScaleMaxScore – string – The maximum value the ScaleScore can be.

• ScaleProficiencyLevel – string – The proficiency level of the strand.

• Strand – array of strand objects (see later object reference) – Additional strand scores for this scale

Strand

• StandardizedTestStrandID – integer – The internal SAM Spectra Strand ID for this test.

• StrandScore – string – The score achieved for this strand.

• StrandID – integer – The internal SAM Spectra Strand Template ID for this type of strand, scale, and test.

• StrandName – string – The name of this strand.

• StrandMaxScore – string – The maximum value the StrandScore can be.

HistoryStudent

SessionID – integer The internal SAM Spectra Student Session ID for this historical student session.

SessionStartDate– string – String representation of the date this session begins. Format is mm/dd/yyyy. SessionEndDate – string – String representation of the date this session begins. Format is mm/dd/yyyy. SessionName – string – Student Session’s name.

• InstitutionName – string – Student Session’s institution name. (This can be different from the school object below).

• StudentID – integer – The internal SAM Spectra student ID.

• StudentFirstName – string – Student’s first name.

• StudentMiddleName – string – Student’s middle name.

• StudentLastName – string – Student’s last name.

• GradeLevel – string – The grade level of the stundent at the end of this session.

• School – school object (see earlier object reference) – The school where the session took place. If the SchoolID is 0, then the school has been deleted or was a custom historical session.

• Courses – array of HistoryCourse objects (see later object reference) – The student’s courses taken during this session.

HistoryCourse

• CourseID – integer – The internal SAM Spectra History Course ID for this historical student course.

• CourseName – string – HistoryCourse’s course name.

• CourseShortName – string – HistoryCourse’s short name.

• CourseCode – string – HistoryCourse’s course code.

• StateCourseCode – string – HistoryCourse’s state course code.

• CourseType – string – HistoryCourse’s course type.

• Classification – string – HistoryCourse’s classification.

• SubjectArea – string – HistoryCourse’s subject area.

• CourseCredits – string – Indicates the number of credit hours earned for this historical course.

• Grades – array of HistoryGrade objects (see later object reference) – The historical grades associated with this historical course.

HistoryGrade

Grades – integer – The internal SAM Spectra HistoryGrade ID for this historical student course grade.

ReportingCode – string – The reporting code description of this historical grade.

GradeNumeric – string – A string representation of the numeric version of the historical grade. GradeAlpha – string – The alpha version of the historical grade.

• Incomplete – boolean – Indicates whether this historical grade should be marked as incomplete for the historical student course.

• IsFinal – boolean – Indicates whether this is the final grade for the historical course.

• CreditHoursAttempted – string – Indicates the number of credit hours attempted for this historical course.

• CreditHoursEarned – string – Indicates the number of credit hours earned for this historical course.

HistoryAttendanceRecord

• HistoryAttendanceRecordID – integer – The internal SAM Spectra History Attendance Record ID for this attendance record.

• SessionID – integer – The internal SAM Spectra Student Session ID for this historical student session.

• AttendanceRecordID – integer – The internal SAM Spectra Attendance Record ID for this attendance record. This is only unique to each school year.

• StudentID – integer – The SAM Spectra Internal Student ID for this attendance record.