Sign In

The SameGoal generic API allows districts to setup an SFTP-based CSV file upload integration or bulk upload demographics as needed.

API CSV Files link

We recommend you include all currently enrolled students in the integration, rather than only students in a particular program. This allows staff to easily start new documentation for students as they are initially referred into programs.

The guardians.csv file below is not required. However, forms throughout the program are prefilled with student and parent/guardian demographics whenever possible. Including guardians.csv saves staff time.

students.csv link

[download spec]

  • 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. 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.
    • 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 IRN. School building IRN.

guardians.csv link

[download spec]

  • 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 no row(s) 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.

user_groups.csv link

[download spec]

  • Complete one row for each user group form permission. For example, for a user group that assigns permissions for four (4) forms, this file should contain 4 rows, one for each form permission.
  • Fields - unless otherwise specified, all fields are optional, may contain letters, numbers and symbols, and are of unlimited length.
    • Group Name [required, key]. Name of user group.
    • 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".
    • Buildings [required]. Comma separated list of buildings this user group form permission should apply to. Building name must exactly match a building listed in your administrative account, which can be found by visiting Settings > Buildings.

users.csv link

[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.
    • Username [required, key]. User username. If your organization uses LDAP/Active Directory, this username should be the LDAP username.
    • Password. User password. If your organization uses LDAP/Active Directory, leave this blank (user will use LDAP password when logging in, which is not stored in the SameGoal database). If your organization is not using LDAP and password is left blank, user will be unable to login until a password is stored.
    • User Groups. Comma separated list of user group(s) user belongs to.

CSV File Generation Requirements link

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.

Technical Details link

  • 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.


.
.
.