Insightly User Management API Guide

Auth method: HTTP Basic Auth (API key as username, empty password)

Setup steps

1. Log in to Insightly and navigate to User Settings (avatar menu > User Settings).
2. Scroll to the 'API Key' section and copy your personal API key.
3. Encode the API key using Base64 (key + ':' with empty password, e.g., base64('YOUR_API_KEY:')).
4. Include the header: Authorization: Basic on every request.
5. Alternatively, pass the API key directly as the HTTP Basic Auth username with a blank password using standard HTTP client libraries.

List all users

• Method: GET
• URL: https://api.insightly.com/v3.1/Users
• Watch out for: Returns all users including inactive ones. Filter client-side on ACTIVE field. Max 500 records per page; use $skip and $top for pagination.

Request example

GET /v3.1/Users HTTP/1.1
Host: api.insightly.com
Authorization: Basic <base64key>

Response example

[
  {
    "USER_ID": 12345,
    "FIRST_NAME": "Jane",
    "LAST_NAME": "Doe",
    "EMAIL_ADDRESS": "jane@example.com",
    "ACTIVE": true,
    "ADMINISTRATOR": false
  }
]

Get a single user by ID

• Method: GET
• URL: https://api.insightly.com/v3.1/Users/{id}
• Watch out for: Returns HTTP 404 if user does not exist or is not accessible with the calling API key's permissions.

Request example

GET /v3.1/Users/12345 HTTP/1.1
Host: api.insightly.com
Authorization: Basic <base64key>

Response example

{
  "USER_ID": 12345,
  "FIRST_NAME": "Jane",
  "LAST_NAME": "Doe",
  "EMAIL_ADDRESS": "jane@example.com",
  "ACTIVE": true,
  "ADMINISTRATOR": false
}

Get the current authenticated user (Me)

• Method: GET
• URL: https://api.insightly.com/v3.1/Users/Me
• Watch out for: Useful for validating API key and retrieving the calling user's USER_ID without knowing it in advance.

Request example

GET /v3.1/Users/Me HTTP/1.1
Host: api.insightly.com
Authorization: Basic <base64key>

Response example

{
  "USER_ID": 12345,
  "FIRST_NAME": "Jane",
  "EMAIL_ADDRESS": "jane@example.com",
  "ADMINISTRATOR": true
}

Create a new user

• Method: POST
• URL: https://api.insightly.com/v3.1/Users
• Watch out for: Only administrators can create users. Creating a user consumes a paid seat. An invitation email is sent automatically to the new user's email address.

Request example

POST /v3.1/Users HTTP/1.1
Authorization: Basic <base64key>
Content-Type: application/json

{"FIRST_NAME":"John","LAST_NAME":"Smith","EMAIL_ADDRESS":"john@example.com","ADMINISTRATOR":false,"ACTIVE":true}

Response example

{
  "USER_ID": 67890,
  "FIRST_NAME": "John",
  "LAST_NAME": "Smith",
  "EMAIL_ADDRESS": "john@example.com",
  "ACTIVE": true
}

Update an existing user

• Method: PUT
• URL: https://api.insightly.com/v3.1/Users
• Watch out for: Uses PUT (full update semantics) with USER_ID in the body, not the URL path. Omitting fields may reset them; send the full user object to avoid data loss.

Request example

PUT /v3.1/Users HTTP/1.1
Authorization: Basic <base64key>
Content-Type: application/json

{"USER_ID":67890,"FIRST_NAME":"John","LAST_NAME":"Smith","ACTIVE":false}

Response example

{
  "USER_ID": 67890,
  "FIRST_NAME": "John",
  "ACTIVE": false
}

Delete a user

• Method: DELETE
• URL: https://api.insightly.com/v3.1/Users/{id}
• Watch out for: Deleting a user is irreversible via API. Consider setting ACTIVE=false instead to deactivate without permanent deletion. Only admins can delete users.

Request example

DELETE /v3.1/Users/67890 HTTP/1.1
Host: api.insightly.com
Authorization: Basic <base64key>

Response example

HTTP/1.1 202 Accepted

List users with OData filtering

• Method: GET
• URL: https://api.insightly.com/v3.1/Users?$filter=ACTIVE+eq+true&$top=100&$skip=0
• Watch out for: Insightly supports a subset of OData query parameters ($filter, $top, $skip, $orderby). Not all OData operators are supported; test filters carefully.

Request example

GET /v3.1/Users?$filter=ACTIVE+eq+true&$top=100&$skip=0 HTTP/1.1
Authorization: Basic <base64key>

Response example

[
  {"USER_ID":12345,"ACTIVE":true,"EMAIL_ADDRESS":"jane@example.com"}
]

Get all permission profiles

• Method: GET
• URL: https://api.insightly.com/v3.1/Permissions/Profiles
• Watch out for: Required to resolve PROFILE_ID values when creating or updating users with specific permission profiles.

Request example

GET /v3.1/Permissions/Profiles HTTP/1.1
Authorization: Basic <base64key>

