Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 status, licenses, effective product settings with the layer they resolve from, mailbox status, and provider status.

Four endpoints make up the Accounts API:

  • List Accounts (GET /api/v1/accounts): filter, sort, and page through accounts

  • Get Account (GET /api/v1/accounts/{id}): retrieve a single account by its encoded ID

  • Update Account (PATCH /api/v1/accounts/{id}): update an account's VIP designation, licenses, setting overrides, and role assignments

  • Bulk Accounts (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=<field>: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 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.

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 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 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.

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

get

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.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Query parameters
cursorstringOptional

The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.

Example: eyJ2IjoxLCJvIjoyNSwibCI6MjV9
limitintegerOptional

The maximum number of items to return per page.

Example: 25
searchstringOptional

Loose match on the account name or email address.

Example: jane
emailstringOptional

Filter to these exact email addresses, comma-separated.

Example: jane@example.com
typestring · enumOptional

Filter by the provider the account is synced from: google or microsoft.

Example: googlePossible values:
vipbooleanOptional

Filter to accounts marked as a VIP (true) or not marked (false).

licensestringOptional

Filter to accounts holding any of these active licenses, comma-separated.

Example: advanced,ato_resilience
licensedbooleanOptional

Filter to accounts with (true) or without (false) any active license.

groupstringOptional

Filter to members of any of these groups, as comma-separated encoded group IDs (format grp.1.<base64>).

Example: grp.1.ZXhhbXBsZV9pZF8xMjM
mailboxStatusstring · enumOptional

Filter by mailbox status: enabled or disabled.

Example: enabledPossible values:
hasAnyRolebooleanOptional

Filter to accounts that hold at least one role (true) or none at all (false).

providerStatusstring · enumOptional

Filter by the account's state at your provider: active, suspended, archived, or deleted. One value only.

Example: suspendedPossible values:
includeMaterialSecuritySupportAdminsbooleanOptional

Include Material support admins, the Material employees with support access to your instance. They are excluded by default.

rolestringOptional

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.

Example: tenant_admin,analyst
setting.emailSyncstring · enumOptional

Filter by the effective emailSync setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
setting.fileSyncstring · enumOptional

Filter by the effective fileSync setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
setting.emailThreatRemediationstring · enumOptional

Filter by the effective emailThreatRemediation setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
setting.fileRemediationstring · enumOptional

Filter by the effective fileRemediation setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
setting.sensitiveEmailRedactionstring · enumOptional

Filter by the effective sensitiveEmailRedaction setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
setting.passwordResetProtectionstring · enumOptional

Filter by the effective passwordResetProtection setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
setting.oauthAppRemediationstring · enumOptional

Filter by the effective oauthAppRemediation setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
setting.emailBombProtectionstring · enumOptional

Filter by the effective emailBombProtection setting: on, off, or overridden (the account defines its own override, whatever the value).

Possible values:
sortstringOptional

Sort field, e.g. displayName:asc or mailbox.messageCount:desc. A single field only.

Example: displayName:asc
Responses
200

Successful response

application/json
get/api/v1/accounts
GET /api/v1/accounts HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Accept: */*

{
  "meta": {
    "totalCount": 1,
    "limit": 1,
    "hasMore": true,
    "nextCursor": "text"
  },
  "items": [
    {
      "id": "acct.1.ZXhhbXBsZV9pZF8xMjM",
      "type": "google",
      "displayName": "Jane Doe",
      "givenName": "Jane",
      "familyName": "Doe",
      "email": "jane@example.com",
      "aliases": [
        "jane.doe@example.com"
      ],
      "organization": "Engineering",
      "vip": {
        "enabled": true,
        "emailAliases": [],
        "displayNames": []
      },
      "licenses": {
        "values": [
          "advanced",
          "ato_resilience"
        ],
        "source": "group",
        "sourceGroups": [
          {
            "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
            "name": "Engineering"
          }
        ],
        "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
        "requireMailbox": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        }
      },
      "roles": [
        {
          "id": "analyst",
          "tenants": [
            "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          ],
          "source": "direct",
          "groupId": "grp.1.ZXhhbXBsZV9pZF8xMjM"
        }
      ],
      "settings": {
        "emailSync": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        },
        "fileSync": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        },
        "emailThreatRemediation": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        },
        "fileRemediation": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        },
        "sensitiveEmailRedaction": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        },
        "passwordResetProtection": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        },
        "oauthAppRemediation": {
          "enabled": true,
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        },
        "emailBombProtection": {
          "mode": "enabled",
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        }
      },
      "mailbox": {
        "status": "enabled",
        "messageCount": 3543
      },
      "providerStatus": "active",
      "lastSyncedAt": "2026-01-01T00:00:00.000Z",
      "groups": {
        "meta": {
          "totalCount": 1,
          "limit": 1,
          "hasMore": true,
          "nextCursor": "text"
        },
        "items": [
          {
            "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
            "name": "Engineering"
          }
        ]
      }
    }
  ]
}

Get Account

get

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.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Path parameters
idstringRequired

The encoded ID of the account to retrieve. Format: acct.1.<base64>.

Example: acct.1.ZXhhbXBsZV9pZF8xMjMPattern: ^[a-z]{1,6}\.[0-9]{1,2}\.[A-Za-z0-9_-]+$
Query parameters
includestringOptional

Comma-separated list of extra fields to return. Supported: groups, the account's group memberships.

Example: groups
Responses
200

Successful response

application/json

A directory account (person or mailbox) synced from Google or Microsoft.

idstringRequired

The encoded account ID. Format: acct.1.<base64>.

Example: acct.1.ZXhhbXBsZV9pZF8xMjM
typestring · enumRequired

The provider the account is synced from: google or microsoft.

Example: googlePossible values:
displayNamestringRequired

Display name of the account holder.

Example: Jane Doe
givenNamestring · nullableRequired

Given (first) name; null if unavailable.

Example: Jane
familyNamestring · nullableRequired

Family (last) name; null if unavailable.

Example: Doe
emailstringRequired

Primary email address.

Example: jane@example.com
aliasesstring[]Required

Additional email aliases.

Example: ["jane.doe@example.com"]
organizationstring · nullableRequired

The organization on the account's directory record. Read-only, and null if your provider doesn't supply one.

Example: Engineering
providerStatusstring · enumRequired

The account's state at your provider: active, suspended, archived, or deleted.

Example: activePossible values:
lastSyncedAtstring · date-time · nullableRequired

When Material last synced this account, in ISO 8601 format. Null if it has never synced.

get/api/v1/accounts/{id}
GET /api/v1/accounts/{id} HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Accept: */*

{
  "id": "acct.1.ZXhhbXBsZV9pZF8xMjM",
  "type": "google",
  "displayName": "Jane Doe",
  "givenName": "Jane",
  "familyName": "Doe",
  "email": "jane@example.com",
  "aliases": [
    "jane.doe@example.com"
  ],
  "organization": "Engineering",
  "vip": {
    "enabled": true,
    "emailAliases": [],
    "displayNames": []
  },
  "licenses": {
    "values": [
      "advanced",
      "ato_resilience"
    ],
    "source": "group",
    "sourceGroups": [
      {
        "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
        "name": "Engineering"
      }
    ],
    "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
    "requireMailbox": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    }
  },
  "roles": [
    {
      "id": "analyst",
      "tenants": [
        "tnt.1.ZXhhbXBsZV9pZF8xMjM"
      ],
      "source": "direct",
      "groupId": "grp.1.ZXhhbXBsZV9pZF8xMjM"
    }
  ],
  "settings": {
    "emailSync": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "fileSync": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "emailThreatRemediation": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "fileRemediation": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "sensitiveEmailRedaction": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "passwordResetProtection": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "oauthAppRemediation": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "emailBombProtection": {
      "mode": "enabled",
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    }
  },
  "mailbox": {
    "status": "enabled",
    "messageCount": 3543
  },
  "providerStatus": "active",
  "lastSyncedAt": "2026-01-01T00:00:00.000Z",
  "groups": {
    "meta": {
      "totalCount": 1,
      "limit": 1,
      "hasMore": true,
      "nextCursor": "text"
    },
    "items": [
      {
        "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
        "name": "Engineering"
      }
    ]
  }
}

