API docs / API reference

Create or update a contribution

POST/v1/contributions

Log a contribution, or update one you sent before by sending its external ID again.

Request

curl https://api.equitymatrix.io/v1/contributions \
  -H "Authorization: Bearer $EQUITY_MATRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memberEmail": "ana@example.com",
    "type": "TIME",
    "value": 3.5,
    "date": "2026-09-30",
    "description": "Q3 close",
    "externalId": "harvest:time_entry:2291837"
  }'
FieldRequiredDescription
memberIdExactly one of memberId or memberEmailThe member’s id from List members.
memberEmailExactly one of memberId or memberEmailThe member’s email, matched without regard to case.
typeYes, unless you send contributionTypeIdTIME, CASH, COMMISSION or ROYALTY. For a custom type, leave it out or send CUSTOM.
contributionTypeIdFor a custom typeThe custom type’s id from List contribution types. Don’t send it with a built-in type.
valueYesHours for TIME, an amount in your organization’s currency otherwise. Greater than 0, at most 2 decimal places.
dateYesThe day of the contribution, as YYYY-MM-DD. It can’t be in the future. A date one day ahead of today in UTC is allowed, for callers whose day has already started.
descriptionNoUp to 500 characters. Spaces at the start and end are removed.
externalIdNo, but send it from any syncThe record’s ID in the other system. See Syncing with external IDs.

Logging a custom type

curl https://api.equitymatrix.io/v1/contributions \
  -H "Authorization: Bearer $EQUITY_MATRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memberEmail": "ana@example.com",
    "contributionTypeId": 12,
    "value": 450,
    "date": "2026-09-30",
    "description": "Camera body",
    "externalId": "odoo:hr.expense:412"
  }'

What happens

  • No externalId, or one Equity Matrix hasn’t seen: creates a contribution and returns 201 with "result": "created".
  • An externalId that matches an active contribution: replaces it with what you sent, recalculates slices, and returns 200 with "result": "updated". Fields you leave out are cleared.
  • Nothing changed, slices included: returns 200 with "result": "unchanged".

On an update, a contribution keeps the hourly rate and multiplier stored on it as long as it stays with the same member and type. If the update moves it to a different member, or changes another type to TIME, it takes that member’s current hourly rate. If it changes the type, it takes the new type’s current multiplier. See Contributions and slices.

Response

{
  "result": "created",
  "contribution": {
    "id": 1842,
    "externalId": "harvest:time_entry:2291837",
    "memberId": 57,
    "memberName": "Ana Lopez",
    "type": "TIME",
    "contributionTypeId": null,
    "contributionTypeName": null,
    "expenseSource": null,
    "value": 3.5,
    "date": "2026-09-30",
    "description": "Q3 close",
    "hourlyRate": 85,
    "multiplier": 2,
    "slices": 595,
    "source": "API",
    "apiKeyName": "Harvest",
    "createdAt": "2026-09-30T18:04:11Z",
    "updatedAt": "2026-09-30T18:04:11Z"
  }
}

slices is value × hourlyRate × multiplier for TIME, and value × multiplier for the other types. hourlyRate is null for types other than TIME. For a custom type, type is CUSTOM and contributionTypeId and contributionTypeName identify it; they’re null for built-in types. expenseSource is only set on EXPENSE contributions, which can’t be created through the API. See Deposits and expenses.

Errors

A 422 with fields for invalid input. See Errors for the full list.