Batch upsert students — Create or update up to 1000 students in a single request

Create or update up to 1,000 students in a single request You can now sync student records in batches using POST /v3/students/batch-upsert.

This endpoint replaces thousands of sequential requests with a single call, making large-scale imports faster and more reliable for ERP and SIS integrations.

How it works

This endpoint performs a batch upsert (create-or-update in one request):

Students are matched using externalReferenceId
If a match is found → the student is updated
If no match is found → a new student is created

Each student is processed independently, so one failure does not block the rest of the batch.

What’s new

Batch upsert: create or update up to 1,000 students per request
Partial success support: failed records don’t block the rest
Deterministic behavior: no implicit restoration or hidden side effects
Idempotent syncs using your own identifiers
No cross-record side effects: each student is processed independently

What to expect

Returns 200 when all students succeed
Returns 207 when some students fail
Use inputIndex to map results to your original payload

Overview

Endpoint: POST /v3/students/batch-upsert

Limits: minimum 1, maximum 1000 students per request. The endpoint is rate-limited.

{
  "students": [
    {
      "firstName": "Marie",
      "lastName": "Dupont",
      "email": "[email protected]",
      "externalReferenceId": "your-external-reference-id-001",
      "externalReferenceType": "Ypareo",
      "phone": "+33600000000",
      "curriculumName": "Master of Economics",
      "company": "Edusign",
      "badgeId": "BADGE-001",
      "tags": ["promo-2026"],
      "fileNumber": "F-0042",
      "photoUrl": "https://cdn.example.com/photo.jpg"
    },
			{
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "externalReferenceId": "your-external-reference-id-002",
      "externalReferenceType": "external-system-source",
      "phone": "+33600000000",
      "curriculumName": "Master of Computer Sciences",
      "company": "Edusign",
      "badgeId": "BADGE-002",
      "tags": ["promo-2026"],
      "fileNumber": "F-0043",
      "photoUrl": "https://cdn.example.com/photo.jpg"
    }
  ],
  "options": {
    "allowUnarchive": false,
    "onStudentCreated": {
      "sendCredentials": false,
      "newPasswordNeeded": false
    }
  }
}

Student fields:

Defines the attributes used to create or update a student record. Only provided fields are updated (partial update semantics).

Field	Type	Description
`externalReferenceId`	string	Your unique identifier for the student. Used as the create-or-update match key. Max 64 characters.
`externalReferenceType`	string	Name of the source system or connector. Max 30 characters.
`firstName`	string	Required on create. Max 100 characters.
`lastName`	string	Required on create. Max 100 characters.
`email`	string	Accepts `null` to clear the value. Max 255 characters
`phone`	string	Accepts `null` to clear. Max 20 characters
`photoUrl`	string (URL)	Accepts `null` to clear. Max 255 characters
`fileNumber`	string	Accepts `null` to clear. Max 128 characters
`curriculumName`	string	Accepts `null` to clear. Max 160 characters
`company`	string	Accepts `null` to clear. Max 64 characters
`badgeId`	string	Accepts `null` to clear. Max 20 characters
`tags`	string[]	Accepts `null` to clear. Max 15 tags, each max 35 characters

Options:

Field	Default	Description
`allowUnarchive`	`false`	When `true`, an archived student that matches `externalReferenceId` is unarchived and updated instead of rejected.
`onStudentCreated.sendCredentials`	`false`	Sends login credentials by email to newly created students
`onStudentCreated.newPasswordNeeded`	`false`	Requires newly created students to set a password on first login