Update Account

patch

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.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Path parameters
idstringRequired

The encoded ID of the account to retrieve. Format: acct.1.<base64>.

Example: acct.1.ZXhhbXBsZV9pZF8xMjMPattern: ^[a-z]{1,6}\.[0-9]{1,2}\.[A-Za-z0-9_-]+$
Body
Responses
200

Successful response

application/json

A directory account (person or mailbox) synced from Google or Microsoft.

idstringRequired

The encoded account ID. Format: acct.1.<base64>.

Example: acct.1.ZXhhbXBsZV9pZF8xMjM
typestring · enumRequired

The provider the account is synced from: google or microsoft.

Example: googlePossible values:
displayNamestringRequired

Display name of the account holder.

Example: Jane Doe
givenNamestring · nullableRequired

Given (first) name; null if unavailable.

Example: Jane
familyNamestring · nullableRequired

Family (last) name; null if unavailable.

Example: Doe
emailstringRequired

Primary email address.

Example: jane@example.com
aliasesstring[]Required

Additional email aliases.

Example: ["jane.doe@example.com"]
organizationstring · nullableRequired

The organization on the account's directory record. Read-only, and null if your provider doesn't supply one.

Example: Engineering
providerStatusstring · enumRequired

The account's state at your provider: active, suspended, archived, or deleted.

