Teambrite
Metrics

Send a metric value

POST/v1/metrics

Records one employee's current value for a metric, then checks it against every active goal program using that metric. Send the full value each time, not a change: if someone has closed 12 deals, send 12. Each value is checked by itself, in the order they arrive, using the time Teambrite receives it. A program pays a person once, the first time any value reaches its target, and a later lower value or a counter reset doesn't undo that. To correct a value, send a new one with a new idempotencyKey. Idempotency keys are unique across your company and kept for good. A replay with the same employee, metric and value answers 202 with duplicate: true and the original id and acceptedAt, including when two arrive at once, and only one is recorded.

Needs a key with the metric:write scope.

Body

  • employeeIdstring

    An active employee in your company. Find it with List employees.

  • metricKeystring

    The key of one of your metrics, in snake_case.

  • valueinteger

    The employee's total so far, not a change since last time. A whole number, which can be negative.

  • idempotencyKeystring

    A value you choose that names this one reading, such as the ID of the event that produced it. Unique across your whole company and never forgotten, so send a new one whenever the value changes.

Response

202: The value has been recorded safely. Checking it against your programs happens afterwards, and Get a metric value shows the result.

  • idstring

    The ID of this reading. Use it to check how it went with Get a metric value. A replay answers with the original ID.

  • statusenum

    pending is recorded and waiting. processing is being checked against your programs. completed is checked. failed means the last check hit a problem on our side, and Teambrite keeps retrying for 24 hours, so there's no need to send it again.

    pendingprocessingcompletedfailed

  • acceptedAtstring

    When Teambrite first recorded it. A replay answers with the original time.

  • duplicateboolean

    true if this request repeated one already recorded, and nothing new was recorded.

Errors

  • 400METRIC_OBSERVATION_INVALID: The body doesn't match the required fields.
  • 401API_KEY_INVALID: The key is missing, wrong, expired or revoked.
  • 403API_KEY_SCOPE_MISSING: The key is valid but wasn't given the scope this endpoint needs. PLAN_UPGRADE_REQUIRED: Your plan doesn't include the API. COMPANY_CLOSED: Your company has closed its Teambrite account.
  • 404EMPLOYEE_NOT_FOUND: No employee in your company has this ID.
  • 409METRIC_IDEMPOTENCY_CONFLICT: The idempotency key was already used with a different employee, metric or value.
  • 411REQUEST_LENGTH_REQUIRED: The request didn't declare its length.
  • 413REQUEST_TOO_LARGE: The body is over 1 MB.
  • 422EMPLOYEE_INACTIVE: The employee is no longer active. METRIC_NOT_FOUND: Your company has no metric with this key. METRIC_ARCHIVED: This metric has been archived.
  • 429API_KEY_RATE_LIMITED: The key is over 600 requests a minute.
  • 500METRIC_OBSERVATION_FAILED: A problem on our side stopped the value being recorded.

Get program review

Programs that would pay someone twice, or never pay anyone.

Get a metric value

See how a value you sent was checked against your goal programs.

Copyright © 2026