OneRoster CSV Integration over SFTP

How to deliver OneRoster v1.1 CSV rostering files to Lingco via SFTP

Overview

Lingco can roster your students, teachers, classes, courses, and enrollments from a nightly OneRoster v1.1 CSV export delivered over SFTP. Your SIS (PowerSchool, Infinite Campus, Skyward, ClassLink, Clever, etc.) generates the file set, and Lingco picks it up on a schedule and syncs it into your Lingco organization.

Important: Lingco supports full (bulk) exports only. Delta files are not currently supported. Every upload must contain the complete, current picture of your data. If delta-only export is a hard requirement for your district, let us know and we'll discuss options.

SFTP Connection Details

Lingco provisions a dedicated SFTP account for your district. Your connection details:

Setting	Value
Host	sftp-oneroster.lingco.io
Port	22
Protocol	SFTP (SSH File Transfer Protocol)
Username	`________________________________`
Password	`________________________________`
Upload directory	/

Notes on connecting

Only SFTP is supported. Plain FTP and FTPS are not accepted.
If your district firewalls outbound traffic, allow outbound TCP on port 22 to the host above.
Your account is chrooted to your own directory — you will not see or be able to reach other districts' files.
Please store these credentials in your district's password manager. If they're ever exposed, contact Lingco support and we'll rotate them.

Uploading

Connect with any standard SFTP client (WinSCP, FileZilla, Cyberduck, sftp/scp on the command line) or your SIS's built-in scheduled export/delivery feature.
Upload a single .zip archive containing the CSV files (see below).
Upload to a temporary name and rename into place, or use your client's atomic upload option, so Lingco never picks up a partially written file.
Lingco processes the most recent archive on each scheduled run and archives the previous one.

Recommended schedule: nightly, outside of school hours (for example between 1:00 AM and 4:00 AM local time). Weekly is acceptable for districts whose rosters change infrequently. Confirm your intended schedule with Lingco during setup so our pickup window lines up with your export window.

What Lingco Does With the Data

Entity	How it's used	Fields read
Organization	Builds the district/school hierarchy so users only see data within their own organizations	`name`, `identifier`, `type`, `sourcedId`, parent, children, `status`
Course	Links to Lingco classes; codes and titles drive display in reports and content mapping	`title`, `courseCode`, `sourcedId`, `schoolYear`, `grades`, `subjects`, org, `subjectCodes`
Class	The core unit assignments and assessments bind to	`sourcedId`, `title`, `classCode`, `classType`, `location`, `grades`, `subjects`, course, school, terms, `periods`
User	Creates Lingco student and teacher accounts with the right roles and org assignments	`username`, `sourcedId`, `givenName`, `familyName`, `middleName`, `email`, `role`, orgs, `grades`
Enrollment	Links users to classes with role and enrollment period	`sourcedId`, user, class, school, `role`, `primary`, `beginDate`, `endDate`
Academic Session	Organizes classes temporally into terms and grading periods	`sourcedId`, `title`, `startDate`, `endDate`, `type`, `schoolYear`, parent, children

Setup Checklist

Before your first upload

[ ] Receive SFTP host, username, and credentials from Lingco
[ ] Send Lingco your IP address so we can whitelist
[ ] Confirm your district can reach the host on port 22
[ ] Configure your SIS export for OneRoster v1.1 bulk CSV

First upload

[ ] Upload a sample archive and notify Lingco support
[ ] Lingco reviews file structure, org hierarchy, and course codes
[ ] Lingco maps SIS course codes to the Lingco course catalog
[ ] Verify a small sample of classes, users, and enrollments in Lingco
[ ] Confirm teacher vs. student role assignments look correct

Ongoing

[ ] Switch to the agreed nightly/weekly schedule
[ ] Monitor for sync failures during the first two weeks
[ ] Notify Lingco before major changes (new school year rollover, SIS upgrade, org restructuring)
[ ] Rotate SFTP credentials periodically

Troubleshooting

Connection refused or timeout Confirm port 22 outbound is open from the machine or SIS service doing the upload, and that you're using SFTP rather than FTP/FTPS. Double-check the host for typos. Ensure Lingco has whitelisted SIS IP address

Authentication failed Verify the username and password/key. If you recently rotated credentials, make sure your SIS's saved configuration was updated too. Contact Lingco support to re-issue credentials if needed.

Upload succeeds but nothing syncs Usually a structure problem: the CSVs are nested in a folder inside the zip, extra files are present in the archive, a required file is missing, or the manifest lists a file as absent or delta.