Example: activePossible values:
lastSyncedAtstring · date-time · nullableRequired

When Material last synced this account, in ISO 8601 format. Null if it has never synced.

patch/api/v1/accounts/{id}
PATCH /api/v1/accounts/{id} HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 453

{
  "vip": {
    "enabled": true,
    "emailAliases": [],
    "displayNames": []
  },
  "licenses": {
    "values": [
      "advanced",
      "ato_resilience"
    ],
    "requireMailbox": "on"
  },
  "settings": {
    "emailSync": "on",
    "fileSync": "on",
    "emailThreatRemediation": "on",
    "fileRemediation": "on",
    "sensitiveEmailRedaction": "on",
    "passwordResetProtection": "on",
    "oauthAppRemediation": "on",
    "emailBombProtection": "enabled"
  },
  "roles": {
    "assign": [
      {
        "id": "analyst",
        "tenants": [
          "tnt.1.ZXhhbXBsZV9pZF8xMjM"
        ]
      }
    ],
    "remove": [
      "analyst"
    ]
  }
}
{
  "id": "acct.1.ZXhhbXBsZV9pZF8xMjM",
  "type": "google",
  "displayName": "Jane Doe",
  "givenName": "Jane",
  "familyName": "Doe",
  "email": "jane@example.com",
  "aliases": [
    "jane.doe@example.com"
  ],
  "organization": "Engineering",
  "vip": {
    "enabled": true,
    "emailAliases": [],
    "displayNames": []
  },
  "licenses": {
    "values": [
      "advanced",
      "ato_resilience"
    ],
    "source": "group",
    "sourceGroups": [
      {
        "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
        "name": "Engineering"
      }
    ],
    "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
    "requireMailbox": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    }
  },
  "roles": [
    {
      "id": "analyst",
      "tenants": [
        "tnt.1.ZXhhbXBsZV9pZF8xMjM"
      ],
      "source": "direct",
      "groupId": "grp.1.ZXhhbXBsZV9pZF8xMjM"
    }
  ],
  "settings": {
    "emailSync": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "fileSync": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "emailThreatRemediation": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "fileRemediation": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "sensitiveEmailRedaction": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "passwordResetProtection": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "oauthAppRemediation": {
      "enabled": true,
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    },
    "emailBombProtection": {
      "mode": "enabled",
      "source": "group",
      "sourceGroups": [
        {
          "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
          "name": "Engineering"
        }
      ],
      "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
    }
  },
  "mailbox": {
    "status": "enabled",
    "messageCount": 3543
  },
  "providerStatus": "active",
  "lastSyncedAt": "2026-01-01T00:00:00.000Z",
  "groups": {
    "meta": {
      "totalCount": 1,
      "limit": 1,
      "hasMore": true,
      "nextCursor": "text"
    },
    "items": [
      {
        "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
        "name": "Engineering"
      }
    ]
  }
}

