search
SameGoal supports OneRoster Version 1.1 and OneRoster Version 1.2 for student/parent demographics integration. However, OneRoster lacks specific fields for certain data (e.g. addresses, phone, email, etc) for both students and parents/guardians.
We recommend student information systems (SISes) extend the metadata field of the /demographics endpoint to make such data available.
The following endpoints are also used in demographics integration, but do not require extension:
This endpoint is used to obtain demographics information for students. SIS vendors can extend the metadata field as follows:
| Field | Type | Required | Description |
| sourcedId | string | Yes | Unique identifier linking this record to a user |
| birthDate | string | Yes | Date of birth in ISO 8601 format (YYYY-MM-DD) |
| sex | string | Yes | Sex as reported |
| race | string | Yes | Race as reported |
| americanIndianOrAlaskaNative | string | Yes | Indicator for American Indian or Alaska Native identity |
| asian | string | Yes | Indicator for Asian identity |
| blackOrAfricanAmerican | string | Yes | Indicator for Black or African American identity |
| nativeHawaiianOrOtherPacificIslander | string | Yes | Indicator for Native Hawaiian or Other Pacific Islander identity |
| white | string | Yes | Indicator for White identity |
| demographicRaceTwoOrMoreRaces | string | Yes | Indicator for two or more races |
| metadata | meta | Yes | Consists of additional demographic info |
Add the following fields to the meta object of the metadata field of the /demographics endpoint. Replace vdr in the field names below with an abbreviation for your company/organization, to distinguish they added to the standard spec by your organization.
| Field | Type | Required | Description |
| vdr_address | address | Yes | The student's residential address (see address type below) |
| vdr_homePhone | string | Yes | Home phone number |
| vdr_workPhone | string | Yes | Work phone number |
| vdr_cellPhone | string | Yes | Cell phone number |
| vdr_relationships | relationship[] | Yes | List of guardians or related contacts (see relationship type below) |
| vdr_legalDistrictResidenceName | address | Yes | The legal district of residence name |
Add type address (referenced by field in meta above).
| Field | Type | Required | Description |
| number | string | Yes | Street number |
| prefix | string | Yes | Street prefix (e.g. N, SW) |
| street | string | Yes | Street name |
| tag | string | Yes | Street type suffix (e.g. Ave, Blvd, St) |
| city | string | Yes | City name |
| state | string | Yes | State abbreviation (e.g. WI) |
| zipcode | string | Yes | ZIP or postal code |
| districtResidenceName | string|null | No | Name of the district of residence, if applicable |
| county | string | Yes | County name |
| direction | string | Yes | Cardinal direction suffix (e.g. N, SE) |
| apartment | string | Yes | Apartment or unit number |
| POBox | string | Yes | PO Box identifier, if applicable |
Add type relationship (referenced by field in meta above).
| Field | Type | Required | Description |
| sourcedId | string | Yes | Unique identifier for the contact/guardian record |
| guardian | boolean | Yes | Indicates whether this contact is a legal guardian |
| relationshipType | string|null | No | The type of relationship (e.g. Mother, Father, Step-parent) |
This endpoint is used to obtain records for students and staff. Does not require extension (just provided for reference).
| Field | Type | Required | Description |
| sourcedId | string | Yes | Unique identifier for the user record |
| username | string | No | The user's login username |
| givenName | string | No | The user's given (first) name |
| firstName | string | No | Alias for given name |
| familyName | string | No | The user's last name / surname |
| middleName | string | No | The user's middle name |
| preferredFirstName1 | string | No | The user's preferred first name |
| preferredMiddleName1 | string | No | The user's preferred middle name |
| preferredLastName1 | string | No | The user's preferred last name |
| role2 | string | Yes | The user's role (e.g. student, teacher, administrator) |
| identifier | string | No | A secondary identifier (e.g. local student ID) |
| string | Yes | The user's email address | |
| orgs3 | object[] | Yes | List of organizations the user belongs to |
| grades | string[] | Yes | Grade levels associated with the user |
1 Available in OneRoster Version 1.2 only.
2 This field is role in OneRoster Version 1.1, and roles in OneRoster Version 1.2 (which is of type role).
3 This field is orgs in OneRoster Version 1.1, and primaryOrg in OneRoster Version 1.2.
This endpoint is used with OneRoster Version 1.1 to determine the district enrollment status for each student. Does not require extension (just provided for reference).
For OneRoster Version 1.2, /users roles (beginDate, endDate) fields are used instead of this endpoint.
| Field | Type | Required | Description |
| sourcedId | string | Yes | Unique identifier for the enrollment record |
| beginDate | string | Yes | Start date of the enrollment |
| endDate | string | Yes | End date of the enrollment |
| role | string | Yes | Role of the user this enrollment belongs to |
| primary | string | Yes | Enumeration (true/false); only applicable to teachers |
| status | string | Yes | Enumeration (active/inactive/tobedeleted) |
| user | user | Yes | Link to the user this record belongs to |
| school | org | Yes | Link to the school at which this class is being provided |
| class | class | Yes | The class associated with this enrollment record |
This endpoint is used to associate users with org information. Does not require extension (just provided for reference).
| Field | Type | Required | Description |
| sourcedId | string | Yes | Unique identifier for the organization record |
| status | string | Yes | Record status (e.g. active, tobedeleted) |
| name | string | Yes | Display name of the organization |
| identifier | string | Yes | A secondary identifier for the organization (e.g. local school code) |