API - Users

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

TL;DR

• Use GET /api/v1/users to search for 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 supported user fields.
• Use DELETE /api/v1/users/{user_id} to offboard a former employee.
• Deleting a user preserves their historical activity and existing metrics attribution.
• Deleted users can currently be restored through the LinearB UI. Restoration through the API is planned.
• 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 users with roles and team membership
• Updating supported user attributes
• Managing contributor identity metadata and team scopes
• Deleting users when offboarding former employees

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

Before You Begin

Authentication

All Users API requests require an API token.

1. Go to Company Settings → API Tokens.
2. Create or reuse an API token.
3. Add the token to the x-api-key header of every request.

x-api-key: <your_api_token>

User model

User objects can include the following fields (non-exhaustive):

• id — LinearB user ID
• organization_id — owning organization
• name — full name
• email — primary email address
• avatar_url — avatar URL, if available
• created_at, updated_at, and deleted_at — timestamps
• team_membership — team-membership information
• permissions — role and team scopes
• connected_users — linked platform users and contributor identities
• custom_info — fields such as extra_emails and extra_ids

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

When to use this API

• You maintain contributor identities outside LinearB.
• You want automated onboarding and offboarding workflows.
• You need to synchronize email aliases and extra IDs across systems.
• You programmatically manage users associated with teams, deployments, or analytics.

Endpoints and Usage

1. List all users

GET /api/v1/users

2. Get a user by ID

GET /api/v1/users/{user_id}

3. Create users

POST /api/v1/users

4. Update a user

PATCH /api/v1/users/{user_id}

5. Delete a user

DELETE /api/v1/users/{user_id}

6. Restore a deleted user

Identity Behavior in LinearB

Multiple emails per user

Users may commit under different email addresses. Adding alternate emails, for example through custom_info.extra_emails when supported by the API schema, helps ensure:

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

Merging duplicate identities

Duplicate accounts, such as multiple Git identities belonging to the same developer, should be merged through the LinearB UI:

• Settings → Users & Teams → ⋮ → Merge Account

User merging is not currently supported through the Users API.

Impact on teams and metrics

• Updating email addresses and additional identity information helps LinearB attribute activity to the correct user.
• Team membership is represented by team_membership, with team scopes represented in the user’s permissions.
• Changes to users and team memberships may take a short time to appear across all dashboards.

Seat Usage and Billing

The Users API does not currently expose a dedicated is_billable field.

Use team_membership as the seat-counting signal. A user whose team_membership value is not null is billable.

Verify and Troubleshoot

Verify an updated user

1. Update a user through PATCH /api/v1/users/{user_id} using supported fields.
2. Confirm that the API returns a successful 2xx response and that the response body, if returned, reflects the updated values.
3. Call GET /api/v1/users/{user_id} or GET /api/v1/users and confirm that the user record contains the expected 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 the update.

Verify a deleted user

1. Delete the user through DELETE /api/v1/users/{user_id}.
2. Confirm that the API returns a successful 2xx response.
3. In LinearB, confirm that the user no longer appears in the applicable active-user views.
4. Confirm that the contributor’s historical activity remains available.
5. If required, exclude the contributor’s historical activity from metrics separately.

Quick fixes for common issues

• User not appearing as expected
  — Use GET /api/v1/users to confirm that the user exists.
  — In the UI, clear search, team, and role filters and search using the user’s complete email address.
• Email updates not reflected in activity
  — Confirm that all relevant email addresses are associated with the contributor identity.
  — Verify that Git commits use one of the configured email addresses.
  — Allow time for new activity to be processed.
• 422 validation errors
  — Confirm that the request body is valid JSON.
  — Check the request against the current API schema.
  — Confirm that every supplied field is writable and uses the required data type.
• 401 Unauthorized or 403 Forbidden
  — Confirm that the API token is valid and belongs to the correct organization.
  — Send the token in the x-api-key: <your_api_token> header.
  — If the request passes through a proxy, confirm that the proxy preserves the x-api-key header.

Advanced troubleshooting

Use this matrix when user records still do not behave as expected.

FAQ

For complete endpoint and schema information, visit the Users API documentation .

For additional technical assistance, contact LinearB Support .