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

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

• Groups are matched using externalReferenceId
• If a match is found → the group is updated
• If no match is found → a new group is created

Each group 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 groups 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 group is processed independently

What to expect

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

Overview

Endpoint: POST /v3/groups/batch-upsert

 {
   "groups": [
     {
       "name": "Promo 2026 - Paris",
       "externalReferenceId": "your-external-reference-id-001",
       "externalReferenceType": "Ypareo",
       "description": "First year economics cohort",
       "parentExternalReferenceId": "parent-group-ref-001",
       "logoUrl": "https://cdn.example.com/logo.png"
     },
     {
       "name": "Promo 2026 - Lyon",
       "externalReferenceId": "your-external-reference-id-002",
       "externalReferenceType": "Ypareo",
       "description": "First year computer science cohort",
       "parentExternalReferenceId": "parent-group-ref-001",
       "logoUrl": "https://cdn.example.com/logo2.png"
     }
   ]
 }

Group fields:

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