# Create an account group

Creates an account group for a user or a business.
An account group aggregates the accounts within it for tax calculation and regulatory reporting purposes and holds positions in the form of cash; the official securities account number is assigned at account group level. The account group is created with status `PENDING_APPROVAL` and switches to `ACTIVE` once onboarding is complete.
See the Creating account groups guide ([TOL](https://docs.upvest.co/products/tol/guides/accounts/accounts_create_account_groups) / [BYOL](https://docs.upvest.co/products/byol/guides/accounts/accounts_create_account_groups)) for implementation details.

Endpoint: POST /account_groups
Version: 1.156.0
Security: oauth-client-credentials

## Security:

  - `oauth-client-credentials` (unknown)
    oauth2 scopes: accounts:admin

## Header parameters:

  - `idempotency-key` (string, required)
    A UUID to be used as an idempotency key.  This prevents a duplicate request from being replayed.
https://docs.upvest.co/documentation/concepts/api_concepts/idempotency

  - `upvest-client-id` (string, required)
    Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).

  - `Authorization` (string, required)
    Bearer (access) token from the OAuth flow with correct scopes.
https://datatracker.ietf.org/doc/html/rfc6750

  - `signature` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

  - `signature-input` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

  - `upvest-api-version` (string)
    Upvest API version (Note: Do not include quotation marks)

## Request fields (application/json):

  - `user_id` (string, required)
    Unique identifier of the user, as a UUID.

  - `type` (string, required)
    Account group type.
* PERSONAL - Account group of a person holding assets on their own behalf.
* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.
* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.
* ISA - Account group of a UK resident holding assets in an individual savings account.
* CHILD - Account group of a child user holding assets in a child account.
* JOINT - Account group legally and beneficially owned by exactly 2 users. The user the account group is created with becomes the first owner and receives an OWNER role. The second owner is added by creating an OWNER role for them (POST /roles); no further owners can be added. The account group activates only once both OWNER roles are active.
    Enum: "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD", "JOINT"

  - `securities_account_number` (string)
    Official securities account number, assigned at account group level. A string of 7 to 12 digits.

  - `business_id` (string, required)
    Unique identifier for the business.

  - `type` (string, required)
    Account group type.
* BUSINESS - Account group of a business holding assets.
    Enum: "BUSINESS"

## Request examples:

  - `User account group` (unknown)

  - `Joint account group` (unknown)

  - `Business account group` (unknown)

## Response 200:

  - `200` (unknown)
    Account group created.

## Response 200 fields (application/json):

  - `id` (string, required)
    Universally Unique Identifier (UUID) of the account group.

  - `created_at` (string, required)
    Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `updated_at` (string, required)
    Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `users` (array, required)
    The users associated with the account group, each with their relation type.

  - `users.id` (string)
    Unique identifier of the user, as a UUID.

  - `users.type` (string)
    Relation of the user to the account group.
* `OWNER` — The user owns the account group. A `JOINT` account group has exactly 2 `OWNER` users.
* `CHILD` — The user is the child in a child account group.
* `GUARDIAN` — The user is a guardian of a child account group.
    Enum: "OWNER", "CHILD", "GUARDIAN"

  - `status` (string, required)
    Status of the account group.
* `PENDING_APPROVAL` — Account group approval is pending — the account group is visible through our API but cannot be acted on.
* `ACTIVE` — Account group is active — full functionality of the Investment API is accessible.
* `CLOSING` — Account group is closing.
* `CLOSED` — Account group is closed.
* `LOCKED` — Account group is locked for all actions.
    Enum: "PENDING_APPROVAL", "ACTIVE", "CLOSING", "CLOSED", "LOCKED"

  - `type` (string, required)
    Account group type.
* PERSONAL - Account group of a person holding assets on their own behalf.
* LEGAL_ENTITY - Account group of a legal entity holding assets on behalf of their users.
* FRENCH_PEA - Account group of a french resident holding assets in Plan d'Epargne en Actions.
* ISA - Account group of a UK resident holding assets in an individual savings account.
* CHILD - Account group of a child user holding assets in a child account.
* JOINT - Account group legally and beneficially owned by exactly 2 users. The user the account group is created with becomes the first owner and receives an OWNER role. The second owner is added by creating an OWNER role for them (POST /roles); no further owners can be added. The account group activates only once both OWNER roles are active.
    Enum: "PERSONAL", "LEGAL_ENTITY", "FRENCH_PEA", "ISA", "CHILD", "JOINT"

  - `securities_account_number` (string, required)
    Official securities account number, assigned at account group level. A string of 7 to 12 digits.

  - `business_id` (string, required)
    Unique identifier for the business.

  - `type` (string, required)
    Account group type.
* BUSINESS - Account group of a business holding assets.
    Enum: "BUSINESS"

## Response 200 headers (application/json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 400:

  - `400` (unknown)
    Bad Request. The incoming request had a malformed parameter/object.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 400 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 401:

  - `401` (unknown)
    Unauthorized. The caller has not been authenticated.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 401 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 403:

  - `403` (unknown)
    Forbidden. The caller has been authenticated but is not allowed to take the requested action.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 403 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 404:

  - `404` (unknown)
    Not Found. The requested resource could not be found.

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 404 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 406:

  - `406` (unknown)
    Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value.

## Response 406 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 406 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 429:

  - `429` (unknown)
    Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 429 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 500:

  - `500` (unknown)
    Internal Server Error. The service encountered an unexpected error.

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 500 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 503:

  - `503` (unknown)
    Service Unavailable. The service handling for this request cannot be reached at this time.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 503 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 504:

  - `504` (unknown)
    Gateway Timeout. The service gateway has reached its internal timeout.

## Response 504 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 504 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 200 examples:

  - `User account group` (unknown)

  - `Joint account group` (unknown)

  - `Business account group` (unknown)