This generic CSV API allows districts to import data into SameGoal through SFTP-based CSV file upload integrations. These file layouts are also used for bulk data load as needed.
[download spec]
lightbulb Tip
We recommend you include all currently enrolled students in the integration. This allows staff to start evaluation documentation immediately for students when they are initially referred.
- Complete one row for each student you wish to be added.
- Fields - unless otherwise specified, all fields are optional, may contain letters, numbers and symbols, and are of unlimited length.
- Student Id [required, key]. Student Id number from your student information system (eg: 555555). This field can contain letters and numbers, but is limited to 20 characters. Each Student Id number must be unique to your district.
- Last Name [required]. Student last name.
- Middle Name. Student middle name.
- First Name [required]. Student first name.
- Date of Birth [required]. Student date of birth. Must be in one of the following formats: MM/DD/YYYY, MM-DD-YYYY, YYYY/MM/DD, YYYY-MM-DD
- Gender [required]. Must be one of the following values: M, F, m, f, male, female, Male, Female.
- District Enrollment [required]. Student enrollment status. Must be one of the following values: PRE_ENROLLED, ENROLLED, TRANSFERRED, WITHDREW, DROPPED_OUT, GRADUATED, INACTIVE, HISTORICAL_IDLE.
- Grade. Student grade.
- Address. Student address.
- City. Student city.
- State. Student state.
- Zip. Student zip.
- Race. Student race.
- District of Residence. Student district of residence.
- County of Residence. Student county of residence.
- District of Service. Student district of service.
- Student Reporting Id. Student Id used in state reporting.
- Building. School name, such as Forest Middle School.
- Building Reporting Id. School building Id used in state reporting.
- SIS Internal ID. Student information system internal identifier, if applicable.
- Student State Assigned Id. Student state assigned ID number. (Note: Texas only)
- Student SSN. Student social security number. Only populate when Student State Assigned Id is not available and SSN may be needed for integration with a third-party system (eg Medicaid billing vendor). (Note: Texas only)
- Preferred Language. Language1 family prefers to receive communications from school in.
- HLS Student Language. Language1 used most by child at home, as indicated on home language survey.
- HLS Home Language. Language1 used most within child's home, as indicated on home language survey.
- HLS Prior Home Language. If child had a previous home setting, language1 used most often in this setting, as indicated on home language survey.
1 2-character ISO 639 language code (eg for Spanish, use "es")
[download spec]
lightbulb Tip
guardians.csv is not required. However, forms throughout the program are prefilled with student and parent/guardian demographics whenever possible. Including guardians.csv saves staff time.
- Complete one row for each parent/guardian you wish to be added. If no parent/guardian information exists for a given student, this file may contain zero rows for this student.
- Fields - unless otherwise specified, all fields are optional, may contain letters, numbers and symbols, and are of unlimited length.
- Student Id [required, key]. Student Id number from your student information system (eg: 555555) that corresponds to child of this parent/guardian.
- Last Name [required]. Parent/guardian last name.
- First Name [required]. Parent/guardian first name.
- Type [required]. Parent/guardian type. This field must be 1 or M for the Mother, 2 or F for the Father, or 3 or G for the Guardian.
- Address. Parent/guardian address.
- City. Parent/guardian city.
- State. Parent/guardian state.
- Zip. Parent/guardian zip.
- Home Phone. Parent/guardian home phone.
- Work Phone. Parent/guardian work phone.
- Cell Phone. Parent/guardian cell phone.
- Email. Parent/guardian email.
[download spec]
- Complete one row for each user you wish to be added.
- Fields - unless otherwise specified, all fields are optional, may contain letters, numbers and symbols, and are of unlimited length.
- Last Name [required]. User last name.
- First Name [required]. User first name.
- Email [required, key]. User email. Most commonly district supplied.
- LDAP Username. User LDAP/Active Directory username. Required when:
- LDAP/Active Directory is enabled for the environment, and
- The user is in LDAP, and
- The LDAP username is different than the user's email username (eg LDAP username is "bobsmith", and email username is "bsmith")
- Force Local Authentication. Required when:
- LDAP/Active Directory is enabled for the environment, and
- The user is not in LDAP and/or should be authenticated without querying the LDAP/Active Directory server (eg instead use a password stored in SameGoal).
- If specified, must be one of the following values: "Yes", "Y", "yes", "y", "X", "x", "1", "No", "no", "N", "n", "0".
- Roles. Exact name of role to assign user to. If adding User Roles for the first time, this should match the Role Names found in the user_roles.csv.
- Administrative users must have the role "Admin" and no buildings assoicated with the role as Admin users have access to all buildings.
- Users not assigned a user role will have a default permission of None for all forms and a max permission of Owner for all forms in all buildings available in the district.
- Buildings. Comma separated list of buildings this user should have for the specified user role. Building name must exactly match a building listed in your administrative account, which can be found by visiting Settings > Buildings.
- Deleted. Required only when removing accounts currently in the system.
- If specified, must be one of the following values: "Yes", "Y", "yes", "y", "X", "x", "1", "No", "no", "N", "n", "0".
lightbulb Tip
If a user has multiple roles, separate them by semicolon and separate the buildings that are associated with the role respectively by semicolon. Roles with multiple buildings should be comma separated. An example for a user who is a Special Education Teacher at North Elementary, a Related Service Provider at North Elementary, South Elementary, East Elementary, and West Elementary, and Literacy Teacher at South Elementary would have the below for Role and Buildings:
- Roles = Special Education Teacher; Related Service Provider; Literacy Teacher
- Buildings = North Elementary; North Elementary, South Elementary,East Elementary,West Elementary; South Elementary
[download spec]
- Complete one row for each user role form permission. For example, for a user role that assigns permissions for four (4) forms, this file should contain 4 rows, one for each form permission.
- Fields - all fields may contain letters, numbers and symbols, and are of unlimited length.
- Role [required, key]. Name of user role.
- Form [required]. Exact name of form to assign permissions to. This can be found by visiting a document using this form in the program.
- Default Permission [required]. The default permission users in this user group should have for this form. Valid options include "none", "view", "edit", "owner".
- Max Permission [required]. The maximum permission users in this user group should have for this form. Valid options include "none", "view", "edit", "owner".
See the IETF CSV spec, particularly section "2. Definition of the CSV Format" for tips on generating valid CSV files. In short:
- All fields may be OPTIONALLY enclosed in double quotes.
- All fields MUST be enclosed in double quotes if they contain a special character (comma, newline, or double quote).
- Double quote characters that are part of the value of a field must be escaped by adding another double quote character immediately before the double quote. For example, the value will take place at "The Wildcats" computer room is escaped to will take place at ""The Wildcats"" computer room.
- A good sanity check on the format of your files is to open them in Excel and ensure the columns line up as you intend. If Excel can read it, we should be able to read it.
- Note that some fields may contain non-printable characters (depending on your data source). This is likely undesired and we recommend removing values outside the ASCII "printable characters" range. This is not strictly necessary, but it is strongly encouraged as it can help to keep the data imported clean and looking as intended.
- SFTP-based CSV file upload is safe to run multiple times. In the event that you upload the same files multiple times, all successive runs will have no effect.
- You may upload CSV files as many times per day as you like. All uploads are processed in chronological order.
- If you have a "bad" upload that you do not want processed, simply connect to your SFTP account and delete the epoch directory.
- If no upload occurs for a given day(s), nothing bad happens. All information will be left in the system and no update will be performed.
- After each epoch directory is processed, it is moved to /upload-processed/ for approximately 30 days. Data is retained for debugging purposes but can be garbage collected at any time.
- Leading and trailing whitespace is removed from all fields.
- Add/update policy:
- If the key for a given row IS NOT in the database, the information in the row will be added.
- If the key for a given row IS in the database, the information in the database for the row will be updated.
- If a key is in the database, but not in the integration file, that information is not removed from the database. No information can be deleted from the database via integration. This minimizes the risk of accidental deletion of information.
- Integrations are "transactional". Either all rows or no rows are processed.