Zoho CRM User Management API Guide

Auth method: OAuth 2.0

Setup steps

1. Register a server-based or self-client application at https://api-console.zoho.com/.
2. Select the appropriate client type (Server-based Application for backend integrations).
3. Add required OAuth scopes (e.g., ZohoCRM.users.ALL) during app registration.
4. Generate an authorization URL and redirect the user to obtain an authorization code.
5. Exchange the authorization code for an access token and refresh token via POST to https://accounts.zoho.com/oauth/v2/token.
6. Use the access token in the Authorization header as 'Zoho-oauthtoken {access_token}' on all API requests.
7. Use the refresh token to obtain new access tokens before expiry (access tokens expire in 1 hour).

Required scopes

List Users

• Method: GET
• URL: https://www.zohoapis.com/crm/v7/users?type=AllUsers&page=1&per_page=200
• Watch out for: The 'type' parameter filters users: AllUsers, ActiveUsers, DeactiveUsers, ConfirmedUsers, NotConfirmedUsers, DeletedUsers, ActiveConfirmedUsers, AdminUsers, ActiveConfirmedAdmins, CurrentUser. Omitting it defaults to AllUsers.

Request example

GET /crm/v7/users?type=AllUsers&page=1&per_page=200
Authorization: Zoho-oauthtoken {access_token}

Response example

{
  "users": [
    {"id":"111","email":"user@example.com","status":"active","role":{"id":"r1","name":"Manager"}}
  ],
  "info": {"page":1,"per_page":200,"count":1,"more_records":false}
}

Get Single User

• Method: GET
• URL: https://www.zohoapis.com/crm/v7/users/{user_id}
• Watch out for: Response wraps single user in a 'users' array, not a single object.

Request example

GET /crm/v7/users/111
Authorization: Zoho-oauthtoken {access_token}

Response example

{
  "users": [
    {"id":"111","email":"user@example.com","first_name":"Jane","last_name":"Doe","status":"active"}
  ]
}

Get Current User

• Method: GET
• URL: https://www.zohoapis.com/crm/v7/users?type=CurrentUser
• Watch out for: Returns the user associated with the OAuth token in use.

Request example

GET /crm/v7/users?type=CurrentUser
Authorization: Zoho-oauthtoken {access_token}

Response example

{
  "users": [
    {"id":"222","email":"me@example.com","full_name":"John Smith"}
  ]
}

Create User

• Method: POST
• URL: https://www.zohoapis.com/crm/v7/users
• Watch out for: An invitation email is sent to the new user automatically. The user must accept the invite to activate. 'role' and 'profile' IDs are mandatory.

Request example

POST /crm/v7/users
Authorization: Zoho-oauthtoken {access_token}
Content-Type: application/json

{"users":[{"last_name":"Doe","email":"jane@example.com","role":{"id":"r1"},"profile":{"id":"p1"}}]}

Response example

{
  "users": [
    {"code":"SUCCESS","details":{"id":"333"},"message":"User added","status":"success"}
  ]
}

Update User

• Method: PUT
• URL: https://www.zohoapis.com/crm/v7/users/{user_id}
• Watch out for: Use PUT (not PATCH) for updates. The user ID must be included both in the URL path and in the request body.

Request example

PUT /crm/v7/users/333
Authorization: Zoho-oauthtoken {access_token}
Content-Type: application/json

{"users":[{"id":"333","mobile":"+1-555-0100","role":{"id":"r2"}}]}

Response example

{
  "users": [
    {"code":"SUCCESS","details":{"id":"333"},"message":"User updated","status":"success"}
  ]
}

Delete User

• Method: DELETE
• URL: https://www.zohoapis.com/crm/v7/users/{user_id}
• Watch out for: Deleting a user removes them from the CRM org. Records owned by the deleted user must be reassigned beforehand or they will be reassigned to the admin. Consider deactivating (status=inactive) instead of deleting to preserve data ownership.

Request example

DELETE /crm/v7/users/333
Authorization: Zoho-oauthtoken {access_token}

Response example

{
  "users": [
    {"code":"SUCCESS","details":{"id":"333"},"message":"User deleted","status":"success"}
  ]
}

Get Roles

• Method: GET
• URL: https://www.zohoapis.com/crm/v7/settings/roles
• Watch out for: Role IDs are required when creating or updating users. Retrieve them here before provisioning.

Request example

GET /crm/v7/settings/roles
Authorization: Zoho-oauthtoken {access_token}

Response example

{
  "roles": [
    {"id":"r1","name":"Manager","description":"Sales Manager role"}
  ]
}

Get Profiles

• Method: GET
• URL: https://www.zohoapis.com/crm/v7/settings/profiles
• Watch out for: Profile IDs are required when creating or updating users. Retrieve them here before provisioning.

Request example

GET /crm/v7/settings/profiles
Authorization: Zoho-oauthtoken {access_token}

Response example

{
  "profiles": [
    {"id":"p1","name":"Administrator","description":"Full access profile"}
  ]
}

• Rate limits: Zoho CRM API rate limits are based on the organization's plan and the number of licensed users. Limits apply per organization per day (API credits) and per 5-minute window.
• Rate-limit headers: Unknown
• Retry-After header: Unknown
• Rate-limit notes: Each API call consumes a variable number of credits depending on the operation. Bulk operations consume more credits. The exact per-minute concurrency limits are not explicitly published in official docs. Exceeding limits returns HTTP 429.
• Pagination method: offset
• Default page size: 200
• Max page size: 200
• Pagination pointer: page, per_page

