The Salesforce User Management REST API is the standard REST API applied to the User object. You can query, create, update, and deactivate users with it. You cannot delete them. Create calls need 9 required fields, deactivation is a PATCH that sets IsActive to false, and every call runs against your org's 24 hour API allocation.
This page covers the endpoints, the required fields, the errors that block deactivation, the API limits that break bulk jobs, and when SCIM or Apex REST is the better tool. Current as of API version 67.0 (Summer '26).
What Is Salesforce User Management REST API?
Salesforce User Management REST API refers to using Salesforce's standard REST API to interact with the User object. The User object stores information such as username, email, profile, role, and active status.
Through REST API, external systems can manage Salesforce users without manual intervention, as long as authentication and permissions are correctly configured.
Official Salesforce documentation for user management
Salesforce maintains two official documentation pages that cover user management through REST API.
The first page explains how Salesforce REST API works, including authentication, request structure, and API versions.
https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_rest.htm
The second page documents the Salesforce User object. It lists all fields, required attributes, and update permissions.
These two links are sufficient for understanding and implementing user management through REST API.
What Can You Do with Salesforce User REST API?
Using Salesforce REST API, you can perform the following actions on users.
Salesforce applies the same validation, sharing, and license rules to REST API calls that it applies in the user interface. An API call cannot do anything the calling user could not do by hand.
Salesforce user REST API endpoint reference
Every call below is relative to your instance base URI, which takes the form https://MyDomainName.my.salesforce.com/services/data/v67.0. There is no dedicated user management endpoint. User records are handled through the generic sObject endpoints.
| Action | Method and path | Success response |
|---|---|---|
| Read one user | GET /sobjects/User/{userId} | 200 with the full record |
| List or filter users | GET /query?q=SELECT+Id,Username,IsActive+FROM+User | 200 with records and totalSize |
| Create a user | POST /sobjects/User/ | 201 with the new record id |
| Update a user | PATCH /sobjects/User/{userId} | 204 with an empty body |
| Upsert by external id | PATCH /sobjects/User/{extIdField}/{value} | 201 created or 204 updated |
| Deactivate a user | PATCH /sobjects/User/{userId} with IsActive false | 204 with an empty body |
| Delete a user | Not supported | Salesforce returns an error |
| Describe available fields | GET /sobjects/User/describe | 200 with the field metadata |
There is no standard REST collection endpoint that pages through users. Listing users means running SOQL through the query endpoint and following the nextRecordsUrl value that comes back when the result set exceeds the batch size.
The 9 required fields to create a Salesforce user
A POST to the User object fails unless all 9 of these fields are present. Salesforce returns a single generic REQUIRED_FIELD_MISSING error rather than naming every field you left out, which is why most first attempts fail more than once.
| Field | What it holds | Constraint that catches people out |
|---|---|---|
| Username | The login identifier | Must be unique across every Salesforce org worldwide, not just yours, and must be formatted like an email address |
| LastName | Surname | FirstName is optional, LastName is not |
| Contact address | Can duplicate another user's email, unlike Username | |
| Alias | Short display name | Maximum 8 characters, truncate before you send |
| ProfileId | The profile to assign | An 18 character record id, so query Profile first to resolve a name to an id |
| TimeZoneSidKey | Time zone | A Salesforce key such as America/New_York, not an offset |
| LocaleSidKey | Number and date format | A key such as en_US |
| LanguageLocaleKey | Display language | A key such as en_US, separate from LocaleSidKey |
| EmailEncodingKey | Outbound mail encoding | UTF-8 in almost every case |
Creating a user consumes a license seat the moment the record is written. If the org has no free seat on the profile's licence type, the call fails on licensing rather than on validation.
Example create request body
POST /services/data/v67.0/sobjects/User/
{ "Username": "[email protected]", "LastName": "Reyes", "FirstName": "Dana", "Email": "[email protected]", "Alias": "dreyes", "ProfileId": "00e5f000000XXXXAAA", "TimeZoneSidKey": "America/New_York", "LocaleSidKey": "en_US", "LanguageLocaleKey": "en_US", "EmailEncodingKey": "UTF-8" }
A common production pattern is to suffix the Username with the org type, as in .prod or .sandbox, because sandbox refreshes rewrite usernames and a collision with a live org username blocks the create.
Salesforce applies the same validation and security rules as the Salesforce UI.
Can You Create Salesforce Users Using REST API?
Yes. Salesforce allows user creation through REST API.
To create a user, you must provide all required fields such as username, email, profile ID, locale, and time zone. Salesforce also checks license availability and permissions automatically.
If any required field is missing or invalid, the API request will fail.
Can You Delete Salesforce Users Using REST API?
No. Salesforce does not allow permanent deletion of users through REST API.
Users can only be deactivated. This preserves audit history, data ownership, and compliance requirements.
Deactivation is a single PATCH that sets IsActive to false. It frees the licence seat immediately. Existing OAuth access tokens for that user are not revoked by the deactivation itself, so an integration that needs an immediate cutoff should revoke the tokens as a separate step.
Why a deactivation call fails
Salesforce blocks deactivation while the user still owns certain records or sits in certain configurations. Each one returns an error that names the blocker, and each has to be cleared before the PATCH succeeds.
| Blocker | How to clear it |
|---|---|
| User is the default owner of leads or cases | Reassign the default owner in the relevant assignment or escalation rule |
| User is an approver in an active approval process | Replace the approver, or deactivate the approval process |
| User is selected in a workflow email alert or custom field default | Point the alert or default at another user |
| User is the recipient in an active assignment rule | Edit the rule to name a different recipient |
| User owns records in a queue-driven process | Transfer ownership before deactivating |
If you need the seat back but cannot clear the blockers yet, freezing the user is the intermediate step. Freezing stops login immediately but does not release the licence, so it is a stopgap and not a substitute for deactivation.
Authentication and Permissions Explained Simply
All Salesforce REST API calls require OAuth authentication.
The user making the API request must have the API Enabled permission. In production environments, Salesforce recommends using a dedicated integration user with limited access.
Reading user records needs API Enabled. Creating, updating, and deactivating them needs Manage Users as well, which is an administrative permission. Granting Manage Users to an integration user hands it the ability to change profiles and reset access across the org, so scope it deliberately and audit it.
This approach improves security and simplifies monitoring.
When Should You Use Apex REST Instead?
Standard REST API is ideal for basic user management tasks such as onboarding automation and user synchronization.
If you need custom business logic, conditional validation, or multi-step workflows during user creation or updates, Apex REST is a better choice. Apex REST allows you to add logic while still exposing a REST endpoint.
API limits that break user provisioning jobs
User provisioning is usually a batch operation, and batch operations are where orgs hit their ceiling. Three limits matter.
| Limit | What it means in practice |
|---|---|
| Daily API request allocation | Counted on a rolling 24 hour window, not a calendar day, and shared by every integration in the org. Check the current number against Setup, System Overview rather than assuming a figure. |
| Concurrent long-running requests | Requests that run longer than 20 seconds are capped at 25 at once in production. Parallel provisioning threads are the usual cause of hitting it. |
| SOQL OFFSET ceiling | OFFSET stops at 2,000 rows. Paging through a large user list with OFFSET silently stops working, so follow nextRecordsUrl instead. |
REST API is built for single records and small batches. For anything past about 2,000 user records in one run, Bulk API 2.0 is the supported path and it draws on a separate allocation.
SCIM versus REST API for user provisioning
Salesforce supports SCIM 2.0 as well as the REST API, and they solve different problems. Pick on whether an identity provider owns the lifecycle.
| REST API on the User object | SCIM 2.0 | |
|---|---|---|
| Best for | Custom provisioning logic inside your own product | Standard joiner, mover, leaver flows driven by an IdP |
| Who usually drives it | Your application or middleware | Okta, Entra ID, or a similar identity provider |
| Schema | Salesforce User fields | A standard SCIM schema mapped onto Salesforce fields |
| Flexibility | Full access to every User field | Limited to the mapped SCIM attributes |
| Effort to build | Higher, you write the calls | Lower, the IdP connector does the work |
If an identity provider already owns onboarding and offboarding, SCIM removes most of this work. If user records are created as a side effect of something happening inside your own product, REST API is the right tool.
Which API version to call
The current version is 67.0, shipped with Summer '26. Salesforce has announced the retirement of versions 31.0 through 40.0, with calls to those versions failing from Summer '28, so any integration still pinned below 41.0 needs a version bump on the roadmap.
Pin the version in the path rather than tracking the newest release. Salesforce guarantees a minimum support window per version, and an unpinned integration inherits behaviour changes without a deploy. Version 67.0 in particular changed the Apex default to user mode, which matters if your user provisioning runs through Apex rather than straight REST calls.
Best Practices for Salesforce User Management via REST API
The practices below keep a user-provisioning integration stable once it is running against a production org with real license limits.
These practices help keep your integration stable and compliant.
Summary
Salesforce User Management REST API allows you to query, create, update, and deactivate users using Salesforce's standard REST API. User deletion is not supported. Official documentation includes the REST API overview and the User object reference. Authentication is handled using OAuth, and permissions are enforced the same way as in the Salesforce UI.
Choosing the right approach
Salesforce REST API provides a reliable and supported way to manage users programmatically. By focusing on the User object and following Salesforce's security model, teams can automate user management without risking compliance or stability.
Frequently asked questions
Can you delete a Salesforce user through the REST API?
No. The User object does not support the delete operation through any API. Deactivation, done by setting IsActive to false, is the supported way to remove access, and it preserves the audit trail and record ownership history that compliance reviews depend on.
What are the required fields to create a Salesforce user via API?
Nine: Username, LastName, Email, Alias, ProfileId, TimeZoneSidKey, LocaleSidKey, LanguageLocaleKey, and EmailEncodingKey. Username has to be globally unique across all Salesforce orgs and formatted like an email address, and Alias is capped at 8 characters.
How do you query all users with the Salesforce REST API?
Send a GET to the query endpoint with a SOQL statement, for example SELECT Id, Username, IsActive FROM User. There is no REST collection endpoint for users. When the result set is larger than one batch, the response carries a nextRecordsUrl value that you follow to get the next page. Do not page with OFFSET, which stops working past 2,000 rows.
Why does my Salesforce user deactivation fail?
Almost always because the user is still referenced somewhere active: a default lead or case owner, an approval process approver, a workflow email alert recipient, or an assignment rule. Salesforce names the blocker in the error. Clear the reference, then repeat the PATCH.
What permission does an integration user need to manage users?
API Enabled to make any call, plus Manage Users to create, update, or deactivate user records. Manage Users is a powerful administrative permission, so it belongs on a dedicated integration user with a tightly scoped profile rather than on a shared account.
Should I use REST API or SCIM to provision Salesforce users?
Use SCIM when an identity provider such as Okta or Entra ID owns the joiner, mover, leaver process, because the connector does the work. Use the REST API when user records need to be created by logic inside your own application, or when you need access to User fields that the SCIM mapping does not expose.
Does creating a user through the API consume a licence?
Yes, immediately on creation, based on the licence type tied to the assigned profile. If no seat is free the call fails on licensing rather than validation. Deactivating a user releases the seat straight away, freezing one does not.
When should I use Apex REST instead of the standard REST API?
When user creation or update has to run multi-step business logic, conditional validation, or work across several objects in one transaction. Apex REST wraps that logic behind a single endpoint. For plain create, update, and deactivate calls the standard REST API is less code and less to maintain.
This makes Salesforce REST API a practical solution for modern user lifecycle automation.