Response example

[
  {"PROFILE_ID": 1, "PROFILE_NAME": "Standard User"},
  {"PROFILE_ID": 2, "PROFILE_NAME": "Read Only"}
]

• Rate limits: Rate limits are enforced per API key and vary by plan. Requests exceeding the limit return HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: Exact daily request quotas per plan are not publicly documented in detail. The API returns HTTP 429 when limits are exceeded. Insightly recommends implementing exponential backoff. Rate limit headers are present in responses.
• Pagination method: offset
• Default page size: 500
• Max page size: 500
• Pagination pointer: skip / top

• Webhooks available: No
• Webhook notes: Insightly does not offer native outbound webhooks for user management events (user created, deactivated, deleted) as of the current documentation. Workflow automation within Insightly is focused on CRM record events (contacts, leads, opportunities), not user account lifecycle events.
• Alternative event strategy: Poll GET /v3.1/Users on a schedule to detect changes, or use SCIM provisioning (Enterprise) for IdP-driven lifecycle events.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise ($99/user/month, billed annually)

• Endpoint: https://api.insightly.com/scim/v2

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

Limitations:

• Requires Enterprise plan; not available on Plus or Professional.
• SSO must be configured as a prerequisite before enabling SCIM.
• Supported IdPs include Okta, Microsoft Entra ID (Azure AD), Google Workspace, and OneLogin.
• Group/team provisioning support via SCIM is not explicitly documented; verify with Insightly support.
• SCIM bearer token is separate from the REST API key and is generated in the SSO/SCIM settings page.

Three automation scenarios are well-supported by the current API surface. To provision a new employee, call GET /v3.

1/Permissions/Profiles to resolve available PROFILE_ID values, then POST /v3. 1/Users with the required fields; an invitation email fires automatically and cannot be suppressed.

To deactivate a departing employee without destroying CRM history, fetch the full user object via GET /v3. 1/Users/{id}, set ACTIVE=false, and submit the complete object via PUT /v3.

1/Users - partial updates are not supported on the v3. 1 REST API (no PATCH for users), so omitting fields risks silent data loss.

For IdP-driven lifecycle automation at Enterprise tier, SCIM 2. 0 is available at https://api.insightly.com/scim/v2 with a separately generated bearer token distinct from the REST API key; supported IdPs include Okta, Microsoft Entra ID, Google Workspace, and OneLogin, and SSO must be active before SCIM can be enabled.

Provision a new employee and assign a permission profile

1. GET /v3.1/Permissions/Profiles to retrieve available PROFILE_IDs and their names.
2. POST /v3.1/Users with FIRST_NAME, LAST_NAME, EMAIL_ADDRESS, ACTIVE=true, ADMINISTRATOR=false, and the desired PROFILE_ID.
3. Capture the returned USER_ID for future reference.
4. User receives an automatic invitation email; no additional step needed to trigger onboarding.

Watch out for: The invitation email cannot be suppressed via API. If the email address already exists in the system, the POST will fail with a conflict error.

Deactivate a departing employee without deleting their records

1. GET /v3.1/Users to find the user's USER_ID by EMAIL_ADDRESS.
2. GET /v3.1/Users/{id} to retrieve the full current user object.
3. PUT /v3.1/Users with the full user object, setting ACTIVE=false.
4. Verify the response confirms ACTIVE=false.

Watch out for: PUT requires the complete user object. Fetching the current state first prevents accidental field resets. Deactivated users retain their CRM data and history.

Automate user lifecycle via SCIM with Okta (Enterprise)

1. Ensure SSO is configured in Insightly System Settings (prerequisite for SCIM).
2. Navigate to System Settings > SSO & SCIM in Insightly and generate a SCIM bearer token.
3. In Okta, add the Insightly app from the Okta Integration Network and configure SCIM provisioning with the base URL https://api.insightly.com/scim/v2 and the bearer token.
4. Enable Provisioning features in Okta: Push New Users, Push Profile Updates, Deactivate Users.
5. Assign users or groups in Okta to trigger automatic provisioning to Insightly.

Watch out for: SCIM is only available on the Enterprise plan. The SCIM token is separate from the REST API key. SSO must be active before SCIM can be enabled; disabling SSO will break SCIM provisioning.

Several non-obvious behaviors create integration risk. The DELETE /v3.1/Users/{id} endpoint performs an irreversible hard delete; prefer setting ACTIVE=false via PUT to preserve audit trails and CRM record ownership.

Rate limits are enforced per API key at 10 requests/second across all plans, but exact daily quotas are not publicly documented - implement exponential backoff on HTTP 429 unconditionally.

The GET /v3.1/Users endpoint returns both active and inactive users with no server-side active filter by default; client-side filtering on ACTIVE is required unless using OData (?$filter=ACTIVE+eq+true).

Finally, there are no native webhooks for user lifecycle events - user creation, deactivation, and deletion are not observable via push; polling GET /v3.1/Users on a schedule is the only REST-layer alternative to SCIM for event detection.