• Webhooks available: Yes
• Webhook notes: Zoho CRM supports webhooks (called 'Notifications' in the API) that can be triggered by record-level events. However, native webhook events for user lifecycle changes (user created, user deactivated) are not documented as supported triggers. Webhooks are primarily for CRM record events (Leads, Contacts, Deals, etc.).
• Alternative event strategy: Poll GET /crm/v7/users periodically to detect user changes, or use Zoho Directory SCIM provisioning events via your IdP (Okta, Azure AD) for user lifecycle automation.
• Webhook events: record.create (for CRM modules like Leads, Contacts, Deals), record.update, record.delete

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (or Zoho One); requires Zoho Directory and SAML SSO to be configured

• Endpoint: SCIM endpoint is provisioned per IdP integration via Zoho Directory (e.g., https://directory.zoho.com/scim/v2/). The exact tenant-specific URL is generated within the Zoho Directory admin console when configuring an IdP connector.

• Supported operations: Create user (POST /Users), Update user (PUT /Users/{id}), Deactivate user (PATCH /Users/{id} with active=false), List users (GET /Users), Get user (GET /Users/{id})

Limitations:

• SCIM provisioning is managed through Zoho Directory, not directly through the Zoho CRM API.
• Requires SAML SSO to be configured as a prerequisite.
• Available on Enterprise plan or Zoho One; not available on Standard or Professional CRM plans.
• SCIM endpoint URL is IdP-specific and generated in the Zoho Directory admin console; it is not a static public endpoint.
• Group/role provisioning support via SCIM may be limited depending on the IdP connector used.
• Okta and Azure AD (Entra ID) are documented as supported IdPs; other IdPs may have limited support.

Three provisioning scenarios cover the primary lifecycle needs.

For onboarding, fetch role and profile IDs from /settings/roles and /settings/profiles first - both are mandatory on POST /users and cannot be inferred.

The API sends an invitation email automatically on user creation with no suppression option;

poll GET /users/{id} and check the confirm field to detect when the user has activated.

For offboarding, PUT /users/{user_id} with status set to inactive is the recommended path;

deletion via DELETE is irreversible and will reassign owned records to the org admin if not pre-transferred.

For directory sync, pagination is offset-based with a maximum page size of 200;

loop on info.more_records and use modified_time as a delta filter to minimize redundant data transfer across sync runs.

Provision a new CRM user on employee onboarding

1. Authenticate via OAuth 2.0 and obtain an access token with ZohoCRM.users.CREATE and ZohoCRM.settings.roles.READ and ZohoCRM.settings.profiles.READ scopes.
2. GET /crm/v7/settings/roles to retrieve available role IDs and identify the correct role for the new user.
3. GET /crm/v7/settings/profiles to retrieve available profile IDs and identify the correct permission profile.
4. POST /crm/v7/users with the user's last_name, email, role.id, and profile.id in the request body.
5. Store the returned user ID from the response for future updates.
6. Inform the new user to check their email and accept the CRM invitation to activate their account.

Watch out for: The user will not be active until they accept the invitation email. Poll GET /crm/v7/users/{id} and check 'confirm' field to verify activation status.

Deactivate a user on offboarding

1. Authenticate via OAuth 2.0 with ZohoCRM.users.UPDATE scope.
2. GET /crm/v7/users?type=ActiveUsers to find the user's ID by email if not already stored.
3. PUT /crm/v7/users/{user_id} with body {"users":[{"id":"{user_id}","status":"inactive"}]} to deactivate the user.
4. Verify the response returns code: SUCCESS.
5. Optionally reassign the deactivated user's records to another active user via the CRM record transfer API.

Watch out for: Deactivation preserves the user record and their owned records. Deletion is permanent and may cause data ownership issues if records are not reassigned first.

Sync CRM users to an external directory

1. Authenticate via OAuth 2.0 with ZohoCRM.users.READ scope.
2. GET /crm/v7/users?type=AllUsers&page=1&per_page=200 to retrieve the first page of users.
3. Check response info.more_records; if true, increment page parameter and repeat until more_records is false.
4. For each user, extract id, email, first_name, last_name, status, role, profile, and modified_time.
5. Compare modified_time against your last sync timestamp to identify changed records.
6. Update your external directory with the delta changes.

Watch out for: There is no native change-event webhook for user objects. Full or delta polling is required. Store modified_time from each sync to minimize data transfer on subsequent runs.

There is no native webhook for user lifecycle events - user.created and user.deactivated are not supported notification triggers. Webhooks in Zoho CRM fire on CRM record events (Leads, Contacts, Deals), not on user object changes, so any identity graph or downstream sync that needs real-time user state must rely on polling.

Bulk user creation is not supported; every user requires an individual POST, which compounds API credit consumption on large provisioning runs. Daily credit limits are plan-tiered (up to 5,000 credits/day on Enterprise) and per-minute concurrency limits are not published, making it difficult to safely size burst provisioning jobs.

SCIM provisioning is a separate system entirely - it runs through Zoho Directory, not the CRM REST API, requires SAML SSO as a prerequisite, and is only available on Enterprise or Zoho One; the SCIM endpoint URL is tenant-specific and generated inside the Zoho Directory admin console, not a static public address.