Users

Users are the team members who sign in to your SMBcrm account. Each user has a role, a list of locations they can access, and a set of permissions. You need a user’s ID whenever another endpoint asks which person owns a record: assignedTo on contacts and opportunities, and userId on social posts and conversations. Search the users to find those IDs.

Base URL: https://services.smbcrm.com · Version header: v3 · Scopes: users.readonly (search and retrieve), users.write (create, update, delete). See Scopes.

Writes change who can sign in

Creating, updating, and deleting users change who can sign in to your account and what they can do. Grant users.write only to integrations that manage team members.

Search users

GET/users/search

Search the users in a company by name, email, or phone, with filters and pagination.

scope users.readonlyauth Location token or PIT

companyId is required. Take it from the companyId field of the location record returned by Get your location, or from the companyId in the OAuth token response. Add locationId to search a single location.

Parameter	Type	Required	Description
companyId	string	Yes	ID of the company to search in.
query	string	No	Search term. It matches the user’s full name, email, or phone.
locationId	string	No	Limit the search to one location.
type	string	No	Filter by account type, for example account.
role	string	No	Filter by role, for example admin.
ids	string	No	Comma-separated user IDs to return.
skip	string	No	Number of results to skip. Default 0.
limit	string	No	Maximum number of results to return. Default 25.
sort	string	No	Field to sort by, for example dateAdded. The default order is first name, then last name.
sortDirection	string	No	Sort direction, for example asc.
enabled2waySync	boolean	No	Filter users by whether 2-way sync is enabled.

curl "https://services.smbcrm.com/users/search?companyId=<company_id>&locationId=<location_id>&query=avery&limit=25" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "users": [
    {
      "id": "<user_id>",
      "name": "Avery Chen",
      "firstName": "Avery",
      "lastName": "Chen",
      "email": "avery@example.com",
      "phone": "+15125550142",
      "extension": "",
      "permissions": {
        "campaignsEnabled": true,
        "campaignsReadOnly": false,
        "contactsEnabled": true,
        "workflowsEnabled": true
      },
      "scopes": ["contacts.write", "campaigns.readonly"],
      "roles": {
        "type": "account",
        "role": "admin",
        "locationIds": ["<location_id>"],
        "restrictSubAccount": true
      },
      "deleted": false,
      "lcPhone": { "<location_id>": "+15125550143" },
      "platformLanguage": "en_US"
    }
  ],
  "count": 1
}

count is the total number of users that match the search, not the number in this page. To read the next page, add limit to skip and repeat until skip reaches count. Each user has the fields described in The user object.

Retrieve a user

GET/users/{userId}

Fetch a single user by ID.

scope users.readonlyauth Location token or PIT

Parameter	Type	Required	Description
userId	string	Yes	ID of the user, in the path.

curl https://services.smbcrm.com/users/<user_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

The response is the user object itself, with no wrapper.

200 OK

{
  "id": "<user_id>",
  "name": "Avery Chen",
  "firstName": "Avery",
  "lastName": "Chen",
  "email": "avery@example.com",
  "phone": "+15125550142",
  "extension": "",
  "permissions": {
    "campaignsEnabled": true,
    "campaignsReadOnly": false,
    "contactsEnabled": true,
    "workflowsEnabled": true
  },
  "scopes": ["contacts.write", "campaigns.readonly"],
  "roles": {
    "type": "account",
    "role": "admin",
    "locationIds": ["<location_id>"],
    "restrictSubAccount": true
  },
  "lcPhone": { "<location_id>": "+15125550143" },
  "platformLanguage": "en_US"
}

The user object

Search, retrieve, create, and update all return users in this shape. The examples on this page show only some of the permissions fields.

Field	Description
id	The user’s ID. Send it as assignedTo or userId on other endpoints.
name	Full name.
firstName	First name.
lastName	Last name.
email	Email address.
phone	Phone number.
extension	Phone extension.
permissions	Feature switches for the user. The fields are listed under Permissions.
scopes	The scopes granted to the user. See Scopes.
roles.type	Account type. account for a Sub-Account user.
roles.role	admin or user.
roles.locationIds	Array of the location IDs the user can access.
roles.restrictSubAccount	Boolean. Whether the user is restricted to specific Sub-Accounts only.
lcPhone	Inbound phone numbers from the SMBcrm phone system, keyed by location ID.
platformLanguage	Language the user sees in the app: en_US, es, fr_CA, fr_FR, nl, de, pt_PT, pt_BR, it, sv, da, fi, or no.
deleted	Search results only. Whether the user has been deleted.