Some records are skipped Most often a broken reference — an enrollment pointing at a classSourcedId or userSourcedId that doesn't exist in the same archive, or a class pointing at a missing course or term. Bulk exports must be internally complete and consistent.

Classes appear but no students Check that the enrollment rows exist for those classes and that enabledUser is true on the relevant users.

Users can't sign in Confirm SSO is configured and that username/email in users.csv match what your identity provider sends. Rostered users have no local password.

Old classes and users won't go away Because Lingco treats each archive as the complete picture, anything omitted from the latest upload is removed. If stale records persist, the export is probably still including them.

Support

Lingco support — credential provisioning, course mapping, and sync troubleshooting.

Your SIS vendor — help generating a compliant OneRoster v1.1 bulk CSV export and scheduling automated SFTP delivery.

1EdTech — the OneRoster v1.1 specification and the CSV ZIP File Validation tool.

Technical Specs

File Format Requirements

All files must conform to the OneRoster v1.1 CSV binding.

Archive: one .zip file containing the CSVs at the root of the archive — no nested folders, no extra files.
Encoding: UTF-8. A byte order mark (BOM) is tolerated but not required.
Format: RFC 4180 CSV. Fields containing commas or double quotes must be wrapped in double quotes; a literal double quote inside a quoted field is escaped by doubling it (""). Carriage returns are not permitted inside a field.
Header row: required in every file. Headers must be spelled exactly as specified and must appear in exactly the order listed below.
All columns required: every column defined for a file must be present, even when you have no data for it. Leave the value empty rather than omitting the column.
Filenames and headers are case sensitive. users.csv, not Users.csv.
Dates: YYYY-MM-DD (note: this differs from the RESTful API's datetime format).
Bulk processing: because Lingco only accepts full exports, the status and dateLastModified columns must be present but empty in every row. Records that disappear from a subsequent export are treated as removed.
Multi-value fields (grades, subjects, subjectCodes, orgSourcedIds, termSourcedIds, periods, userIds) hold comma-separated lists inside a single quoted field — for example "09,10,11".
sourcedId values must be globally unique, stable across exports, and under 256 characters. If a sourcedId changes between runs, Lingco sees it as a brand new record.

Before your first delivery, we strongly recommend validating your archive with the 1EdTech CSV ZIP File Validation tool (a free 1EdTech account is required).

Required Files

Send all seven files below in every archive. If a file legitimately has no rows, still include it with its header row.

File	Contents
`manifest.csv`	Inventory of which files are included and how they should be processed
`orgs.csv`	Districts and schools
`academicSessions.csv`	School years, terms, semesters, grading periods
`courses.csv`	Course catalog offerings
`classes.csv`	Individual class sections
`users.csv`	Students and teachers
`enrollments.csv`	Which users belong to which classes, and in what role

demographics.csv is optional and not used by Lingco.

File Specifications

`manifest.csv`

Two columns: propertyName and value. Each row is one property/value pair.

propertyName	value
`manifest.version`	`1.0`
`oneroster.version`	`1.1`
`file.academicSessions`	`bulk`
`file.categories`	`absent`
`file.classes`	`bulk`
`file.classResources`	`absent`
`file.courses`	`bulk`
`file.courseResources`	`absent`
`file.demographics`	`absent`
`file.enrollments`	`bulk`
`file.lineItems`	`absent`
`file.orgs`	`bulk`
`file.resources`	`absent`
`file.results`	`absent`
`file.users`	`bulk`
`source.systemName`	Name of your SIS (e.g. `PowerSchool`)
`source.systemCode`	Your SIS vendor/instance code

Every file we consume must be marked bulk. Files marked delta will not be processed.

`orgs.csv`

Column order: sourcedId, status, dateLastModified, name, type, identifier, parentSourcedId

Field	Required	Notes
`sourcedId`	Yes	Unique, stable ID for the org
`status`	Leave empty	Bulk mode
`dateLastModified`	Leave empty	Bulk mode
`name`	Yes	Display name of the district or school
`type`	Yes	One of `district`, `school`, `department`, `local`, `state`, `national`. Lingco uses `district` and `school`.
`identifier`	No	Local/state school code
`parentSourcedId`	Conditional	Each school should point at its district's `sourcedId`

Lingco uses the org hierarchy to scope permissions — users only see data inside the organizations they belong to.

`academicSessions.csv`

Column order: sourcedId, status, dateLastModified, title, type, startDate, endDate, parentSourcedId, schoolYear

Field	Required	Notes
`sourcedId`	Yes
`status`	Leave empty
`dateLastModified`	Leave empty
`title`	Yes	e.g. `Fall Semester 2025`
`type`	Yes	`gradingPeriod`, `semester`, `schoolYear`, or `term`
`startDate`	Yes	`YYYY-MM-DD`
`endDate`	Yes	`YYYY-MM-DD`
`parentSourcedId`	No	e.g. a semester's parent school year
`schoolYear`	Yes	Four-digit year the session ends in, e.g. `2026`

Date ranges matter: Lingco uses them to determine which classes are current. Make sure terms cover the actual instructional dates.

`courses.csv`

Column order: sourcedId, status, dateLastModified, schoolYearSourcedId, title, courseCode, grades, orgSourcedId, subjects, subjectCodes

Field	Required	Notes
`sourcedId`	Yes
`status`	Leave empty
`dateLastModified`	Leave empty
`schoolYearSourcedId`	No	Points at an `academicSessions` row of type `schoolYear`
`title`	Yes	e.g. `Spanish II`
`courseCode`	No	Your SIS course code — used for mapping to Lingco content
`grades`	No	Comma-separated grade codes, e.g. `"09,10"`
`orgSourcedId`	Yes	The school or district that owns the course
`subjects`	No	e.g. `World Languages`
`subjectCodes`	No

Course codes and titles are what Lingco's team uses to map your SIS courses to the Lingco course catalog, so accurate, consistent values here make setup much faster.

`classes.csv`

Column order: sourcedId, status, dateLastModified, title, grades, courseSourcedId, classCode, classType, location, schoolSourcedId, termSourcedIds, subjects, subjectCodes, periods

Field	Required	Notes
`sourcedId`	Yes
`status`	Leave empty
`dateLastModified`	Leave empty
`title`	Yes	Shown to teachers and students in Lingco — make it recognizable, e.g. `Spanish II - Period 3`
`grades`	No
`courseSourcedId`	Yes	Must match a row in `courses.csv`
`classCode`	No	Section code from the SIS
`classType`	Yes	`scheduled` or `homeroom`. Lingco works with `scheduled`.
`location`	No	Room number
`schoolSourcedId`	Yes	Must match a `school` row in `orgs.csv`
`termSourcedIds`	Yes	One or more `academicSessions` IDs, comma-separated inside quotes
`subjects`	No
`subjectCodes`	No
`periods`	No	e.g. `"3"`

The class is the core unit in Lingco — assignments and grades attach to it.

`users.csv`

Column order: sourcedId, status, dateLastModified, enabledUser, orgSourcedIds, role, username, userIds, givenName, familyName, middleName, identifier, email, sms, phone, agentSourcedIds, grades, password

Field	Required	Notes
`sourcedId`	Yes
`status`	Leave empty
`dateLastModified`	Leave empty
`enabledUser`	Yes	`true` or `false`. `false` users are not provisioned.
`orgSourcedIds`	Yes	School(s) the user belongs to, comma-separated inside quotes
`role`	Yes	`student`, `teacher`, `administrator`, `aide`, `proctor`, `parent`, `guardian`, `relative`. Lingco provisions `student` and `teacher`.
`username`	Yes	Must match the identifier your SSO provider sends
`userIds`	No
`givenName`	Yes	First name
`familyName`	Yes	Last name
`middleName`	No
`identifier`	No	Student/staff ID
`email`	Recommended	Should match the email in your identity provider
`sms`	No	Leave empty
`phone`	No	Leave empty
`agentSourcedIds`	No	Parent/guardian links — not used by Lingco
`grades`	No	Student grade level
`password`	No	Leave empty. Lingco never sets local passwords from a roster file.

Authentication: OneRoster-provisioned accounts are SSO-only. Users sign in through your district identity provider (Google, Clever, ClassLink, Microsoft, or LTI launch) — they do not have Lingco passwords. Make sure the username and email values here match what your IdP asserts, or accounts won't link up.

`enrollments.csv`

Column order: sourcedId, status, dateLastModified, classSourcedId, schoolSourcedId, userSourcedId, role, primary, beginDate, endDate

Field	Required	Notes
`sourcedId`	Yes
`status`	Leave empty
`dateLastModified`	Leave empty
`classSourcedId`	Yes	Must match a row in `classes.csv`
`schoolSourcedId`	Yes	Must match a `school` row in `orgs.csv`
`userSourcedId`	Yes	Must match a row in `users.csv`
`role`	Yes	`student`, `teacher`, `administrator`, or `proctor`
`primary`	Conditional	`true` for the teacher of record on co-taught sections
`beginDate`	No	`YYYY-MM-DD`
`endDate`	No	`YYYY-MM-DD`

Every student and every teacher needs a separate row for each class they're in.

OneRoster SFTP