> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a custody account group > Creates a new custody account group for the calling entity. If `accountIds` is provided, those accounts are assigned to the new group in the same transaction. Accounts must belong to the caller's entity; accounts already assigned to a different group are reassigned. ## OpenAPI ````yaml openapi/accounts.yaml post /v1/accounts/groups openapi: 3.0.2 info: version: 1.0.0 title: Accounts (Stablecoin) API description: > Circle's Accounts API provides endpoints for managing stablecoin accounts -- including transfers, withdrawals, deposits, wire and ACH bank accounts, and blockchain addresses. An **Account** is a general representation of a ledger or custody object that holds balances. It can be a business account, a stablecoin account ledger for an end user, an extra sub-ledger, or any future custody solution. license: name: Circle License url: https://circle.com/terms servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Accounts description: Manage accounts. - name: Account Groups description: Manage custody account groups and their memberships. - name: Transactions description: | Get a unified, customer-friendly view of account transaction activity. - name: Transfers description: Manage account transfers. - name: Withdrawals description: Manage account bank withdrawals (fiat offramp). - name: Wires description: Manage account bank accounts for wire transfers. - name: ACH description: Manage account bank accounts for ACH transfers. - name: Deposits description: Get information on account bank deposits. - name: Deposit Addresses description: Manage account deposit addresses. - name: Recipient Addresses description: Manage account recipient addresses used for transfers. paths: /v1/accounts/groups: post: tags: - Account Groups summary: Create a custody account group description: | Creates a new custody account group for the calling entity. If `accountIds` is provided, those accounts are assigned to the new group in the same transaction. Accounts must belong to the caller's entity; accounts already assigned to a different group are reassigned. operationId: createAccountGroup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AccountGroupCreationRequest' responses: '201': description: Successfully created the custody account group. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/CreateAccountGroupResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: AccountGroupCreationRequest: type: object required: - idempotencyKey - name properties: idempotencyKey: $ref: '#/components/schemas/IdempotencyKey' name: type: string description: Display name. maxLength: 32 example: Team A accountIds: type: array description: > Optional list of accounts to assign to the new group at creation time. Each account must belong to the caller's entity. Accounts already assigned to another group are reassigned. Max 100 entries. maxItems: 100 items: type: integer example: - 12345 - 12346 - 12347 CreateAccountGroupResponse: title: CreateAccountGroupResponse properties: data: $ref: '#/components/schemas/CustodyAccountGroup' IdempotencyKey: type: string description: >- Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. format: uuid example: ba943ff1-ca16-49b2-ba55-1057e70ca5c7 XRequestId: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde CustodyAccountGroup: type: object description: > A customer-defined grouping of custody accounts owned by a single entity. Each account can belong to at most one group at a time. The `approximateBalanceInUsd` and `accountsPreview` fields are aggregate views populated by the list-groups endpoint. The single-group detail endpoint returns the metadata-only view and omits both fields. required: - id - name - createDate - updateDate properties: id: type: string format: uuid description: Identifier of the custody account group. example: 9c0f1c0d-6c61-4f3d-9b8a-1a3a4b3c5d6e name: type: string description: Display name. maxLength: 32 example: Team A approximateBalanceInUsd: description: > Aggregate USD-equivalent balance across every account in the group. Returned by the list endpoint only. allOf: - $ref: '#/components/schemas/FiatMoneyUsd' accountsPreview: description: > Lightweight summary of member accounts (total count + a few names). Returned by the list endpoint only. allOf: - $ref: '#/components/schemas/AccountsPreview' createDate: description: Timestamp the group was created. allOf: - $ref: '#/components/schemas/UtcTimestamp' updateDate: description: Timestamp the group was last updated. allOf: - $ref: '#/components/schemas/UtcTimestamp' Error: type: object required: - code - message properties: code: type: integer description: > Circle internal status code from the platform `CoreStatusCode` enum (and its domain-specific extensions). **This is not the HTTP status code** — `-1` is the catch-all unknown error, `1`/`2` indicate API parameter problems, `3` is forbidden, `4` is unauthorized, and larger values identify domain-specific failures. Consumers should rely on the HTTP status line for transport-level error class and on this field for the specific Circle error case. example: 2 message: type: string description: >- Internal error message; suitable for logging but not for end-user display. example: API parameter invalid. externalMessage: type: string description: > End-user-displayable error message. Present when the server has generated a customer-facing variant for this error; omitted otherwise. example: The provided amount exceeds the maximum allowed. FiatMoneyUsd: type: object required: - amount - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: description: Currency code. type: string enum: - USD AccountsPreview: type: object description: > Lightweight preview of the accounts assigned to a custody account group. Used by the list-groups endpoint to render an at-a-glance summary without requiring the caller to also page through `/v1/accounts`. required: - totalCount - accountNames properties: totalCount: type: integer description: Total number of accounts assigned to the group. example: 15 accountNames: type: array description: > Sample of member account descriptions, ordered alphabetically and truncated to a small preview size. May be shorter than `totalCount`. items: type: string example: - Operations US - Reserve US - Treasury APAC - Treasury EU - Treasury US UtcTimestamp: type: string description: ISO-8601 UTC date/time format. example: '2020-04-10T02:13:30.000Z' headers: XRequestId: description: > Circle-generated universally unique identifier (UUID v4). Useful for identifying a specific request when communicating with Circle Support. schema: $ref: '#/components/schemas/XRequestId' responses: BadRequest: description: The request cannot be processed due to a client error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 2 message: API parameter invalid. NotAuthorized: description: >- The request has not been applied because it lacks valid authentication credentials. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 4 message: Unauthorized. NotFound: description: The specified resource was not found. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: Not found. InternalServerError: description: >- The server encountered an unexpected condition that prevented it from fulfilling the request. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: -1 message: 'Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4' securitySchemes: bearerAuth: type: http scheme: bearer ````