> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/reference/api-v1/accounts.md). # Accounts **Overview** The Accounts API provides programmatic access to the directory accounts synced from your Google or Microsoft tenant. List and filter accounts, retrieve one by its encoded ID, and update VIP status, licenses, setting overrides, and role assignments. Each account exposes identity and contact fields, [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation) status, licenses, effective product settings with the [layer they resolve from](https://docs.material.security/learn-more/administration/settings-hierarchy), mailbox status, and provider status. Four endpoints make up the Accounts API: * [**List Accounts**](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts) (`GET /api/v1/accounts`): filter, sort, and page through accounts * [**Get Account**](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id) (`GET /api/v1/accounts/{id}`): retrieve a single account by its encoded ID * [**Update Account**](https://docs.material.security/reference/api-v1/accounts#patch-api-v1-accounts-id) (`PATCH /api/v1/accounts/{id}`): update an account's VIP designation, licenses, setting overrides, and role assignments * [**Bulk Accounts**](https://docs.material.security/reference/api-v1/accounts#post-api-v1-accounts-bulk) (`POST /api/v1/accounts/bulk`): apply up to 200 account update operations in one request **Filtering** List accepts `search` (a loose match on name or email), `email`, `type` (`google` or `microsoft`), `vip`, `license`, `licensed`, `group`, `mailboxStatus`, `hasAnyRole`, `role`, `providerStatus`, and `includeMaterialSecuritySupportAdmins`. Per-setting filters use dotted params, for example `setting.emailThreatRemediation=on`, and take `on`, `off`, or `overridden` (the account defines its own override). Comma-separated values match any of the listed values within a single filter, and each filter you add narrows the result set further. Material support admins are excluded by default. Pass `includeMaterialSecuritySupportAdmins=true` to list them. **Sorting** Sort with `?sort=:asc|desc`. Supported fields: `displayName` (default), `email`, and `mailbox.messageCount`. **The `include` Parameter** By default, account responses return identity, VIP, licenses, roles, settings, mailbox, and provider fields. Pass **`include=groups`** on [**Get Account**](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id) to also return the account's group memberships. The list endpoint doesn't take `include`; filter by `group` instead, or page a group's members at [**List Group Members**](https://docs.material.security/reference/api-v1/groups#get-api-v1-groups-id-members). **Updating an Account** Identity, mailbox, and provider fields are synced from your provider and read-only. What you can write is `vip`, `licenses`, `settings`, and `roles`, and only fields present in the body change. Each setting takes `on`, `off`, or `default`. Setting a value to `default` clears the [account-level override](https://docs.material.security/learn-more/administration/group-and-account-customization) so the account inherits from its group, its tenant, or the product default again. Changing `roles` additionally requires role-management permission, and you can only grant [roles](https://docs.material.security/learn-more/administration/admin-roles) you're allowed to bind yourself: a tenant-scoped administrator can't grant Super Admin, or grant anything outside their own tenants. Be careful here. Nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support. **Response Structure** List responses follow the standard two-part structure: a `meta` object (with `totalCount`, `limit`, `hasMore`, and `nextCursor`) and an `items` array of account objects. **Bulk** responses are shaped differently. They return `results`, one entry per operation in request order, so `results[i]` corresponds to `operations[i]`, plus a `meta` object counting how many succeeded and failed. Operations are applied best-effort: a well-formed envelope always returns 200, and individual failures are reported in `results[]` rather than failing the request. **Want a walkthrough?** Review [Hello World](https://docs.material.security/reference/api-v1/hello-world). **Pagination and Rate Limiting** * Material APIs use **cursor-based pagination**: pass the `nextCursor` value from one response as the `cursor` parameter in the next request. * The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request. * When `hasMore` is false and `nextCursor` is null, you've reached the last page. ## List Accounts > Retrieves a paginated list of directory accounts synced from Google or Microsoft. Filter by type, VIP status, licenses, group membership, mailbox and provider status, or per-setting overrides, and sort by name or mailbox size. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Accounts","description":"**Overview**\n\nThe Accounts API provides programmatic access to the directory accounts synced from your Google or Microsoft tenant. List and filter accounts, retrieve one by its encoded ID, and update VIP status, licenses, setting overrides, and role assignments. Each account exposes identity and contact fields, [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation) status, licenses, effective product settings with the [layer they resolve from](https://docs.material.security/learn-more/administration/settings-hierarchy), mailbox status, and provider status.\n\nFour endpoints make up the Accounts API:\n\n* **[List Accounts](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts)** (`GET /api/v1/accounts`): filter, sort, and page through accounts\n* **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** (`GET /api/v1/accounts/{id}`): retrieve a single account by its encoded ID\n* **[Update Account](https://docs.material.security/reference/api-v1/accounts#patch-api-v1-accounts-id)** (`PATCH /api/v1/accounts/{id}`): update an account's VIP designation, licenses, setting overrides, and role assignments\n* **[Bulk Accounts](https://docs.material.security/reference/api-v1/accounts#post-api-v1-accounts-bulk)** (`POST /api/v1/accounts/bulk`): apply up to 200 account update operations in one request\n\n**Filtering**\n\nList accepts `search` (a loose match on name or email), `email`, `type` (`google` or `microsoft`), `vip`, `license`, `licensed`, `group`, `mailboxStatus`, `hasAnyRole`, `role`, `providerStatus`, and `includeMaterialSecuritySupportAdmins`. Per-setting filters use dotted params, for example `setting.emailThreatRemediation=on`, and take `on`, `off`, or `overridden` (the account defines its own override). Comma-separated values match any of the listed values within a single filter, and each filter you add narrows the result set further.\n\nMaterial support admins are excluded by default. Pass `includeMaterialSecuritySupportAdmins=true` to list them.\n\n**Sorting**\n\nSort with `?sort=:asc|desc`. Supported fields: `displayName` (default), `email`, and `mailbox.messageCount`.\n\n**The `include` Parameter**\n\nBy default, account responses return identity, VIP, licenses, roles, settings, mailbox, and provider fields. Pass **`include=groups`** on **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** to also return the account's group memberships. The list endpoint doesn't take `include`; filter by `group` instead, or page a group's members at **[List Group Members](https://docs.material.security/reference/api-v1/groups#get-api-v1-groups-id-members)**.\n\n**Updating an Account**\n\nIdentity, mailbox, and provider fields are synced from your provider and read-only. What you can write is `vip`, `licenses`, `settings`, and `roles`, and only fields present in the body change.\n\nEach setting takes `on`, `off`, or `default`. Setting a value to `default` clears the [account-level override](https://docs.material.security/learn-more/administration/group-and-account-customization) so the account inherits from its group, its tenant, or the product default again.\n\nChanging `roles` additionally requires role-management permission, and you can only grant [roles](https://docs.material.security/learn-more/administration/admin-roles) you're allowed to bind yourself: a tenant-scoped administrator can't grant Super Admin, or grant anything outside their own tenants. Be careful here. Nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.\n\n**Response Structure**\n\nList responses follow the standard two-part structure: a `meta` object (with `totalCount`, `limit`, `hasMore`, and `nextCursor`) and an `items` array of account objects.\n\n**Bulk** responses are shaped differently. They return `results`, one entry per operation in request order, so `results[i]` corresponds to `operations[i]`, plus a `meta` object counting how many succeeded and failed. Operations are applied best-effort: a well-formed envelope always returns 200, and individual failures are reported in `results[]` rather than failing the request.\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APIAccountCollection":{"title":"APIAccountCollection","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIAccount"}}},"required":["meta","items"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APIAccount":{"title":"APIAccount","description":"A directory account (person or mailbox) synced from Google or Microsoft.","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"type":{"description":"The provider the account is synced from: `google` or `microsoft`.","type":"string","enum":["google","microsoft"]},"displayName":{"description":"Display name of the account holder.","type":"string"},"givenName":{"description":"Given (first) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"familyName":{"description":"Family (last) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"description":"Primary email address.","type":"string"},"aliases":{"description":"Additional email aliases.","type":"array","items":{"type":"string"}},"organization":{"description":"The organization on the account's directory record. Read-only, and null if your provider doesn't supply one.","anyOf":[{"type":"string"},{"type":"null"}]},"vip":{"$ref":"#/components/schemas/APIVip"},"licenses":{"$ref":"#/components/schemas/APILicenses"},"roles":{"description":"The [roles](https://docs.material.security/learn-more/administration/admin-roles) in effect on this account, both assigned directly and inherited from groups. A role held at a broader scope hides the narrower assignments it supersedes, so this reflects effective access rather than every assignment on record. Empty if the account has no roles. Roles are scoped to this account, so if one person owns several accounts, each reports only its own roles, matching the `role` filter.","type":"array","items":{"$ref":"#/components/schemas/APIAssignedRole"}},"settings":{"$ref":"#/components/schemas/APIAccountSettings"},"mailbox":{"$ref":"#/components/schemas/APIAccountMailbox"},"providerStatus":{"description":"The account's state at your provider: `active`, `suspended`, `archived`, or `deleted`.","type":"string","enum":["active","suspended","archived","deleted"]},"lastSyncedAt":{"description":"When Material last synced this account, in ISO 8601 format. Null if it has never synced.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"groups":{"description":"Group memberships; populated only when `include=groups`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}}},"required":["meta","items"]}},"required":["id","type","displayName","givenName","familyName","email","aliases","organization","vip","licenses","roles","settings","mailbox","providerStatus","lastSyncedAt"]},"APIVip":{"title":"APIVip","type":"object","properties":{"enabled":{"description":"Whether the account is marked as a [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation).","type":"boolean"},"emailAliases":{"description":"Additional email aliases treated as this VIP.","type":"array","items":{"type":"string"}},"displayNames":{"description":"Additional display names treated as this VIP.","type":"array","items":{"type":"string"}}},"required":["enabled","emailAliases","displayNames"]},"APILicenses":{"title":"APILicenses","type":"object","properties":{"values":{"description":"The licenses active on this account: `essentials` (Essentials), `advanced` (Advanced), or `ato_resilience` (ATO Resilience). An account carries at most one tier, `essentials` or `advanced`, and can add `ato_resilience` alongside it.","type":"array","items":{"type":"string","enum":["essentials","advanced","ato_resilience"]}},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"},"requireMailbox":{"title":"APIBooleanSetting","description":"Whether an account needs a provisioned mailbox before Material assigns it a license. Shown as **Require mailbox for license assignment** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"}},"required":["values","source","requireMailbox"]},"APIGroupRef":{"title":"APIGroupRef","type":"object","properties":{"id":{"description":"The encoded group ID. Format: `grp.1.`.","type":"string"},"name":{"description":"The group's display name. Null if Material doesn't have one.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"APIBooleanSetting":{"title":"APIBooleanSetting","type":"object","properties":{"enabled":{"description":"Whether the setting is enabled for this account.","type":"boolean"},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["enabled","source"]},"APIAssignedRole":{"title":"APIAssignedRole","type":"object","properties":{"id":{"description":"Role ID. The ID carries the role's scope: tenant-scoped IDs (for example `analyst`) require `tenants`, while IDs that apply everywhere (for example `global_analyst`, `super_admin`, `tenant_enroller`) take none. Call `GET /roles` for the IDs available on your instance.","type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]},"tenants":{"description":"Tenants the role applies to, as encoded tenant IDs (format `tnt.1.`), for tenant-scoped IDs only. `\"all\"` means the role was granted across every tenant, which you can read but not assign through this API.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"all"}]},"source":{"description":"Where the assignment comes from: `direct` (on this account), `group` (inherited from `groupId`, and changeable only on that group), or `tenant` (granted to everyone in the tenant).","type":"string","enum":["direct","group","tenant"]},"groupId":{"description":"The granting group; present only when `source` is `group`.","type":"string"}},"required":["id","source"]},"APIAccountSettings":{"title":"APIAccountSettings","description":"Each product setting's effective value for this account, with the layer it resolves from. See [Group and Account Customization](https://docs.material.security/learn-more/administration/group-and-account-customization) for how overrides work.","type":"object","properties":{"emailSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's mailbox. Shown as **Mailbox Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's Google Drive files. Shown as **My Drive Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailThreatRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates email threats found in this mailbox. Shown as **Email Threat Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates risky sharing on this account's files. Shown as **File Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"sensitiveEmailRedaction":{"title":"APIBooleanSetting","description":"Whether Material redacts sensitive email in this mailbox. Shown as **Sensitive Email Redaction** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"passwordResetProtection":{"title":"APIBooleanSetting","description":"Whether Material holds password reset and app signup email for this account during a lockdown. Shown as **Password Reset & App Signup Protection** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"oauthAppRemediation":{"title":"APIBooleanSetting","description":"Whether Material revokes this account's grants when an OAuth app carries a revoke policy. Shown as **OAuth App Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailBombProtection":{"title":"APIModeSetting","description":"How Material handles a sudden surge of email to this account. Shown as **[Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection)** on an account's **Settings** tab.","$ref":"#/components/schemas/APIModeSetting"}},"required":["emailSync","fileSync","emailThreatRemediation","fileRemediation","sensitiveEmailRedaction","passwordResetProtection","oauthAppRemediation","emailBombProtection"]},"APIModeSetting":{"title":"APIModeSetting","type":"object","properties":{"mode":{"description":"How [Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection) is applied to this account: `enabled` (detect and remediate), `detection_only` (detect without remediating), or `disabled`.","type":"string","enum":["enabled","detection_only","disabled"]},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["mode","source"]},"APIAccountMailbox":{"title":"APIAccountMailbox","type":"object","properties":{"status":{"description":"Whether the account's mailbox is `enabled` or `disabled`. Null when Material hasn't synced the mailbox or can't determine its state.","anyOf":[{"type":"string","enum":["enabled","disabled"]},{"type":"null"}]},"messageCount":{"description":"Approximate number of messages in the mailbox. Null if unknown.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["status","messageCount"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/accounts":{"get":{"operationId":"listAccounts","summary":"List Accounts","description":"Retrieves a paginated list of directory accounts synced from Google or Microsoft. Filter by type, VIP status, licenses, group membership, mailbox and provider status, or per-setting overrides, and sort by name or mailbox size.","tags":["Accounts"],"parameters":[{"in":"query","name":"cursor","schema":{"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.","type":"string"},"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results."},{"in":"query","name":"limit","schema":{"description":"The maximum number of items to return per page.","type":"integer"},"description":"The maximum number of items to return per page."},{"in":"query","name":"search","schema":{"description":"Loose match on the account name or email address.","type":"string"},"description":"Loose match on the account name or email address."},{"in":"query","name":"email","schema":{"description":"Filter to these exact email addresses, comma-separated.","type":"string"},"description":"Filter to these exact email addresses, comma-separated."},{"in":"query","name":"type","schema":{"description":"Filter by the provider the account is synced from: `google` or `microsoft`.","type":"string","enum":["google","microsoft"]},"description":"Filter by the provider the account is synced from: `google` or `microsoft`."},{"in":"query","name":"vip","schema":{"description":"Filter to accounts marked as a VIP (true) or not marked (false).","type":"boolean"},"description":"Filter to accounts marked as a VIP (true) or not marked (false)."},{"in":"query","name":"license","schema":{"description":"Filter to accounts holding any of these active licenses, comma-separated.","type":"string"},"description":"Filter to accounts holding any of these active licenses, comma-separated."},{"in":"query","name":"licensed","schema":{"description":"Filter to accounts with (true) or without (false) any active license.","type":"boolean"},"description":"Filter to accounts with (true) or without (false) any active license."},{"in":"query","name":"group","schema":{"description":"Filter to members of any of these groups, as comma-separated encoded group IDs (format `grp.1.`).","type":"string"},"description":"Filter to members of any of these groups, as comma-separated encoded group IDs (format `grp.1.`)."},{"in":"query","name":"mailboxStatus","schema":{"description":"Filter by mailbox status: `enabled` or `disabled`.","type":"string","enum":["enabled","disabled"]},"description":"Filter by mailbox status: `enabled` or `disabled`."},{"in":"query","name":"hasAnyRole","schema":{"description":"Filter to accounts that hold at least one role (true) or none at all (false).","type":"boolean"},"description":"Filter to accounts that hold at least one role (true) or none at all (false)."},{"in":"query","name":"providerStatus","schema":{"description":"Filter by the account's state at your provider: `active`, `suspended`, `archived`, or `deleted`. One value only.","type":"string","enum":["active","suspended","archived","deleted"]},"description":"Filter by the account's state at your provider: `active`, `suspended`, `archived`, or `deleted`. One value only."},{"in":"query","name":"includeMaterialSecuritySupportAdmins","schema":{"description":"Include Material support admins, the Material employees with support access to your instance. They are excluded by default.","type":"boolean"},"description":"Include Material support admins, the Material employees with support access to your instance. They are excluded by default."},{"in":"query","name":"role","schema":{"description":"Filter to accounts holding any of these roles, comma-separated. Matches roles inherited from a group as well as those assigned directly. Call `GET /roles` for the IDs available on your instance.","type":"string"},"description":"Filter to accounts holding any of these roles, comma-separated. Matches roles inherited from a group as well as those assigned directly. Call `GET /roles` for the IDs available on your instance."},{"in":"query","name":"setting.emailSync","schema":{"description":"Filter by the effective `emailSync` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `emailSync` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"setting.fileSync","schema":{"description":"Filter by the effective `fileSync` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `fileSync` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"setting.emailThreatRemediation","schema":{"description":"Filter by the effective `emailThreatRemediation` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `emailThreatRemediation` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"setting.fileRemediation","schema":{"description":"Filter by the effective `fileRemediation` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `fileRemediation` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"setting.sensitiveEmailRedaction","schema":{"description":"Filter by the effective `sensitiveEmailRedaction` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `sensitiveEmailRedaction` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"setting.passwordResetProtection","schema":{"description":"Filter by the effective `passwordResetProtection` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `passwordResetProtection` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"setting.oauthAppRemediation","schema":{"description":"Filter by the effective `oauthAppRemediation` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `oauthAppRemediation` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"setting.emailBombProtection","schema":{"description":"Filter by the effective `emailBombProtection` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value).","type":"string","enum":["on","off","overridden"]},"description":"Filter by the effective `emailBombProtection` setting: `on`, `off`, or `overridden` (the account defines its own override, whatever the value)."},{"in":"query","name":"sort","schema":{"description":"Sort field, e.g. `displayName:asc` or `mailbox.messageCount:desc`. A single field only.","type":"string"},"description":"Sort field, e.g. `displayName:asc` or `mailbox.messageCount:desc`. A single field only."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIAccountCollection"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests: the client has exceeded a rate limit and should retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Get Account > Retrieves the full details of a single account by its encoded ID, including identity, VIP, licenses, effective settings with their source, mailbox, and provider status. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Accounts","description":"**Overview**\n\nThe Accounts API provides programmatic access to the directory accounts synced from your Google or Microsoft tenant. List and filter accounts, retrieve one by its encoded ID, and update VIP status, licenses, setting overrides, and role assignments. Each account exposes identity and contact fields, [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation) status, licenses, effective product settings with the [layer they resolve from](https://docs.material.security/learn-more/administration/settings-hierarchy), mailbox status, and provider status.\n\nFour endpoints make up the Accounts API:\n\n* **[List Accounts](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts)** (`GET /api/v1/accounts`): filter, sort, and page through accounts\n* **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** (`GET /api/v1/accounts/{id}`): retrieve a single account by its encoded ID\n* **[Update Account](https://docs.material.security/reference/api-v1/accounts#patch-api-v1-accounts-id)** (`PATCH /api/v1/accounts/{id}`): update an account's VIP designation, licenses, setting overrides, and role assignments\n* **[Bulk Accounts](https://docs.material.security/reference/api-v1/accounts#post-api-v1-accounts-bulk)** (`POST /api/v1/accounts/bulk`): apply up to 200 account update operations in one request\n\n**Filtering**\n\nList accepts `search` (a loose match on name or email), `email`, `type` (`google` or `microsoft`), `vip`, `license`, `licensed`, `group`, `mailboxStatus`, `hasAnyRole`, `role`, `providerStatus`, and `includeMaterialSecuritySupportAdmins`. Per-setting filters use dotted params, for example `setting.emailThreatRemediation=on`, and take `on`, `off`, or `overridden` (the account defines its own override). Comma-separated values match any of the listed values within a single filter, and each filter you add narrows the result set further.\n\nMaterial support admins are excluded by default. Pass `includeMaterialSecuritySupportAdmins=true` to list them.\n\n**Sorting**\n\nSort with `?sort=:asc|desc`. Supported fields: `displayName` (default), `email`, and `mailbox.messageCount`.\n\n**The `include` Parameter**\n\nBy default, account responses return identity, VIP, licenses, roles, settings, mailbox, and provider fields. Pass **`include=groups`** on **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** to also return the account's group memberships. The list endpoint doesn't take `include`; filter by `group` instead, or page a group's members at **[List Group Members](https://docs.material.security/reference/api-v1/groups#get-api-v1-groups-id-members)**.\n\n**Updating an Account**\n\nIdentity, mailbox, and provider fields are synced from your provider and read-only. What you can write is `vip`, `licenses`, `settings`, and `roles`, and only fields present in the body change.\n\nEach setting takes `on`, `off`, or `default`. Setting a value to `default` clears the [account-level override](https://docs.material.security/learn-more/administration/group-and-account-customization) so the account inherits from its group, its tenant, or the product default again.\n\nChanging `roles` additionally requires role-management permission, and you can only grant [roles](https://docs.material.security/learn-more/administration/admin-roles) you're allowed to bind yourself: a tenant-scoped administrator can't grant Super Admin, or grant anything outside their own tenants. Be careful here. Nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.\n\n**Response Structure**\n\nList responses follow the standard two-part structure: a `meta` object (with `totalCount`, `limit`, `hasMore`, and `nextCursor`) and an `items` array of account objects.\n\n**Bulk** responses are shaped differently. They return `results`, one entry per operation in request order, so `results[i]` corresponds to `operations[i]`, plus a `meta` object counting how many succeeded and failed. Operations are applied best-effort: a well-formed envelope always returns 200, and individual failures are reported in `results[]` rather than failing the request.\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APIAccount":{"title":"APIAccount","description":"A directory account (person or mailbox) synced from Google or Microsoft.","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"type":{"description":"The provider the account is synced from: `google` or `microsoft`.","type":"string","enum":["google","microsoft"]},"displayName":{"description":"Display name of the account holder.","type":"string"},"givenName":{"description":"Given (first) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"familyName":{"description":"Family (last) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"description":"Primary email address.","type":"string"},"aliases":{"description":"Additional email aliases.","type":"array","items":{"type":"string"}},"organization":{"description":"The organization on the account's directory record. Read-only, and null if your provider doesn't supply one.","anyOf":[{"type":"string"},{"type":"null"}]},"vip":{"$ref":"#/components/schemas/APIVip"},"licenses":{"$ref":"#/components/schemas/APILicenses"},"roles":{"description":"The [roles](https://docs.material.security/learn-more/administration/admin-roles) in effect on this account, both assigned directly and inherited from groups. A role held at a broader scope hides the narrower assignments it supersedes, so this reflects effective access rather than every assignment on record. Empty if the account has no roles. Roles are scoped to this account, so if one person owns several accounts, each reports only its own roles, matching the `role` filter.","type":"array","items":{"$ref":"#/components/schemas/APIAssignedRole"}},"settings":{"$ref":"#/components/schemas/APIAccountSettings"},"mailbox":{"$ref":"#/components/schemas/APIAccountMailbox"},"providerStatus":{"description":"The account's state at your provider: `active`, `suspended`, `archived`, or `deleted`.","type":"string","enum":["active","suspended","archived","deleted"]},"lastSyncedAt":{"description":"When Material last synced this account, in ISO 8601 format. Null if it has never synced.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"groups":{"description":"Group memberships; populated only when `include=groups`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}}},"required":["meta","items"]}},"required":["id","type","displayName","givenName","familyName","email","aliases","organization","vip","licenses","roles","settings","mailbox","providerStatus","lastSyncedAt"]},"APIVip":{"title":"APIVip","type":"object","properties":{"enabled":{"description":"Whether the account is marked as a [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation).","type":"boolean"},"emailAliases":{"description":"Additional email aliases treated as this VIP.","type":"array","items":{"type":"string"}},"displayNames":{"description":"Additional display names treated as this VIP.","type":"array","items":{"type":"string"}}},"required":["enabled","emailAliases","displayNames"]},"APILicenses":{"title":"APILicenses","type":"object","properties":{"values":{"description":"The licenses active on this account: `essentials` (Essentials), `advanced` (Advanced), or `ato_resilience` (ATO Resilience). An account carries at most one tier, `essentials` or `advanced`, and can add `ato_resilience` alongside it.","type":"array","items":{"type":"string","enum":["essentials","advanced","ato_resilience"]}},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"},"requireMailbox":{"title":"APIBooleanSetting","description":"Whether an account needs a provisioned mailbox before Material assigns it a license. Shown as **Require mailbox for license assignment** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"}},"required":["values","source","requireMailbox"]},"APIGroupRef":{"title":"APIGroupRef","type":"object","properties":{"id":{"description":"The encoded group ID. Format: `grp.1.`.","type":"string"},"name":{"description":"The group's display name. Null if Material doesn't have one.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"APIBooleanSetting":{"title":"APIBooleanSetting","type":"object","properties":{"enabled":{"description":"Whether the setting is enabled for this account.","type":"boolean"},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["enabled","source"]},"APIAssignedRole":{"title":"APIAssignedRole","type":"object","properties":{"id":{"description":"Role ID. The ID carries the role's scope: tenant-scoped IDs (for example `analyst`) require `tenants`, while IDs that apply everywhere (for example `global_analyst`, `super_admin`, `tenant_enroller`) take none. Call `GET /roles` for the IDs available on your instance.","type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]},"tenants":{"description":"Tenants the role applies to, as encoded tenant IDs (format `tnt.1.`), for tenant-scoped IDs only. `\"all\"` means the role was granted across every tenant, which you can read but not assign through this API.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"all"}]},"source":{"description":"Where the assignment comes from: `direct` (on this account), `group` (inherited from `groupId`, and changeable only on that group), or `tenant` (granted to everyone in the tenant).","type":"string","enum":["direct","group","tenant"]},"groupId":{"description":"The granting group; present only when `source` is `group`.","type":"string"}},"required":["id","source"]},"APIAccountSettings":{"title":"APIAccountSettings","description":"Each product setting's effective value for this account, with the layer it resolves from. See [Group and Account Customization](https://docs.material.security/learn-more/administration/group-and-account-customization) for how overrides work.","type":"object","properties":{"emailSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's mailbox. Shown as **Mailbox Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's Google Drive files. Shown as **My Drive Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailThreatRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates email threats found in this mailbox. Shown as **Email Threat Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates risky sharing on this account's files. Shown as **File Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"sensitiveEmailRedaction":{"title":"APIBooleanSetting","description":"Whether Material redacts sensitive email in this mailbox. Shown as **Sensitive Email Redaction** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"passwordResetProtection":{"title":"APIBooleanSetting","description":"Whether Material holds password reset and app signup email for this account during a lockdown. Shown as **Password Reset & App Signup Protection** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"oauthAppRemediation":{"title":"APIBooleanSetting","description":"Whether Material revokes this account's grants when an OAuth app carries a revoke policy. Shown as **OAuth App Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailBombProtection":{"title":"APIModeSetting","description":"How Material handles a sudden surge of email to this account. Shown as **[Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection)** on an account's **Settings** tab.","$ref":"#/components/schemas/APIModeSetting"}},"required":["emailSync","fileSync","emailThreatRemediation","fileRemediation","sensitiveEmailRedaction","passwordResetProtection","oauthAppRemediation","emailBombProtection"]},"APIModeSetting":{"title":"APIModeSetting","type":"object","properties":{"mode":{"description":"How [Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection) is applied to this account: `enabled` (detect and remediate), `detection_only` (detect without remediating), or `disabled`.","type":"string","enum":["enabled","detection_only","disabled"]},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["mode","source"]},"APIAccountMailbox":{"title":"APIAccountMailbox","type":"object","properties":{"status":{"description":"Whether the account's mailbox is `enabled` or `disabled`. Null when Material hasn't synced the mailbox or can't determine its state.","anyOf":[{"type":"string","enum":["enabled","disabled"]},{"type":"null"}]},"messageCount":{"description":"Approximate number of messages in the mailbox. Null if unknown.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["status","messageCount"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/accounts/{id}":{"get":{"operationId":"getAccount","summary":"Get Account","description":"Retrieves the full details of a single account by its encoded ID, including identity, VIP, licenses, effective settings with their source, mailbox, and provider status.","tags":["Accounts"],"parameters":[{"in":"path","name":"id","schema":{"description":"The encoded ID of the account to retrieve. Format: `acct.1.`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"The encoded ID of the account to retrieve. Format: `acct.1.`."},{"in":"query","name":"include","schema":{"description":"Comma-separated list of extra fields to return. Supported: `groups`, the account's group memberships.","type":"string"},"description":"Comma-separated list of extra fields to return. Supported: `groups`, the account's group memberships."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIAccount"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests: the client has exceeded a rate limit and should retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Update Account > Updates an account's \[VIP]\() designation, license allocation, per-account setting overrides, and \[role]\() assignments. Identity, mailbox, and provider fields are read-only, since they're synced from your provider. Only provided fields change, and a setting value of \`default\` clears the account override so it inherits from a higher level. Changing \`roles\` additionally requires role-management permission, and a tenant-scoped administrator can only grant roles they're allowed to bind themselves, within their own tenants. Be careful: nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Accounts","description":"**Overview**\n\nThe Accounts API provides programmatic access to the directory accounts synced from your Google or Microsoft tenant. List and filter accounts, retrieve one by its encoded ID, and update VIP status, licenses, setting overrides, and role assignments. Each account exposes identity and contact fields, [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation) status, licenses, effective product settings with the [layer they resolve from](https://docs.material.security/learn-more/administration/settings-hierarchy), mailbox status, and provider status.\n\nFour endpoints make up the Accounts API:\n\n* **[List Accounts](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts)** (`GET /api/v1/accounts`): filter, sort, and page through accounts\n* **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** (`GET /api/v1/accounts/{id}`): retrieve a single account by its encoded ID\n* **[Update Account](https://docs.material.security/reference/api-v1/accounts#patch-api-v1-accounts-id)** (`PATCH /api/v1/accounts/{id}`): update an account's VIP designation, licenses, setting overrides, and role assignments\n* **[Bulk Accounts](https://docs.material.security/reference/api-v1/accounts#post-api-v1-accounts-bulk)** (`POST /api/v1/accounts/bulk`): apply up to 200 account update operations in one request\n\n**Filtering**\n\nList accepts `search` (a loose match on name or email), `email`, `type` (`google` or `microsoft`), `vip`, `license`, `licensed`, `group`, `mailboxStatus`, `hasAnyRole`, `role`, `providerStatus`, and `includeMaterialSecuritySupportAdmins`. Per-setting filters use dotted params, for example `setting.emailThreatRemediation=on`, and take `on`, `off`, or `overridden` (the account defines its own override). Comma-separated values match any of the listed values within a single filter, and each filter you add narrows the result set further.\n\nMaterial support admins are excluded by default. Pass `includeMaterialSecuritySupportAdmins=true` to list them.\n\n**Sorting**\n\nSort with `?sort=:asc|desc`. Supported fields: `displayName` (default), `email`, and `mailbox.messageCount`.\n\n**The `include` Parameter**\n\nBy default, account responses return identity, VIP, licenses, roles, settings, mailbox, and provider fields. Pass **`include=groups`** on **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** to also return the account's group memberships. The list endpoint doesn't take `include`; filter by `group` instead, or page a group's members at **[List Group Members](https://docs.material.security/reference/api-v1/groups#get-api-v1-groups-id-members)**.\n\n**Updating an Account**\n\nIdentity, mailbox, and provider fields are synced from your provider and read-only. What you can write is `vip`, `licenses`, `settings`, and `roles`, and only fields present in the body change.\n\nEach setting takes `on`, `off`, or `default`. Setting a value to `default` clears the [account-level override](https://docs.material.security/learn-more/administration/group-and-account-customization) so the account inherits from its group, its tenant, or the product default again.\n\nChanging `roles` additionally requires role-management permission, and you can only grant [roles](https://docs.material.security/learn-more/administration/admin-roles) you're allowed to bind yourself: a tenant-scoped administrator can't grant Super Admin, or grant anything outside their own tenants. Be careful here. Nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.\n\n**Response Structure**\n\nList responses follow the standard two-part structure: a `meta` object (with `totalCount`, `limit`, `hasMore`, and `nextCursor`) and an `items` array of account objects.\n\n**Bulk** responses are shaped differently. They return `results`, one entry per operation in request order, so `results[i]` corresponds to `operations[i]`, plus a `meta` object counting how many succeeded and failed. Operations are applied best-effort: a well-formed envelope always returns 200, and individual failures are reported in `results[]` rather than failing the request.\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"UpdateAccountBody":{"title":"UpdateAccountBody","type":"object","properties":{"vip":{"description":"VIP designation and its aliases. Only provided sub-fields change.","$ref":"#/components/schemas/UpdateAccountVip"},"licenses":{"description":"License allocation and the require-mailbox policy.","$ref":"#/components/schemas/UpdateAccountLicenses"},"settings":{"description":"Per-account setting overrides. Only provided settings change.","$ref":"#/components/schemas/UpdateAccountSettings"},"roles":{"description":"[Roles](https://docs.material.security/learn-more/administration/admin-roles) to grant or revoke on this account. Requires role-management permission.","$ref":"#/components/schemas/UpdateRoles"}}},"UpdateAccountVip":{"title":"UpdateAccountVip","type":"object","properties":{"enabled":{"description":"Mark (true) or unmark (false) the account as a VIP.","type":"boolean"},"emailAliases":{"description":"Replace the VIP email aliases. An empty array clears them.","type":"array","items":{"type":"string"}},"displayNames":{"description":"Replace the VIP display names. An empty array clears them.","type":"array","items":{"type":"string"}}}},"UpdateAccountLicenses":{"title":"UpdateAccountLicenses","type":"object","properties":{"values":{"description":"The complete set of licenses the account should end up with, not a list of changes to apply. Include at most one tier, `essentials` (Essentials) or `advanced` (Advanced), and optionally `ato_resilience` (ATO Resilience) alongside it. Send `[]` to allocate none, or `\"default\"` to inherit from a higher level.","anyOf":[{"type":"array","items":{"type":"string","enum":["essentials","advanced","ato_resilience"]}},{"type":"string","const":"default"}]},"requireMailbox":{"description":"Set `requireMailbox` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]}}},"UpdateAccountSettings":{"title":"UpdateAccountSettings","type":"object","properties":{"emailSync":{"description":"Set `emailSync` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"fileSync":{"description":"Set `fileSync` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"emailThreatRemediation":{"description":"Set `emailThreatRemediation` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"fileRemediation":{"description":"Set `fileRemediation` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"sensitiveEmailRedaction":{"description":"Set `sensitiveEmailRedaction` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"passwordResetProtection":{"description":"Set `passwordResetProtection` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"oauthAppRemediation":{"description":"Set `oauthAppRemediation` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"emailBombProtection":{"description":"Set `emailBombProtection` to `enabled`, `detection_only`, or `disabled`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["enabled","detection_only","disabled","default"]}}},"UpdateRoles":{"title":"UpdateRoles","description":"Role assignment changes. Only roles named in `assign` or `remove` are affected, so this is not a full-set replacement. Be careful: nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.","type":"object","properties":{"assign":{"description":"Roles to grant. Only the listed roles are touched.","type":"array","items":{"$ref":"#/components/schemas/APIRoleAssignment"}},"remove":{"description":"Roles to revoke, at every scope the account or group holds them. There is no per-tenant removal, so to narrow a role rather than drop it, re-assign it with a shorter `tenants` list instead. Removing a role that isn't held does nothing, and a role inherited from a group must be removed on that group. Listing an ID in both `assign` and `remove` returns a 400.","type":"array","items":{"type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]}}}},"APIRoleAssignment":{"title":"APIRoleAssignment","type":"object","properties":{"id":{"description":"Role ID. The ID carries the role's scope: tenant-scoped IDs (for example `analyst`) require `tenants`, while IDs that apply everywhere (for example `global_analyst`, `super_admin`, `tenant_enroller`) take none. Call `GET /roles` for the IDs available on your instance.","type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]},"tenants":{"description":"Tenants to grant the role in, as encoded tenant IDs (format `tnt.1.`). Required for tenant-scoped IDs, rejected for the others. Assigning a tenant-scoped role the account or group already holds replaces its tenant list.","type":"array","items":{"type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"}}},"required":["id"]},"APIAccount":{"title":"APIAccount","description":"A directory account (person or mailbox) synced from Google or Microsoft.","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"type":{"description":"The provider the account is synced from: `google` or `microsoft`.","type":"string","enum":["google","microsoft"]},"displayName":{"description":"Display name of the account holder.","type":"string"},"givenName":{"description":"Given (first) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"familyName":{"description":"Family (last) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"description":"Primary email address.","type":"string"},"aliases":{"description":"Additional email aliases.","type":"array","items":{"type":"string"}},"organization":{"description":"The organization on the account's directory record. Read-only, and null if your provider doesn't supply one.","anyOf":[{"type":"string"},{"type":"null"}]},"vip":{"$ref":"#/components/schemas/APIVip"},"licenses":{"$ref":"#/components/schemas/APILicenses"},"roles":{"description":"The [roles](https://docs.material.security/learn-more/administration/admin-roles) in effect on this account, both assigned directly and inherited from groups. A role held at a broader scope hides the narrower assignments it supersedes, so this reflects effective access rather than every assignment on record. Empty if the account has no roles. Roles are scoped to this account, so if one person owns several accounts, each reports only its own roles, matching the `role` filter.","type":"array","items":{"$ref":"#/components/schemas/APIAssignedRole"}},"settings":{"$ref":"#/components/schemas/APIAccountSettings"},"mailbox":{"$ref":"#/components/schemas/APIAccountMailbox"},"providerStatus":{"description":"The account's state at your provider: `active`, `suspended`, `archived`, or `deleted`.","type":"string","enum":["active","suspended","archived","deleted"]},"lastSyncedAt":{"description":"When Material last synced this account, in ISO 8601 format. Null if it has never synced.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"groups":{"description":"Group memberships; populated only when `include=groups`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}}},"required":["meta","items"]}},"required":["id","type","displayName","givenName","familyName","email","aliases","organization","vip","licenses","roles","settings","mailbox","providerStatus","lastSyncedAt"]},"APIVip":{"title":"APIVip","type":"object","properties":{"enabled":{"description":"Whether the account is marked as a [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation).","type":"boolean"},"emailAliases":{"description":"Additional email aliases treated as this VIP.","type":"array","items":{"type":"string"}},"displayNames":{"description":"Additional display names treated as this VIP.","type":"array","items":{"type":"string"}}},"required":["enabled","emailAliases","displayNames"]},"APILicenses":{"title":"APILicenses","type":"object","properties":{"values":{"description":"The licenses active on this account: `essentials` (Essentials), `advanced` (Advanced), or `ato_resilience` (ATO Resilience). An account carries at most one tier, `essentials` or `advanced`, and can add `ato_resilience` alongside it.","type":"array","items":{"type":"string","enum":["essentials","advanced","ato_resilience"]}},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"},"requireMailbox":{"title":"APIBooleanSetting","description":"Whether an account needs a provisioned mailbox before Material assigns it a license. Shown as **Require mailbox for license assignment** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"}},"required":["values","source","requireMailbox"]},"APIGroupRef":{"title":"APIGroupRef","type":"object","properties":{"id":{"description":"The encoded group ID. Format: `grp.1.`.","type":"string"},"name":{"description":"The group's display name. Null if Material doesn't have one.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"APIBooleanSetting":{"title":"APIBooleanSetting","type":"object","properties":{"enabled":{"description":"Whether the setting is enabled for this account.","type":"boolean"},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["enabled","source"]},"APIAssignedRole":{"title":"APIAssignedRole","type":"object","properties":{"id":{"description":"Role ID. The ID carries the role's scope: tenant-scoped IDs (for example `analyst`) require `tenants`, while IDs that apply everywhere (for example `global_analyst`, `super_admin`, `tenant_enroller`) take none. Call `GET /roles` for the IDs available on your instance.","type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]},"tenants":{"description":"Tenants the role applies to, as encoded tenant IDs (format `tnt.1.`), for tenant-scoped IDs only. `\"all\"` means the role was granted across every tenant, which you can read but not assign through this API.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"all"}]},"source":{"description":"Where the assignment comes from: `direct` (on this account), `group` (inherited from `groupId`, and changeable only on that group), or `tenant` (granted to everyone in the tenant).","type":"string","enum":["direct","group","tenant"]},"groupId":{"description":"The granting group; present only when `source` is `group`.","type":"string"}},"required":["id","source"]},"APIAccountSettings":{"title":"APIAccountSettings","description":"Each product setting's effective value for this account, with the layer it resolves from. See [Group and Account Customization](https://docs.material.security/learn-more/administration/group-and-account-customization) for how overrides work.","type":"object","properties":{"emailSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's mailbox. Shown as **Mailbox Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's Google Drive files. Shown as **My Drive Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailThreatRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates email threats found in this mailbox. Shown as **Email Threat Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates risky sharing on this account's files. Shown as **File Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"sensitiveEmailRedaction":{"title":"APIBooleanSetting","description":"Whether Material redacts sensitive email in this mailbox. Shown as **Sensitive Email Redaction** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"passwordResetProtection":{"title":"APIBooleanSetting","description":"Whether Material holds password reset and app signup email for this account during a lockdown. Shown as **Password Reset & App Signup Protection** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"oauthAppRemediation":{"title":"APIBooleanSetting","description":"Whether Material revokes this account's grants when an OAuth app carries a revoke policy. Shown as **OAuth App Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailBombProtection":{"title":"APIModeSetting","description":"How Material handles a sudden surge of email to this account. Shown as **[Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection)** on an account's **Settings** tab.","$ref":"#/components/schemas/APIModeSetting"}},"required":["emailSync","fileSync","emailThreatRemediation","fileRemediation","sensitiveEmailRedaction","passwordResetProtection","oauthAppRemediation","emailBombProtection"]},"APIModeSetting":{"title":"APIModeSetting","type":"object","properties":{"mode":{"description":"How [Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection) is applied to this account: `enabled` (detect and remediate), `detection_only` (detect without remediating), or `disabled`.","type":"string","enum":["enabled","detection_only","disabled"]},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["mode","source"]},"APIAccountMailbox":{"title":"APIAccountMailbox","type":"object","properties":{"status":{"description":"Whether the account's mailbox is `enabled` or `disabled`. Null when Material hasn't synced the mailbox or can't determine its state.","anyOf":[{"type":"string","enum":["enabled","disabled"]},{"type":"null"}]},"messageCount":{"description":"Approximate number of messages in the mailbox. Null if unknown.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["status","messageCount"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/accounts/{id}":{"patch":{"operationId":"patchAccount","summary":"Update Account","description":"Updates an account's [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation) designation, license allocation, per-account setting overrides, and [role](https://docs.material.security/learn-more/administration/admin-roles) assignments. Identity, mailbox, and provider fields are read-only, since they're synced from your provider. Only provided fields change, and a setting value of `default` clears the account override so it inherits from a higher level. Changing `roles` additionally requires role-management permission, and a tenant-scoped administrator can only grant roles they're allowed to bind themselves, within their own tenants. Be careful: nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.","tags":["Accounts"],"parameters":[{"in":"path","name":"id","schema":{"description":"The encoded ID of the account to retrieve. Format: `acct.1.`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"The encoded ID of the account to retrieve. Format: `acct.1.`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountBody"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIAccount"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests: the client has exceeded a rate limit and should retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Bulk Accounts > Applies up to 200 account update operations in one request, best-effort with per-item results in request order (\`results\[i]\` corresponds to \`operations\[i]\`). A well-formed envelope always returns 200; individual failures are reported in \`results\[]\`. ```json {"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Accounts","description":"**Overview**\n\nThe Accounts API provides programmatic access to the directory accounts synced from your Google or Microsoft tenant. List and filter accounts, retrieve one by its encoded ID, and update VIP status, licenses, setting overrides, and role assignments. Each account exposes identity and contact fields, [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation) status, licenses, effective product settings with the [layer they resolve from](https://docs.material.security/learn-more/administration/settings-hierarchy), mailbox status, and provider status.\n\nFour endpoints make up the Accounts API:\n\n* **[List Accounts](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts)** (`GET /api/v1/accounts`): filter, sort, and page through accounts\n* **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** (`GET /api/v1/accounts/{id}`): retrieve a single account by its encoded ID\n* **[Update Account](https://docs.material.security/reference/api-v1/accounts#patch-api-v1-accounts-id)** (`PATCH /api/v1/accounts/{id}`): update an account's VIP designation, licenses, setting overrides, and role assignments\n* **[Bulk Accounts](https://docs.material.security/reference/api-v1/accounts#post-api-v1-accounts-bulk)** (`POST /api/v1/accounts/bulk`): apply up to 200 account update operations in one request\n\n**Filtering**\n\nList accepts `search` (a loose match on name or email), `email`, `type` (`google` or `microsoft`), `vip`, `license`, `licensed`, `group`, `mailboxStatus`, `hasAnyRole`, `role`, `providerStatus`, and `includeMaterialSecuritySupportAdmins`. Per-setting filters use dotted params, for example `setting.emailThreatRemediation=on`, and take `on`, `off`, or `overridden` (the account defines its own override). Comma-separated values match any of the listed values within a single filter, and each filter you add narrows the result set further.\n\nMaterial support admins are excluded by default. Pass `includeMaterialSecuritySupportAdmins=true` to list them.\n\n**Sorting**\n\nSort with `?sort=:asc|desc`. Supported fields: `displayName` (default), `email`, and `mailbox.messageCount`.\n\n**The `include` Parameter**\n\nBy default, account responses return identity, VIP, licenses, roles, settings, mailbox, and provider fields. Pass **`include=groups`** on **[Get Account](https://docs.material.security/reference/api-v1/accounts#get-api-v1-accounts-id)** to also return the account's group memberships. The list endpoint doesn't take `include`; filter by `group` instead, or page a group's members at **[List Group Members](https://docs.material.security/reference/api-v1/groups#get-api-v1-groups-id-members)**.\n\n**Updating an Account**\n\nIdentity, mailbox, and provider fields are synced from your provider and read-only. What you can write is `vip`, `licenses`, `settings`, and `roles`, and only fields present in the body change.\n\nEach setting takes `on`, `off`, or `default`. Setting a value to `default` clears the [account-level override](https://docs.material.security/learn-more/administration/group-and-account-customization) so the account inherits from its group, its tenant, or the product default again.\n\nChanging `roles` additionally requires role-management permission, and you can only grant [roles](https://docs.material.security/learn-more/administration/admin-roles) you're allowed to bind yourself: a tenant-scoped administrator can't grant Super Admin, or grant anything outside their own tenants. Be careful here. Nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.\n\n**Response Structure**\n\nList responses follow the standard two-part structure: a `meta` object (with `totalCount`, `limit`, `hasMore`, and `nextCursor`) and an `items` array of account objects.\n\n**Bulk** responses are shaped differently. They return `results`, one entry per operation in request order, so `results[i]` corresponds to `operations[i]`, plus a `meta` object counting how many succeeded and failed. Operations are applied best-effort: a well-formed envelope always returns 200, and individual failures are reported in `results[]` rather than failing the request.\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"BulkAccountsBody":{"title":"BulkAccountsBody","type":"object","properties":{"operations":{"description":"Up to 200 operations, applied best-effort with per-item results.","minItems":1,"maxItems":200,"type":"array","items":{"$ref":"#/components/schemas/BulkAccountOperation"}}},"required":["operations"]},"BulkAccountOperation":{"title":"BulkAccountOperation","type":"object","properties":{"method":{"description":"The operation to apply. Only `update` is supported.","type":"string","const":"update"},"id":{"description":"The encoded ID of the account to update.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"body":{"$ref":"#/components/schemas/UpdateAccountBody"}},"required":["method","id","body"]},"UpdateAccountBody":{"title":"UpdateAccountBody","type":"object","properties":{"vip":{"description":"VIP designation and its aliases. Only provided sub-fields change.","$ref":"#/components/schemas/UpdateAccountVip"},"licenses":{"description":"License allocation and the require-mailbox policy.","$ref":"#/components/schemas/UpdateAccountLicenses"},"settings":{"description":"Per-account setting overrides. Only provided settings change.","$ref":"#/components/schemas/UpdateAccountSettings"},"roles":{"description":"[Roles](https://docs.material.security/learn-more/administration/admin-roles) to grant or revoke on this account. Requires role-management permission.","$ref":"#/components/schemas/UpdateRoles"}}},"UpdateAccountVip":{"title":"UpdateAccountVip","type":"object","properties":{"enabled":{"description":"Mark (true) or unmark (false) the account as a VIP.","type":"boolean"},"emailAliases":{"description":"Replace the VIP email aliases. An empty array clears them.","type":"array","items":{"type":"string"}},"displayNames":{"description":"Replace the VIP display names. An empty array clears them.","type":"array","items":{"type":"string"}}}},"UpdateAccountLicenses":{"title":"UpdateAccountLicenses","type":"object","properties":{"values":{"description":"The complete set of licenses the account should end up with, not a list of changes to apply. Include at most one tier, `essentials` (Essentials) or `advanced` (Advanced), and optionally `ato_resilience` (ATO Resilience) alongside it. Send `[]` to allocate none, or `\"default\"` to inherit from a higher level.","anyOf":[{"type":"array","items":{"type":"string","enum":["essentials","advanced","ato_resilience"]}},{"type":"string","const":"default"}]},"requireMailbox":{"description":"Set `requireMailbox` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]}}},"UpdateAccountSettings":{"title":"UpdateAccountSettings","type":"object","properties":{"emailSync":{"description":"Set `emailSync` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"fileSync":{"description":"Set `fileSync` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"emailThreatRemediation":{"description":"Set `emailThreatRemediation` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"fileRemediation":{"description":"Set `fileRemediation` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"sensitiveEmailRedaction":{"description":"Set `sensitiveEmailRedaction` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"passwordResetProtection":{"description":"Set `passwordResetProtection` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"oauthAppRemediation":{"description":"Set `oauthAppRemediation` to `on` or `off`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["on","off","default"]},"emailBombProtection":{"description":"Set `emailBombProtection` to `enabled`, `detection_only`, or `disabled`, or to `default` to clear the account override so it inherits from a higher level.","type":"string","enum":["enabled","detection_only","disabled","default"]}}},"UpdateRoles":{"title":"UpdateRoles","description":"Role assignment changes. Only roles named in `assign` or `remove` are affected, so this is not a full-set replacement. Be careful: nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.","type":"object","properties":{"assign":{"description":"Roles to grant. Only the listed roles are touched.","type":"array","items":{"$ref":"#/components/schemas/APIRoleAssignment"}},"remove":{"description":"Roles to revoke, at every scope the account or group holds them. There is no per-tenant removal, so to narrow a role rather than drop it, re-assign it with a shorter `tenants` list instead. Removing a role that isn't held does nothing, and a role inherited from a group must be removed on that group. Listing an ID in both `assign` and `remove` returns a 400.","type":"array","items":{"type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]}}}},"APIRoleAssignment":{"title":"APIRoleAssignment","type":"object","properties":{"id":{"description":"Role ID. The ID carries the role's scope: tenant-scoped IDs (for example `analyst`) require `tenants`, while IDs that apply everywhere (for example `global_analyst`, `super_admin`, `tenant_enroller`) take none. Call `GET /roles` for the IDs available on your instance.","type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]},"tenants":{"description":"Tenants to grant the role in, as encoded tenant IDs (format `tnt.1.`). Required for tenant-scoped IDs, rejected for the others. Assigning a tenant-scoped role the account or group already holds replaces its tenant list.","type":"array","items":{"type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"}}},"required":["id"]},"BulkAccountsResponse":{"title":"BulkAccountsResponse","type":"object","properties":{"results":{"description":"Per-operation result, in the same order as the request.","type":"array","items":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"ok"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"id":{"type":"string"},"account":{"$ref":"#/components/schemas/APIAccount"}},"required":["status","index","id","account"]},{"type":"object","properties":{"status":{"type":"string","const":"error"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"id":{"type":"string"},"error":{"type":"string"}},"required":["status","index","id","error"]}],"type":"object"}},"meta":{"description":"Aggregate counts across all operations.","type":"object","properties":{"succeeded":{"description":"Number of operations that succeeded.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"description":"Number of operations that failed.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["succeeded","failed"]}},"required":["results","meta"]},"APIAccount":{"title":"APIAccount","description":"A directory account (person or mailbox) synced from Google or Microsoft.","type":"object","properties":{"id":{"description":"The encoded account ID. Format: `acct.1.`.","type":"string"},"type":{"description":"The provider the account is synced from: `google` or `microsoft`.","type":"string","enum":["google","microsoft"]},"displayName":{"description":"Display name of the account holder.","type":"string"},"givenName":{"description":"Given (first) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"familyName":{"description":"Family (last) name; null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"email":{"description":"Primary email address.","type":"string"},"aliases":{"description":"Additional email aliases.","type":"array","items":{"type":"string"}},"organization":{"description":"The organization on the account's directory record. Read-only, and null if your provider doesn't supply one.","anyOf":[{"type":"string"},{"type":"null"}]},"vip":{"$ref":"#/components/schemas/APIVip"},"licenses":{"$ref":"#/components/schemas/APILicenses"},"roles":{"description":"The [roles](https://docs.material.security/learn-more/administration/admin-roles) in effect on this account, both assigned directly and inherited from groups. A role held at a broader scope hides the narrower assignments it supersedes, so this reflects effective access rather than every assignment on record. Empty if the account has no roles. Roles are scoped to this account, so if one person owns several accounts, each reports only its own roles, matching the `role` filter.","type":"array","items":{"$ref":"#/components/schemas/APIAssignedRole"}},"settings":{"$ref":"#/components/schemas/APIAccountSettings"},"mailbox":{"$ref":"#/components/schemas/APIAccountMailbox"},"providerStatus":{"description":"The account's state at your provider: `active`, `suspended`, `archived`, or `deleted`.","type":"string","enum":["active","suspended","archived","deleted"]},"lastSyncedAt":{"description":"When Material last synced this account, in ISO 8601 format. Null if it has never synced.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"groups":{"description":"Group memberships; populated only when `include=groups`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}}},"required":["meta","items"]}},"required":["id","type","displayName","givenName","familyName","email","aliases","organization","vip","licenses","roles","settings","mailbox","providerStatus","lastSyncedAt"]},"APIVip":{"title":"APIVip","type":"object","properties":{"enabled":{"description":"Whether the account is marked as a [VIP](https://docs.material.security/learn-more/risk-areas/email-threats/detect/vip-impersonation).","type":"boolean"},"emailAliases":{"description":"Additional email aliases treated as this VIP.","type":"array","items":{"type":"string"}},"displayNames":{"description":"Additional display names treated as this VIP.","type":"array","items":{"type":"string"}}},"required":["enabled","emailAliases","displayNames"]},"APILicenses":{"title":"APILicenses","type":"object","properties":{"values":{"description":"The licenses active on this account: `essentials` (Essentials), `advanced` (Advanced), or `ato_resilience` (ATO Resilience). An account carries at most one tier, `essentials` or `advanced`, and can add `ato_resilience` alongside it.","type":"array","items":{"type":"string","enum":["essentials","advanced","ato_resilience"]}},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"},"requireMailbox":{"title":"APIBooleanSetting","description":"Whether an account needs a provisioned mailbox before Material assigns it a license. Shown as **Require mailbox for license assignment** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"}},"required":["values","source","requireMailbox"]},"APIGroupRef":{"title":"APIGroupRef","type":"object","properties":{"id":{"description":"The encoded group ID. Format: `grp.1.`.","type":"string"},"name":{"description":"The group's display name. Null if Material doesn't have one.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"APIBooleanSetting":{"title":"APIBooleanSetting","type":"object","properties":{"enabled":{"description":"Whether the setting is enabled for this account.","type":"boolean"},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["enabled","source"]},"APIAssignedRole":{"title":"APIAssignedRole","type":"object","properties":{"id":{"description":"Role ID. The ID carries the role's scope: tenant-scoped IDs (for example `analyst`) require `tenants`, while IDs that apply everywhere (for example `global_analyst`, `super_admin`, `tenant_enroller`) take none. Call `GET /roles` for the IDs available on your instance.","type":"string","enum":["super_admin","global_analyst","global_issue_responder","global_phishing_simulation_admin","global_analytics_admin","global_settings_admin","tenant_admin","content_admin","drive_content_admin","email_content_admin","analyst","issue_responder","ediscovery_admin","phishing_simulation_admin","analytics_admin","settings_admin","tenant_enroller"]},"tenants":{"description":"Tenants the role applies to, as encoded tenant IDs (format `tnt.1.`), for tenant-scoped IDs only. `\"all\"` means the role was granted across every tenant, which you can read but not assign through this API.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"all"}]},"source":{"description":"Where the assignment comes from: `direct` (on this account), `group` (inherited from `groupId`, and changeable only on that group), or `tenant` (granted to everyone in the tenant).","type":"string","enum":["direct","group","tenant"]},"groupId":{"description":"The granting group; present only when `source` is `group`.","type":"string"}},"required":["id","source"]},"APIAccountSettings":{"title":"APIAccountSettings","description":"Each product setting's effective value for this account, with the layer it resolves from. See [Group and Account Customization](https://docs.material.security/learn-more/administration/group-and-account-customization) for how overrides work.","type":"object","properties":{"emailSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's mailbox. Shown as **Mailbox Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileSync":{"title":"APIBooleanSetting","description":"Whether Material syncs this account's Google Drive files. Shown as **My Drive Syncing** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailThreatRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates email threats found in this mailbox. Shown as **Email Threat Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"fileRemediation":{"title":"APIBooleanSetting","description":"Whether Material remediates risky sharing on this account's files. Shown as **File Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"sensitiveEmailRedaction":{"title":"APIBooleanSetting","description":"Whether Material redacts sensitive email in this mailbox. Shown as **Sensitive Email Redaction** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"passwordResetProtection":{"title":"APIBooleanSetting","description":"Whether Material holds password reset and app signup email for this account during a lockdown. Shown as **Password Reset & App Signup Protection** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"oauthAppRemediation":{"title":"APIBooleanSetting","description":"Whether Material revokes this account's grants when an OAuth app carries a revoke policy. Shown as **OAuth App Remediation** on an account's **Settings** tab.","$ref":"#/components/schemas/APIBooleanSetting"},"emailBombProtection":{"title":"APIModeSetting","description":"How Material handles a sudden surge of email to this account. Shown as **[Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection)** on an account's **Settings** tab.","$ref":"#/components/schemas/APIModeSetting"}},"required":["emailSync","fileSync","emailThreatRemediation","fileRemediation","sensitiveEmailRedaction","passwordResetProtection","oauthAppRemediation","emailBombProtection"]},"APIModeSetting":{"title":"APIModeSetting","type":"object","properties":{"mode":{"description":"How [Email Bomb Protection](https://docs.material.security/learn-more/risk-areas/email-threats/detect/material-email-threat-detections/email-bomb-protection) is applied to this account: `enabled` (detect and remediate), `detection_only` (detect without remediating), or `disabled`.","type":"string","enum":["enabled","detection_only","disabled"]},"source":{"description":"Which layer the effective value comes from: `account`, `group`, `tenant`, or `default`. See [Settings Hierarchy](https://docs.material.security/learn-more/administration/settings-hierarchy) for how the layers resolve.","type":"string","enum":["account","group","tenant","default"]},"sourceGroups":{"description":"The group(s) responsible for the value; present only when `source` is `group`.","type":"array","items":{"$ref":"#/components/schemas/APIGroupRef"}},"sourceTenant":{"description":"The tenant responsible for the value, as an encoded tenant ID (format `tnt.1.`). Present only when `source` is `tenant`.","type":"string"}},"required":["mode","source"]},"APIAccountMailbox":{"title":"APIAccountMailbox","type":"object","properties":{"status":{"description":"Whether the account's mailbox is `enabled` or `disabled`. Null when Material hasn't synced the mailbox or can't determine its state.","anyOf":[{"type":"string","enum":["enabled","disabled"]},{"type":"null"}]},"messageCount":{"description":"Approximate number of messages in the mailbox. Null if unknown.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["status","messageCount"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/accounts/bulk":{"post":{"operationId":"bulkAccounts","summary":"Bulk Accounts","description":"Applies up to 200 account update operations in one request, best-effort with per-item results in request order (`results[i]` corresponds to `operations[i]`). A well-formed envelope always returns 200; individual failures are reported in `results[]`.","tags":["Accounts"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAccountsBody"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAccountsResponse"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests: the client has exceeded a rate limit and should retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.material.security/reference/api-v1/accounts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.