Batch upsert trainings — Create or update up to 1,000 trainings in a single request

Create or update up to 1,000 trainings in a single request. You can now sync training records in batches using POST /v3/trainings/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.

Matching logic

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

Identifiers provided	Path	Behaviour
`externalReferenceId`	Upsert	Update if found, create if not
`trainingId`	Strict update	Update if found → `TRAINING_NOT_FOUND` if not. No create fallback.
Neither	Create	`name`, `startDateTime`, `endDateTime` required
Both	Rejected	Fails with `AMBIGUOUS_TRAINING_IDENTIFIER`

Each training 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 trainings per request
Partial success support: failed records don't block the rest
Deterministic behaviour: no implicit restoration or hidden side effects
Idempotent syncs using your own identifiers
Roster replacement: pass student and group identifiers to sync enrollment in the same call
Metadata storage: attach arbitrary key-value data to each training record
No cross-record side effects: each training is processed independently

What to expect

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

Overview

Endpoint: POST /v3/trainings/batch-upsert

Limits: minimum 1, maximum 1,000 trainings per request. The endpoint is rate-limited.

{
  "trainings": [
    {
      "name": "Introduction to Economics",
      "externalReferenceId": "your-external-reference-id-001",
      "externalReferenceType": "external-system-source",
      "startDateTime": "2026-09-01T09:00:00Z",
      "endDateTime": "2027-06-30T18:00:00Z",
      "goals": "Understand macroeconomic fundamentals",
      "tags": ["economics", "promo-2026"],
      "metadata": { "internalCode": "ECO-101" },
      "studentExternalReferenceIds": ["STU-001", "STU-002"],
      "groupExternalReferenceIds": ["GROUP-001"],
      "professorExternalReferenceIds": ["prof-ref-001"]
    },
    {
      "trainingId": "gkia42e40c9s6i9",
      "name": "Advanced Computer Science",
      "startDateTime": "2026-09-02T09:00:00Z",
      "endDateTime": "2027-06-30T18:00:00Z",
      "studentIds": ["456t5qgc1ai7gljh"],
      "groupIds": ["2z7733r2diu8n9zd"],
      "professorIds": ["bkia42e40c9s6i7"]
    }
  ]
}

Training fields:

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

Field	Type	Description
`trainingId`	string	Edusign internal training ID — alternative match key for strict update only.
`externalReferenceId`	string	Your unique identifier for the training. Used as the create-or-update match key. Max 64 characters.
`externalReferenceType`	string	Name of the source system or connector. Max 30 characters.
`name`	string	Required on create.
`startDateTime`	string (ISO 8601)	Required on create. Start date and time with timezone offset.
`endDateTime`	string (ISO 8601)	Required on create. End date and time with timezone offset. Must be after `startDateTime`.
`goals`	string	Accepts `null` to clear.
`tags`	string[]	Accepts `null` to clear.
`metadata`	object	Arbitrary key-value pairs. Accepts `null` to clear.
`studentIds`	string[]	Edusign internal student IDs to enroll. Full replacement semantics.
`studentExternalReferenceIds`	string[]	External reference IDs of students to enroll. Full replacement semantics.
`groupIds`	string[]	Edusign internal group IDs — enrolls all active students in those groups.
`groupExternalReferenceIds`	string[]	External reference IDs of groups — enrolls all active students in those groups.
`professorIds`	string[]	Edusign internal professor IDs to assign.
`professorExternalReferenceIds`	string[]	External reference IDs of professors to assign.

Use only one field from each pair: studentIds or studentExternalReferenceIds, groupIds or groupExternalReferenceIds, professorIds or professorExternalReferenceIds.