Create a user

POST/users/

Create a user and give them access to one or more locations.

scope users.writeauth Location token or PIT

companyId, firstName, lastName, email, password, type, role, and locationIds are required. Send any subset of the others.

Field	Type	Required	Description
companyId	string	Yes	ID of the company to add the user to. Find it as described under Search users.
firstName	string	Yes	First name.
lastName	string	Yes	Last name.
email	string	Yes	Email address. The user signs in with it.
password	string	Yes	Password for the account. It needs at least 12 characters, including one uppercase letter, one lowercase letter, one number, and one special character such as !, @, #, or $.
phone	string	No	Phone number in E.164 format, for example +15125550142.
type	string	Yes	Account type. Use account for a Sub-Account user.
role	string	Yes	admin or user.
locationIds	array of strings	Yes	IDs of the locations the user can access.
permissions	object	No	Feature switches for the user. See Permissions.
scopes	array of strings	No	Scopes to enable for the user. See Scopes.
scopesAssignedToOnly	array of strings	No	Assigned scopes for the user. It takes the same values as scopes.
profilePhoto	string	No	URL of the user’s profile photo.
twilioPhone	object	No	Inbound number for calls and voicemail, for locations that use your own Twilio account. Keys are location IDs and values are phone numbers in E.164 format.
platformLanguage	string	No	Language the user sees in the app. One of the values listed in The user object.

curl -X POST https://services.smbcrm.com/users/ \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "<company_id>",
    "firstName": "Avery",
    "lastName": "Chen",
    "email": "avery@example.com",
    "password": "<password>",
    "phone": "+15125550142",
    "type": "account",
    "role": "user",
    "locationIds": ["<location_id>"],
    "permissions": {
      "contactsEnabled": true,
      "campaignsEnabled": true,
      "campaignsReadOnly": true,
      "workflowsEnabled": false
    },
    "scopes": ["contacts.write", "campaigns.readonly"]
  }'

201 Created

{
  "id": "<user_id>",
  "name": "Avery Chen",
  "firstName": "Avery",
  "lastName": "Chen",
  "email": "avery@example.com",
  "phone": "+15125550142",
  "extension": "",
  "permissions": {
    "campaignsEnabled": true,
    "campaignsReadOnly": true,
    "contactsEnabled": true,
    "workflowsEnabled": false
  },
  "scopes": ["contacts.write", "campaigns.readonly"],
  "roles": {
    "type": "account",
    "role": "user",
    "locationIds": ["<location_id>"]
  },
  "platformLanguage": "en_US"
}

Permissions

permissions is an object of boolean switches. A switch you leave out takes its default.

Field	Default	What it controls
campaignsEnabled	true	Access to campaigns.
campaignsReadOnly	false	Read-only mode for campaigns.
contactsEnabled	true	Access to contacts.
workflowsEnabled	true	Access to workflows.
workflowsReadOnly	false	Read-only mode for workflows.
triggersEnabled	true	Access to triggers.
funnelsEnabled	true	Access to funnels.
websitesEnabled	false	Access to websites.
opportunitiesEnabled	true	Access to opportunities.
dashboardStatsEnabled	true	Dashboard statistics.
bulkRequestsEnabled	true	Bulk requests.
appointmentsEnabled	true	Access to appointments.
reviewsEnabled	true	Access to reviews.
onlineListingsEnabled	true	Access to online listings.
phoneCallEnabled	true	Phone calls.
conversationsEnabled	true	Access to conversations.
assignedDataOnly	false	Limits the user to data assigned to them.
adwordsReportingEnabled	false	AdWords reporting.
membershipEnabled	false	Membership features.
facebookAdsReportingEnabled	false	Facebook Ads reporting.
attributionsReportingEnabled	false	Attributions reporting.
settingsEnabled	true	Access to settings.
tagsEnabled	true	Access to tags.
leadValueEnabled	true	Lead value features.
marketingEnabled	true	Marketing features.
agentReportingEnabled	true	Agent reporting.
botService	false	The bot service.
socialPlanner	true	Access to the social planner.
bloggingEnabled	true	Blogging.
invoiceEnabled	true	Invoices.
affiliateManagerEnabled	true	The affiliate manager.
contentAiEnabled	true	Content AI.
refundsEnabled	true	Issuing refunds.
recordPaymentEnabled	true	Recording payments.
cancelSubscriptionEnabled	true	Cancelling subscriptions.
paymentsEnabled	true	Payments.
communitiesEnabled	true	Communities.
exportPaymentsEnabled	true	Exporting payments.

