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

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

 {
   "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"
     }
   ]
 }

Response: 200when all groups succeed, or207 when the batch contains both successes and failures.

  {
  "data": {
    "succeeded": [
      {
        "inputIndex": 0,
        "id": "group-internal-id",
        "type": "created",
        "externalReferenceId": "your-external-reference-id-001"
      }
    ],
    "failed": [
      {
        "inputIndex": 1,
        "externalReferenceId": "your-external-reference-id-002",
        "error": {
          "code": "GROUP_ARCHIVED_EXISTS",
          "message": "Cannot update archived group",
          "field": "externalReferenceId"
        }
      }
    ]
  },
  "meta": {
    "total": 2,
    "createdCount": 1,
    "updatedCount": 0,
    "failureCount": 1,
    "processedAt": "2026-04-10T10:00:00.000Z"
  }
}

Group fields:

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

Field	Type	Description
`externalReferenceId`	string	Your unique identifier for the group. 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. Max 255 characters.
`description`	string	Accepts `null` to clear. Max 255 characters.
`parentExternalReferenceId`	string	External reference ID of the parent group. Accepts null to clear. Max 255 characters.s
`photoUrl`	string (URL)	Accepts `null` to clear. Max 500 characters.