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 an associated person marked as a signer on a business account. 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. requirements is rewritten each time Hop refreshes the group from the provider, so requirements is replaced on every refresh. A satisfied requirement disappears; new ones can appear at any time, including after the group is live: a requirement disappears once it is satisfied, and 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. 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