Bulk Accounts

post

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[].

Authorizations
x-material-client-secretstringRequired

Material Security API key

Body
Responses
200

Successful response

application/json
resultsone of[]Required

Per-operation result, in the same order as the request.

or
post/api/v1/accounts/bulk
POST /api/v1/accounts/bulk HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 529

{
  "operations": [
    {
      "method": "text",
      "id": "acct.1.ZXhhbXBsZV9pZF8xMjM",
      "body": {
        "vip": {
          "enabled": true,
          "emailAliases": [],
          "displayNames": []
        },
        "licenses": {
          "values": [
            "advanced",
            "ato_resilience"
          ],
          "requireMailbox": "on"
        },
        "settings": {
          "emailSync": "on",
          "fileSync": "on",
          "emailThreatRemediation": "on",
          "fileRemediation": "on",
          "sensitiveEmailRedaction": "on",
          "passwordResetProtection": "on",
          "oauthAppRemediation": "on",
          "emailBombProtection": "enabled"
        },
        "roles": {
          "assign": [
            {
              "id": "analyst",
              "tenants": [
                "tnt.1.ZXhhbXBsZV9pZF8xMjM"
              ]
            }
          ],
          "remove": [
            "analyst"
          ]
        }
      }
    }
  ]
}
{
  "results": [
    {
      "status": "text",
      "index": 1,
      "id": "text",
      "account": {
        "id": "acct.1.ZXhhbXBsZV9pZF8xMjM",
        "type": "google",
        "displayName": "Jane Doe",
        "givenName": "Jane",
        "familyName": "Doe",
        "email": "jane@example.com",
        "aliases": [
          "jane.doe@example.com"
        ],
        "organization": "Engineering",
        "vip": {
          "enabled": true,
          "emailAliases": [],
          "displayNames": []
        },
        "licenses": {
          "values": [
            "advanced",
            "ato_resilience"
          ],
          "source": "group",
          "sourceGroups": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ],
          "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
          "requireMailbox": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          }
        },
        "roles": [
          {
            "id": "analyst",
            "tenants": [
              "tnt.1.ZXhhbXBsZV9pZF8xMjM"
            ],
            "source": "direct",
            "groupId": "grp.1.ZXhhbXBsZV9pZF8xMjM"
          }
        ],
        "settings": {
          "emailSync": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          },
          "fileSync": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          },
          "emailThreatRemediation": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          },
          "fileRemediation": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          },
          "sensitiveEmailRedaction": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          },
          "passwordResetProtection": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          },
          "oauthAppRemediation": {
            "enabled": true,
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          },
          "emailBombProtection": {
            "mode": "enabled",
            "source": "group",
            "sourceGroups": [
              {
                "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
                "name": "Engineering"
              }
            ],
            "sourceTenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM"
          }
        },
        "mailbox": {
          "status": "enabled",
          "messageCount": 3543
        },
        "providerStatus": "active",
        "lastSyncedAt": "2026-01-01T00:00:00.000Z",
        "groups": {
          "meta": {
            "totalCount": 1,
            "limit": 1,
            "hasMore": true,
            "nextCursor": "text"
          },
          "items": [
            {
              "id": "grp.1.ZXhhbXBsZV9pZF8xMjM",
              "name": "Engineering"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "succeeded": 1,
    "failed": 1
  }
}
PreviousErrors and Troubleshooting
NextGroups

Last updated

Was this helpful?