API docs / API reference

Create or update in a batch

POST/v1/contributions/batch

Send up to 100 contributions in one request, for bulk changes and backfills.

Request

curl https://api.equitymatrix.io/v1/contributions/batch \
  -H "Authorization: Bearer $EQUITY_MATRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contributions": [
      { "memberEmail": "ana@example.com", "type": "TIME", "value": 3.5, "date": "2026-09-30", "description": "Q3 close", "externalId": "harvest:time_entry:2291837" },
      { "memberEmail": "ben@example.com", "type": "CASH", "value": 1200, "date": "2026-09-29", "description": "Laptop", "externalId": "odoo:hr.expense:318" }
    ]
  }'

Each item takes the same fields as Create or update a contribution and follows the same rules.

All or nothing

  • The batch must have between 1 and 100 items.
  • If any item is invalid, nothing is saved and you get a 422 listing each failing item by its position in the list (starting at 0).
  • Two items with the same externalId in one batch are rejected.

An empty batch, or one with more than 100 items, is rejected as a whole, with the error on contributions instead of on an item:

{
  "error": "validation_failed",
  "message": "contributions must have between 1 and 100 items.",
  "fields": [{ "field": "contributions", "message": "contributions must have between 1 and 100 items." }]
}

A batch with invalid items gets items instead, one entry per failing item:

{
  "error": "validation_failed",
  "message": "1 contribution failed validation. Nothing was saved.",
  "items": [
    {
      "index": 1,
      "fields": [{ "field": "memberEmail", "message": "No member in this organization has this email." }]
    }
  ]
}

Response

200 with one result per item, in the order you sent them:

{
  "results": [
    { "result": "updated", "contribution": { "id": 1842, "externalId": "harvest:time_entry:2291837", "multiplier": 2, "slices": 595 } },
    { "result": "created", "contribution": { "id": 1907, "externalId": "odoo:hr.expense:318", "multiplier": 4, "slices": 4800 } }
  ]
}

Each contribution has the full shape shown in Create or update a contribution. It’s shortened here.