Skip to main content
POST
Create Virtual Account Group
Any customer can open a virtual account group on an account it owns, provided the API key carries the virtual_accounts scope: on your own account, or, if you are a platform customer, on any of your end-customer accounts and on your own fee-collection account. The account needs an identity profile before onboarding can progress, and a business account also needs an associated person marked as a signer. Opens a group of the given type for an account you own. The body names a type from List Group Types. There is no Idempotency-Key header on this endpoint. It is idempotent on the account and the group type instead: posting the same type for the same account twice returns the group that already exists. The first call returns 201, a call that reuses an existing group returns 200. Branch on the status code, or compare the returned id with the one you already hold. Requires an API key with write access on the virtual_accounts scope, which is separate from accounts.

What the account needs first

Onboarding runs on the account’s identity, so the account needs an identity profile before it can progress. Set it with Update Account. That call also fixes the account’s type, business or individual, which decides what else is required.

Business accounts

A business agreement must be signed by an authorised signer, so the account needs at least one associated person with is_signer: true. Add them with Create Associated Person. That person’s id is then required as signer_id on Submit Agreement Actions.

Individual accounts

Individual accounts have no associated persons at all: an individual account signs as itself. signer_id must be omitted from Submit Agreement Actions; sending one is rejected.

Opening a group before the identity profile is set

You do not have to wait for the identity profile. Opening a group on an account that has none succeeds and returns 201 like any other create. The group carries a requirement naming what is missing, which Get Virtual Account Group returns: Clear it the way you clear any other requirement: set the identity profile with Update Account, then poll. That resumes onboarding on its own. There is no second call to this endpoint, and the group keeps the id you already hold.

Onboarding starts immediately

Creating a group starts provider onboarding, so the group that comes back is not ready to use. A new group starts with status pending and onboarding_status action_needed, and two separate gates have to clear before virtual accounts can be created under it: the provider has to approve onboarding (onboarding_status approved), and Hop has to enable the group (status enabled). onboarding_status is provider-neutral and provider-authoritative: Allowed transitions, as Hop enforces them when the provider reports a change:
  • action_needed → under_review, approved, rejected, closed
  • under_review → action_needed, approved, rejected, closed
  • approved → action_needed, suspended, closed
  • suspended → action_needed, approved, closed
  • rejected and closed are terminal
An approved group can drop back to action_needed at any time when the provider asks for something new, so keep handling requirements after go-live.

The onboarding loop

  1. Create the group with this endpoint and keep the returned id.
  2. Read Get Virtual Account Group. The detail response carries requirements: the outstanding actions, and an agreements summary. The create response does not.
  3. Clear each requirement. A document requirement is satisfied by Upload Document quoting the requirement key; an account_profile requirement by setting or correcting the account’s identity: account_profile.required means no identity profile has been set at all, and an associated_person requirement by adding or correcting a person on the account.
  4. Accept the pending agreements with Submit Agreement Actions, using the ids in agreements.pending_ids: List Agreements has their titles and content.
  5. Poll Get Virtual Account Group until requirements is empty, agreements.status is complete and onboarding_status is approved. There are no webhook events for group onboarding today, so polling is the only signal.
  6. Wait for Hop to enable the group: status becomes enabled and enabled_at is set. Then create virtual accounts with Create Virtual Account.
Uploading documents and responding to agreements both nudge onboarding forward on Hop’s side, so requirements can change between polls without any further action from you.

Path Parameters

string
required
The account’s external ID (starts with acct_). It must belong to your customer: your own account, one of your end-customer accounts, or your fee-collection account.

Request Body

string
required
The group type to open, copied from type in List Group Types (1-100 characters). A type that is not configured returns 404 VIRTUAL_ACCOUNT_GROUP_NOT_FOUND. No other body field is accepted.

Response

Returns 201 with the new group, or 200 with the existing group when one is already open for this account and type. The response is the group summary. The same shape List Virtual Account Groups returns. It carries no requirements; call Get Virtual Account Group for those.
string
Virtual account group identifier (starts with vag_)
string
Always returns "virtual_account_group"
string
Account the group belongs to (starts with acct_)
string
The group type, matching the type you sent
string
Activation state, controlled by Hop: pending, enabled or disabled. A new group is pending; Hop moves it to enabled once onboarding is approved. Only an enabled group whose onboarding_status is approved can back virtual accounts.
string
KYC/KYB progress: action_needed, under_review, approved, rejected, suspended or closed. See the table above.
string
ISO 8601 timestamp when Hop first enabled the group, or null
string
ISO 8601 timestamp when onboarding most recently became suspended, or null
string
ISO 8601 timestamp when onboarding was closed, or null
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that created the group: the API key id (starts with ak_) when opened through this API, otherwise the actor Hop recorded
string
Actor that last updated the group, or null

Errors

Request Example

Response Example