Teambrite
Employees

Create an employee

POST/v1/employees

Adds an active employee. Programs that reach everyone, or match their dates, start including them straight away. Nobody is emailed. To archive someone who has left, use the Teambrite dashboard: the API can't. Email and externalId are each unique in your company, so a retried create can't add someone twice: it answers 409 with data.employeeId, the person the first attempt made.

Needs a key with the employee:write scope.

Body

  • fullNamestring

    Their full name.

  • emailstring

    Their work email. Rewards are sent here, and no two employees in your company can share one. Capitals don't matter.

  • startDatedate or null

    The day they started. Work anniversary programs count from it.

  • birthdaystring or null

    Their birthday as MM-DD. Send no year: Teambrite never keeps one. Whether coworkers see it stays their own choice.

  • timezonestring or null

    Their IANA time zone, such as America/Toronto.

  • externalIdstring or null

    The ID your own system uses for them. No two employees in your company can share one.

  • externalIdSourcestring or null

    The system externalId comes from, such as workday.

Response

201: The employee was added. Their profile, as List employees shows it.

  • idstring

    The employee's ID, which is also in the address of their dashboard profile. Use it as employeeId when you send a metric value.

  • fullNamestring

    The employee's full name.

  • emailstring or null

    Their work email.

  • startDatedate or null

    The day they started.

  • yearsOfServiceinteger or null

    Whole years since startDate, as of today in your company's time zone. Someone who started on 29 February reaches the next year on 28 February in other years. null with no start date, or one still to come.

  • birthdaystring or null

    Their birthday as MM-DD. Teambrite keeps no birth year. null if it's missing or they have made it private, and the two aren't told apart.

  • avatarUrlstring or null

    The address of the picture they uploaded.

  • timezonestring or null

    Their IANA time zone, such as America/Toronto.

  • externalIdstring or null

    The ID your own system uses for them.

  • externalIdSourcestring or null

    The system externalId came from.

Errors

  • 400REQUEST_BODY_INVALID: The body has a field that is unknown, missing or out of range.
  • 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. PLAN_HEADCOUNT_LIMIT: Adding this person would take you past the number of employees your plan covers.
  • 409EMPLOYEE_EMAIL_TAKEN: Another employee in your company already has this email. EMPLOYEE_EXTERNAL_ID_TAKEN: Another employee in your company already has this externalId.
  • 411REQUEST_LENGTH_REQUIRED: The request didn't declare its length.
  • 413REQUEST_TOO_LARGE: The body is over 1 MB.
  • 429API_KEY_RATE_LIMITED: The key is over 600 requests a minute.

List employees

Your active employees, with the IDs you need to send metric values.

Update an employee

Change someone's profile, such as a new start date or email.

Copyright © 2026