Skip to main content
Sign in
Deutsch (Deutschland) Español Français Italiano Português

Users API

Heather Hazell
  • Updated

The Users API allows you to automate provisioning, lookup, and update of contributor identities inside LinearB. This API is typically used by organizations that sync users from identity systems, maintain centralized contributor records, or need automated onboarding/offboarding flows.

TL;DR

  • Use GET /api/v1/users to search users in your LinearB organization.
  • Use POST /api/v1/users to create one or more users.
  • Use PATCH /api/v1/users/{user_id} to update a user’s details, role, and team membership.
  • Use DELETE /api/v1/users/{user_id} to remove a user record.
  • Users represent developer identities used for LinearB metrics, team membership, and activity attribution.

Overview

The Users API supports:

  • Searching and listing users in your LinearB organization
  • Creating new users with roles and team membership
  • Updating user attributes (for example, name, email, roles, and extra IDs/emails)
  • Managing contributor identity metadata and team scopes
  • Deleting users when they should no longer appear in your organization

Users represent developer identities used by LinearB to calculate team metrics, PR activity, deployments, AI insights, and more.

Before You Begin

Authentication

All API requests require an API token.

  1. Go to Company Settings → API Tokens.
  2. Create (or reuse) an API token.
  3. Add it to the header of every request:
Authorization: Bearer <your_api_token>

User model

User objects can include (non-exhaustive):

  • id — LinearB user ID
  • organization_id — owning organization
  • name — full name
  • email — primary email address
  • avatar_url — avatar image URL (if available)
  • created_at, updated_at, deleted_at — timestamps
  • team_membership — array of objects with name and joined_at fields
  • permissions — role and team scopes
  • connected_users — linked platform users and contributors
  • custom_info — fields such as extra_emails and extra_ids

For full schema details, refer to the external API documentation linked at the bottom of this article.

When to use this API

  • You maintain contributor identities outside of LinearB.
  • You want automated join/leave flows.
  • You need to synchronize email aliases and extra IDs across systems.
  • You programmatically manage users tied to teams, deployments, or analytics.

Endpoints & Usage

1. List all users

Retrieve all users
GET /v2/users

Returns a (optionally paginated) list of users in your LinearB organization.

2. Get a user by ID

Retrieve a specific user
GET /v2/users/{user_id}

Returns the full user record for the given user_id.

3. Update a user

Modify user fields

You can update fields such as active and emails.

PATCH /v2/users/{user_id}

Example body

{
  "active": true,
  "emails": [
    "primary@acme.com",
    "alias@acme.com"
  ]
}

4. Deactivate a user

Disable a user without deleting data
PATCH /v2/users/{user_id}

Example body

{
  "active": false
}

Deactivated users are ignored in team membership and metrics going forward, but historical data is preserved.

Identity behavior in LinearB

Multiple emails per user

Users may commit under different email addresses. Adding alternate emails (for example, via custom_info.extra_emails) helps ensure:

  • Accurate contributor attribution
  • Unified activity across repositories
  • Consistent team membership and permissions

Merging duplicate identities

Duplicate accounts (multiple Git identities for the same developer) should be merged using the UI:

  • Settings → Users & Teams → ⋮ → Merge Account

This cannot be done via the Users API.

Impact on teams and metrics

  • Updating email addresses and extra emails helps LinearB attribute activity to the correct user.
  • Team membership is driven by the team_membership array and team scopes in permission.
  • Changes to users and memberships may take a short time to be reflected across all dashboards.

Verify & Troubleshooting

Verify an updated user

  1. Update a user via PATCH /api/v1/users/{user_id} with the desired changes.
  2. Confirm you receive a 2xx response and that the response body (if returned) reflects the updated fields.
  3. Call GET /api/v1/users/{user_id} or GET /api/v1/users to verify the user record contains the new values.
  4. In LinearB, go to Settings → Users & Teams → Users and confirm:
    • The user appears with the correct name and email.
    • The user’s role and team access match your update.

Quick fixes (most common issues)

  • User not appearing as expected
    – Use GET /v2/users to confirm the user exists and is active.
    – In the UI, clear any filters (search, teams, roles) and search by full email address.
  • Email updates not reflected in activity
    – Confirm all relevant email addresses were added to the user’s emails array.
    – Verify that Git commits are using one of the configured email addresses.
  • 422 validation errors
    – Ensure you’re sending valid JSON.
    – Check that field types are correct (for example, emails is an array of strings, active is a boolean).
  • 401 Unauthorized or 403 Forbidden
    – Confirm your API token is valid and belongs to the correct organization.
    – Make sure it is sent in the Authorization: Bearer <your_api_token> header.

Advanced troubleshooting (problem → cause → fix)

Use this matrix when user records still don’t behave as expected.

Problem Cause Fix
User not updated The update request failed validation or authorization.
Common causes include invalid field types or a missing/invalid token.		 Check the HTTP status and response body (especially 400 / 422 error details).
Correct the payload (or API token) and resend the request.
User visible via API but not in UI filters The user does not match current UI filters (for example, team filters or search text),
or the user is inactive and the view is scoped to active-only.		 In the UI, clear filters and search by full email.
Use GET /v2/users/{user_id} to confirm the user’s active state and other attributes.
Duplicate user identities Multiple user records exist for the same person with different email addresses or identities. Decide which record should be canonical.
Add all relevant email addresses to the canonical user, and use the in-app merge flow where appropriate.
Commit activity not associated with the user Commits are using an email address that is not listed under the user’s emails array. Add the commit email address to the user’s emails list via PATCH /v2/users/{user_id}, then allow time for new activity to be processed.

FAQ

Does deactivating a user remove historical data?

No. It only prevents the user from appearing in new metrics and team membership going forward.

Can I delete a user?

Deletion is not supported; use deactivation instead to stop new activity from being counted.

Can I merge users through the API?

No. Merges must be done in the LinearB UI.

For additional information, please visit our Users API documentation.

For additional technical support, please contact LinearB support.

Comments

0 comments

Article is closed for comments.