Send metric values

Goal programs reward people for reaching a target, such as closing 50 deals. Your systems report each person's progress, and Teambrite works out who has earned a reward.

Before you start

You need a key with the metric:write scope, and two IDs:

• The employee's ID, which starts with emp_. Find it by filtering on their work email or the ID your own system uses for them, which needs a key with employee:read. It's also in the address of their profile in the dashboard.
• The metric's key, in snake_case. The dashboard doesn't show these yet, so email [email protected] and we'll send you yours.

Send the full value each time

Every value belongs to one person and is never added up across people. If someone has closed 12 deals, send 12, not 1.

curl -X POST https://api.teambrite.com/v1/metrics \
  -H "Authorization: Bearer $TEAMBRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "emp_LssEG8crOK3xrxCVx1nS6jy7",
    "metricKey": "sales_closed",
    "value": 12,
    "idempotencyKey": "crm-event-8f3a2c71"
  }'

A 202 means the value has been recorded safely, and answers with an id for this reading. Checking it against your programs happens afterwards.

How values are applied

Each value is checked by itself, in the order Teambrite receives them, and the program's dates are compared with when it arrived.

• A program pays each person once, the first time any value reaches its target.
• A later, lower value doesn't undo a reward. Neither does a counter going back to zero, and an older value arriving late doesn't overwrite a newer one.
• To correct a value, send the right one with a new idempotencyKey. A reward that has already been earned stays earned.

Choose an idempotency key

Use something that names this one reading, like the ID of the event in your system. A key based on the person and the month doesn't work, because the total changes during the month and a key can only ever mean one value.

Keys are unique across your whole company, whichever API key sent them, and Teambrite never forgets one.

Retry safely

If you get a 500 or lose the response, send the same request again with the same idempotencyKey. A person's value is only recorded once, even if two copies arrive at the same moment.

See what happened

Pass the id to Get a metric value to see how it went. Keep checking until status is completed.

See Send a metric value for every field and status.