Skip to main content
GET
Get Virtual Account Group
Works on any account you own that has a virtual account group open. Create Virtual Account Group covers who can open one and what the account needs before onboarding can progress: an identity profile, plus, on a business account, an associated person marked as a signer and holders of the account_representative, director and control_person roles. Poll this endpoint during onboarding. The detail response is a superset of the list item: every field List Virtual Account Groups returns, plus requirements, the outstanding actions the provider is waiting on, and an agreements summary. Poll it after opening a group with Create Virtual Account Group and after every document upload or agreement response. Hop refreshes the provider requirements and retains unresolved submission rejections as described below. Satisfied requirements disappear; new ones can appear at any time, including after the group is live. A group is usable only when status is enabled and onboarding_status is approved. Until both hold, Create Virtual Account rejects the group with 422 VIRTUAL_ACCOUNT_GROUP_NOT_ENABLED. A group opened before the account’s identity profile was set carries a single account_profile.required requirement, labelled Add the Account identity profile. Setting the profile with Update Account clears it and resumes onboarding. The group does not have to be opened again. Details the provider refuses when the account is first submitted show up as a requirement whose key ends in .submission: account_profile.submission for account fields, associated_person.{person_id}.submission for one associated person, or onboarding.submission when only Hop can resolve it. Its reason names the fields to correct, or says to contact Hop when no field would help. A rejection stays through refreshes and attempts that submit no facts. A later rejection of the same account or person replaces it; acceptance of that account or person clears it. Submitting another person does not clear the rejection. If a submission contains both named fields and errors Hop cannot map to fields, correct the named fields and contact Hop support for the remaining errors. Rejections also clear when the provider takes the record into review or decides on it. Requires an API key with read access on the virtual_accounts scope.

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.
string
required
The group’s external ID (starts with vag_). A group that belongs to another account returns 404.

Response

Returns every field of the list item, plus requirements and agreements.
string
Virtual account group identifier (starts with vag_)
string
Always returns "virtual_account_group"
string
Account the group belongs to (starts with acct_)
string
Group type, for example business_virtual_accounts. See List Group Types.
string
Activation state, controlled by Hop: pending, enabled or disabled
string
KYC/KYB progress: action_needed, under_review, approved, rejected, suspended or closed. See Create Virtual Account Group for what each means and how they transition.
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
array
Current onboarding actions for this group. An empty array means nothing is outstanding. Either the provider is reviewing what you sent, or onboarding is done.
object
Progress on the group’s agreements
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