Scopes

scopes and scopesAssignedToOnly are arrays of scope names such as contacts.write, campaigns.readonly, workflows.readonly, calendars.write, conversations.readonly, opportunities.write, invoices.readonly, and medias.write. These are the scopes granted to the user, not the scopes on your token. When you send either array, only the scopes in it are enabled, and an empty array disables all of them.

Update a user

Some fields replace what is stored

Sending scopes or scopesAssignedToOnly enables only the scopes in the array you send. An empty array disables all of them.

Sending twilioPhone replaces the stored numbers with the object you send, so any location you leave out loses its number. Omit the field to leave the numbers unchanged. Send {} to clear every number, or set one location ID to "" to clear only that location.

PUT/users/{userId}

Update a user's details, role, locations, permissions, or scopes.

scope users.writeauth Location token or PIT

The userId in the path is the user to update. Send only the body fields you want to change. All of them are optional.

Field	Type	Required	Description
firstName	string	No	First name.
lastName	string	No	Last name.
email	string	No	Deprecated. Email updates are no longer supported for security reasons.
password	string	No	New password. It follows the same rules as on create.
phone	string	No	Phone number in E.164 format.
type	string	No	Account type. Use account for a Sub-Account user.
role	string	No	admin or user.
companyId	string	No	ID of the company. You don’t need it with a Sub-Account token.
locationIds	array of strings	No	IDs of the locations the user can access.
permissions	object	No	Feature switches for the user. See Permissions.
scopes	array of strings	No	Scopes to enable for the user. See Scopes.
scopesAssignedToOnly	array of strings	No	Assigned scopes for the user. It takes the same values as scopes.
profilePhoto	string	No	URL of the user’s profile photo.
twilioPhone	object	No	Inbound number for calls and voicemail, keyed by location ID, with phone numbers in E.164 format.
platformLanguage	string	No	Language the user sees in the app. One of the values listed in The user object.

curl -X PUT https://services.smbcrm.com/users/<user_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Avery",
    "lastName": "Chen",
    "phone": "+15125550199",
    "platformLanguage": "es"
  }'

200 OK

{
  "id": "<user_id>",
  "name": "Avery Chen",
  "firstName": "Avery",
  "lastName": "Chen",
  "email": "avery@example.com",
  "phone": "+15125550199",
  "extension": "",
  "scopes": ["contacts.write", "campaigns.readonly"],
  "roles": {
    "type": "account",
    "role": "user",
    "locationIds": ["<location_id>"]
  },
  "platformLanguage": "es"
}

Delete a user

DELETE/users/{userId}

Delete a user.

scope users.writeauth Location token or PIT

Parameter	Type	Required	Description
userId	string	Yes	ID of the user, in the path.

curl -X DELETE https://services.smbcrm.com/users/<user_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

The request is queued and takes effect in a few minutes. succeeded is true when the deletion was queued.

200 OK

{
  "succeeded": true,
  "message": "Queued deleting user with e-mail avery@example.com and name Avery Chen. Will take effect in a few minutes."
}

Related

• Contacts. assignedTo and followers take user IDs.
• Opportunities & Pipelines. assignedTo and followers take user IDs.
• Conversations & Messages. Filter by the user a conversation is assigned to.
• Social Planner. A post takes the userId of the user creating it.
• Locations. Get the companyId for user search, and filter tasks by user.
• Scopes. The scopes your token needs for each endpoint.