Migrating to accounts with the Plain API

Updated 4 Nov 2026 by Juan

In this article group

Accounts replace companies in the Plain API, and they are the new name for tenants. This article lists the GraphQL fields, operations, permissions, webhooks, and customer card request to update in your integration. For the steps inside your workspace, see Migrating companies and tenants to accounts.

The product UI switches its labels from tenants to accounts between October 26 and November 1, 2026.

What an account is

An account is the organization a customer belongs to. A customer can belong to more than one account. Read those memberships from accountMemberships on the customer. See Accounts in the docs.

Each account record includes:

name
externalId
primaryDomain and alternateDomains
accountFields
logoUrl

In GraphQL, source is API, SALESFORCE, HUBSPOT, ATTIO, or EMAIL_DOMAIN. Webhook payloads use api, salesforce, hubspot, attio, or email_domain.

Store a company account owner in a user reference account field. The field type is USER_REFERENCE_TYPE.

Tiers and their SLAs apply to an account. Set the tier with updateAccountTier. HubSpot, Salesforce, and Attio map a CRM company to an account and a company attribute to an account field. See CRM.

Fields

Account inputs add accountIdentifier, accountIdentifiers, accountId, accountIds, and accountFields. Plain marks the tenant and company fields they replace as deprecated, and those fields still work. Send one name per field in a request, not both.

Use	Instead of
`accountIdentifier`	`tenantIdentifier`, `companyIdentifier`
`accountIdentifiers`	`tenantIdentifiers`, `companyIdentifiers`
`accountId`	`tenantId`, `companyId`
`accountIds`	`tenantIds`, `companyIds`
`accountFields`	`tenantFields`
`account`	`tenant`, `company`
`accounts`	`tenants`, `companies` on a saved view
`hasAccounts`	`hasCompany`, `hasTenants`
`hasAccountFieldExternalIds`	`hasTenantFieldExternalIds`
`accountMemberships`	`tenantMemberships`, and `company` on a customer
`accountMembershipPolicy`	`tenantMembershipPolicy`
`customerAccounts`	`customerCompany`, `customerTenants`

These inputs accept the new fields:

CreateThreadInput and CreateThreadFromSlackMessageInput accept accountIdentifier. UpsertCustomerOnCreateInput accepts accountIdentifiers.
ThreadsFilter, CustomersFilter, and ThreadMetricFilters accept accountIdentifiers. ThreadsFilter and ThreadMetricFilters also accept accountFields.
CreateTaskInput, UpdateTaskInput, and TierMemberIdentifierInput accept accountId.
TasksFilter, ThreadClustersFilter, ThreadLinkGroupFilter, and BroadcastAudienceFilterInput accept accountIds.
SavedThreadsViewFilterInput accepts accounts and accountFields. ThreadsDisplayOptionsInput accepts hasAccounts and hasAccountFieldExternalIds.
Thread exposes account. ThreadChannelAssociation exposes accountId and accountMembershipPolicy.
Help center access settings accept accountIds. Portal thread visibility accepts customerAccounts and overrideCustomerAccounts.

Grouping and access enums use ACCOUNT where they used COMPANY or TENANT:

ThreadsGroupBy and ThreadMetricGroupBy use ACCOUNT. ThreadMetricGroupBy.ACCOUNT_FIELD replaces TENANT_FIELD and needs subKey set to the field's external ID.
DiscussionSourceEntityType and ThreadScopePrimitiveType use ACCOUNT. ThreadScopePrimitiveType is the dimension on a custom role access filter.

Operations

Call the account operation. Plain marks the tenant and company operations as deprecated, and each deprecation reason names the account operation.

Account operation	Replaces
`accounts`	`tenants`, `companies`
`account`	`tenant`, `company`
`searchAccounts`	`searchTenants`, `searchCompanies`
`accountFieldSchemas`	`tenantFieldSchemas`
`createAccount`	`createTenant`
`upsertAccount`	`upsertTenant`, `upsertCompany`
`deleteAccount`	`deleteTenant`, `deleteCompany`
`addCustomerToAccounts`	`addCustomerToTenants`
`removeCustomerFromAccounts`	`removeCustomerFromTenants`
`setCustomerAccounts`	`setCustomerTenants`, `updateCustomerCompany`
`updateAccountTier`	`updateTenantTier`, `updateCompanyTier`
`importAccounts`	`importTenants`
`updateThreadAccount`	`updateThreadTenant`
`upsertAccountField`	`upsertTenantField`
`upsertAccountFieldSchema`	`upsertTenantFieldSchema`
`deleteAccountField`	`deleteTenantField`
`deleteAccountFieldSchema`	`deleteTenantFieldSchema`
`importAccountFieldSchemas`	`importTenantFieldSchemas`
`importAccountFieldSchemasFromService`	`importTenantFieldSchemasFromService`
`setupAccountFieldSchemaMapping`	`setupTenantFieldSchemaMapping`
`removeAccountFieldSchemaMapping`	`removeTenantFieldSchemaMapping`
`updateThreadChannelAssociationAccountMembershipPolicy`	`updateThreadChannelAssociationTenantMembershipPolicy`

The @team-plain/graphql SDK exposes upsertAccount on client.mutation. upsertTenant and upsertCompany are deprecated and point at upsertAccount. The current calls are documented under Accounts in the API docs.

Permissions

Account calls use tenant permission strings. accounts, account, and searchAccounts need tenant:read. createAccount needs tenant:create. upsertAccount needs tenant:create and tenant:edit. deleteAccount needs tenant:delete.

Account field calls use tenantField and tenantFieldSchema strings. deleteAccountField needs tenant:edit. Adding or removing a customer needs customer:edit plus customerTenantMembership:create or customerTenantMembership:delete. Account fields lists the field strings for each call.

The companies, company, and searchCompanies queries need company:read. upsertCompany needs company:create and company:edit. deleteCompany needs company:delete.

The API docs page for each account call lists the strings it needs.

Webhooks

Account events ship in webhook version 2026-10-06 and later. A target on an earlier version, including an unversioned target, does not receive them. Move the target to 2026-10-06 or later.

The events are:

thread.thread_tenant_updated keeps its event type. The payload includes tenant and previousTenant.

Customer cards

The unversioned customer card request has no version field. It sends the account under tenant, with id and externalId.

Request format 2026-10-19 sets version to "2026-10-19" and sends that same object under account. The full request is in request versions.

Update your customer card API so it reads account when version is 2026-10-19.
Go to Settings > Customer cards and set Request format to 2026-10-19. The setting applies to every customer card in the workspace. You can switch back to unversioned if your API needs more time.

Changing the format reloads every card the next time it is viewed. Plain doesn't reuse cards cached under the other format.

Configuration

Saved views, workflows, custom role access filters, and help center access lists that reference a company show an "Accounts are replacing companies" hint. Plain converts them to the matching account settings.

Replace an Assign to company account owner workflow step with Assign to user, and select a user reference account field.

Compatibility

Deprecated tenant and company fields and operations still work. The deprecation reason on each one names the account field or operation to call. Move your integration to those names.