Skip to main content

Account

Accounts represent potential customers. The object contains information about the location and current status of the account.

📄️ Add Account

Creates a new account and returns the created object. Provide either a `locationId` or a `location` address, which is matched to a known location. Omit `ownerId` to make the authenticated user the owner. Depending on the company's duplicate account setting, the request may fail as a duplicate, return the existing account with `duplicate: true`, or create another account when duplicates are allowed. Requires the `account:add` permission. Use `/account/upsert` instead to sync records from an external system (it matches existing accounts and resolves users by email or clientUserId), and `/account/batch` to add, update, or remove up to 20 accounts in one request.

📄️ Batch Accounts

Processes a mixed batch of account add, update, and remove operations, up to 20 operations per request. Each operation behaves like `/account/add`, `/account/update`, or `/account/remove`, returns its own success or error result, and enforces its corresponding permission. A remove operation accepts the same optional `cascade` flag as `/account/remove`: by default an account with calendar events is not deleted and that operation returns an error, while `cascade: true` also permanently deletes the calendar events associated with the account, along with the event attachments and custom-field attachment files on the account. A failed cascade keeps that account and fails only its own operation. To delete notes on several accounts, send one `update` operation per account whose `account` holds the `accountId` and the note IDs in `deletedNotes`. Use this instead of repeated single calls when changing several specific accounts by ID. Use `/account/bulk` instead to change every account that matches a filter.

📄️ Get Account

Retrieves a single account by its `accountId`, including its workflow stage and action names, custom fields, and location. The response includes the account's `notes`, each with its `noteId`, author `userId`, `timestamp` (UTC milliseconds) and `text`. Notes with empty text are included, so use this to find notes to clean up; delete them with `deletedNotes` on `/account/update`, or `/account/batch` for several accounts. Callers with company-level `account:save` permission also receive `potentialDuplicates`. Returns an error if the caller is not allowed to view the account. Use `/account/match` instead when you only have an externalLeadId, sourceId, or address, `/account/list` to filter many accounts, and `/search` for free-text lookup by name or address.

📄️ List Accounts

Lists accounts visible to the authenticated user. Pass `searchInput` to filter by workflow, stage, action, team, user, tags, city, state, zip code, custom fields, polygon, or date range, or pass `nearby` to return accounts closest to a coordinate. With no filters, users with company-wide `account:list` access get all company accounts and other users get the accounts they own. Users without the `account:list` permission receive an empty list. `size` sets the page size (10–1000); pass the returned `sortTimestamp` inside `searchInput` to fetch the next page. `nearby` searches return no `sortTimestamp` and cannot be paged. Send the `sortTimestamp` array back unchanged: it holds the sort value and the account ID, so accounts that share a sort value, such as the same `createdDate`, are neither skipped nor repeated. A single sort value (legacy) is still accepted: the next page starts at the first account with that value, so accounts that share it can be repeated but are not skipped. Use `/account/get` for a single known account, `/account/match` to look up an account by external identifier or address, and `/search` for quick free-text search across accounts, users, teams, and more.

📄️ Match Account

Finds an existing account using a cascading match strategy. Tries each provided criterion in priority order — accountId, externalLeadId, sourceId, then address — and returns the first match found. A sourceId match uses sourceId alone. accountSource is not required and is not part of the key. When matching by address, additional accounts at the same location may also be returned. Only accounts the caller can view are returned, and the response has no `account` when nothing matches. Call this before `/account/add` to avoid creating duplicates, or use `/account/upsert` to match and write in one call. Use `/account/get` instead when you already have the accountId.

📄️ Remove Account

Permanently deletes an existing account. By default, accounts that have calendar events cannot be deleted. Set `cascade` to true to also permanently delete associated calendar events, along with the event attachments and custom-field attachment files on the account; notes stored on the account are removed with the account. Cascade deletion uses the same `account:manage` permission as ordinary account removal. Use `/account/batch` to remove several specific accounts, or `/account/bulk` with the `delete` action to remove every account matching a filter.

📄️ Roll Back Accounts

Moves accounts matching the filter back to the most recent rollback target stage in their history, or to the workflow's default rollback stage. Accounts already in a target or protected stage are skipped. Only the stage changes, and rolled back stages earn no new credit. Set dryRun to preview how many accounts would roll back to each stage, use the default stage, or be skipped, without changing anything. Rollback must be enabled on the workflow, the filter must include an area, team, or user, and the caller must hold one of the workflow's rollback roles on the teams that own the accounts. Only accounts the caller can list under `account:list` are selected, in both the preview and the run. Use `/account/bulk` with `updateStage` instead to move accounts to a specific stage.

📄️ Update Account

Partially updates an existing account by `accountId` and returns the updated object. Omitted fields keep their current values; set `ownerId` or `teamId` to `null` to clear them. `customFields` replaces the whole custom field map; use `customFieldsPatch` to set or clear (`null`) only the fields you name, keeping the rest, including fields you cannot view. `contacts` and `notes` are added or updated, and `deletedContacts` and `deletedNotes` remove entries by ID. To delete notes, read their `noteId`s from `/account/get` and send them in `deletedNotes` with the `accountId`; deleted notes cannot be restored. Use `/account/batch` to delete notes on several accounts. Set `workflowActionId` or `workflowStageId` to record a workflow action or move the account to a stage; actions restricted to specific roles require the caller to hold one of them. `actorId` may be a User ID, email, or clientUserId; omit it to attribute new workflow history to the authenticated user. The caller must be the account's owner or closer, or hold the `account:save` permission. Changing the owner, closer, or team also requires the `account:manage` permission. Use `/account/upsert` instead when you only have an external identifier, and `/account/batch` to update several accounts in one request.

📄️ Upsert Account

Creates or updates an account from an external system's data, such as a CRM or integration sync. An existing account is matched by `accountId`, `sourceId`, or `externalLeadId`, then by address; an address match on another user's account follows the company's duplicate account setting and may create a new account. The `owner` and `closer` are resolved to Terros users by userId, clientUserId, email, name, or phone. `actorId` may be a User ID, email, or clientUserId; omit it to attribute generated workflow history to the authenticated user. Use the 'requestType' field to control behavior: 'add' errors if the account already exists, 'update' errors if the account does not exist, and 'upsert' (default) creates or updates as needed. When an existing account is found by sourceId, that lookup uses sourceId alone. accountSource is not required and is not part of the key. Updating a matched account requires the same permissions as `/account/update`: the caller must be able to view the account and be its owner or closer, or hold the `account:save` permission. An omitted `teamId` keeps the account's team. Changing the owner, closer, or team also requires `account:manage`. A workflow action restricted to roles requires one of those roles. Creating an account requires the `account:add` permission, as `/account/add` does. Use `/account/add` or `/account/update` instead for direct edits when you have Terros IDs, and `/account/match` to look up an account without writing.