Import reunification roster data

Imports a reunification roster as JSON. This is the API equivalent of the in-app CSV upload and writes to the same roster.

Every call replaces the whole roster. Records you send are created or updated, and anything you leave out is deleted. Only records that came from this API or the in-app CSV upload are replaced.

Deleting someone revokes the Coram access an earlier import gave them. Access granted by hand survives. Revocation is also skipped when a previous import has not finished creating accounts yet, and when more than half of a provisioned roster of 10 or more people would lose access at once, which stops a truncated upload locking out a school.

Send every key on every call. The one you may omit is staff, and omitting it deletes every staff member.

The import aborts and leaves the old roster intact if two schools map to the same Coram location, if a location id does not exist, or if a student or teacher repeats a school id in school_ids after the first one. Repeating a student_id, teacher_id or staff_id returns 400 before any work starts.

The order of the top level arrays does not matter.

The import runs in the background and is cancelled after one hour. The 202 carries the initial status. Poll GET /v1/reunification/imports/status. One import runs per organization at a time and the in-app CSV upload counts as one, so a second request returns 409.

Requires write:* scope and an admin creator role, and the feature must be enabled for your organization. The status endpoint needs read:*, so a write-only key can start an import but never see whether it worked. Requests are limited to an average of 5 per second with a short burst allowance, and the body to 32 MiB.

Request body

school_location_mappingsobject required

Maps your school ids to Coram location IDs. Must be present and non-empty. Give every school an entry, because a school without one is imported with no location and everyone attached only to it loses access. Two schools may not point at the same location, and a location that does not exist in your organization aborts the import after it has already returned 202. The location id in the example is illustrative, so look up your real ones with GET /v1/locations before your first call.

Response

Import accepted and processing started

idstring required

status'in_progress' | 'completed' | 'failed' required

synced_schoolsinteger

total_schoolsinteger

synced_studentsinteger

total_studentsinteger

synced_teachersinteger

total_teachersinteger

synced_staffinteger

total_staffinteger

synced_guardiansinteger

total_guardiansinteger

Counted after the merge described on the guardian object, so it is usually lower than the number of guardian entries you sent.

succeeded_usersinteger

Coram accounts created or updated. Rises in the background after status becomes completed. Guardians are never included, because they get no account.

failed_usersinteger

Accounts that could not be created, usually a seat limit or an Auth0 rejection. Zero does not mean everyone succeeded, since anyone without a valid email is absent from both figures.

error_messagestring

started_atstring date-time

Carries a real time only while the import is in progress. Once it reaches completed or failed the field is still returned but reset to 0001-01-01T00:00:00Z, so record the start time yourself if you need it.

completed_atstring date-time

Returned as 0001-01-01T00:00:00Z until the import finishes.

Import reunification roster data

Request body

Response

Changes