Skip to main content
POST
Submit Agreement Actions
This endpoint works on any account you own. Create Virtual Account Group covers who can open a group and what the account needs first. Records the account holder’s decision on the agreements listed by List Agreements. Onboarding completes when every agreement is accepted and every document requirement is satisfied. The batch is validated as a whole before anything is sent to the provider: if any agreement in it is not pending, has expired, or is being rejected while declinable is false, the request fails with 409 and nothing is applied. A 200 does not mean every action was accepted. Hop forwards the batch to the provider and returns one entry per requested action in results. An entry with a non-null error failed and its agreement is unchanged, still pending, while the other entries in the same response may have succeeded. Always inspect every entry; never treat the status code alone as success. After the call, Hop resumes the group’s onboarding in the background, so the group’s requirements and onboarding status update shortly afterwards. Poll Get Virtual Account Group for the new state. Requires an API key with write access on the virtual_accounts scope.

Path Parameters

string
required
The account’s external ID (starts with acct_)
string
required
The virtual account group’s external ID (starts with vag_). It must belong to the account in the path.

Headers

string
required
Canonical lowercase 8-4-4-4-12 UUID. Scoped to the group, with the payload fingerprinted: replaying the same key with the same payload returns the recorded outcome, and with a different payload returns 409. See Idempotency.

Request Body

array
required
The decisions to submit, 1 to 50 entries. Each agreement_id must appear at most once and must belong to the group in the path.
string
The authorised associated person signing on behalf of a business account (starts with aap_, must belong to the account and carry is_signer: true). Required for a business account and rejected for an individual one, which has no associated persons and signs as itself. See Create Associated Person.

Response

Returns 200 with one entry per requested action, in the same order as agreement_actions.
array
Per-action outcomes

Retrying a partial failure

Retry by sending the same batch again with the same Idempotency-Key. Entries already recorded under that key are exempt from the pending check, and the batch reaches the provider under the same key, so only the entries that failed are acted on again. A fresh key on the same batch is rejected with 409, because the agreements that succeeded the first time are no longer pending. Use a fresh key only for a batch of agreements you have not acted on yet.

Errors

Request Example

Response Example