Get Account

curl --request GET \
  --url https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id} \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "object": "account",
  "id": "acct_3mnq7c1e6a2b4f3c9b8d2e5a",
  "customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
  "type": "business",
  "kyc_status": "not_started",
  "display_name": "Acme Pte Ltd",
  "contact_email": "ops@acme.example",
  "country_code": "SG",
  "onboarding": {
    "requirements_version": "ads_business_sgp_v1",
    "ready_for_submission": false,
    "submission_status": "not_ready"
  },
  "requirements": {
    "complete": ["company.proof_of_address", "company.register_of_directors"],
    "pending": [],
    "missing": [
      {
        "key": "company.certificate_of_incorporation",
        "type": "company_document",
        "label": "Certificate of incorporation",
        "accepted_document_types": ["certificate_of_incorporation"]
      },
      {
        "key": "associated_person.ubo.min_count",
        "type": "associated_person",
        "label": "At least one ultimate beneficial owner is required",
        "role": "ultimate_beneficial_owner",
        "min_count": 1
      }
    ],
    "issues": []
  },
  "individual": null,
  "associated_persons": [
    {
      "id": "aap_8rty2c1x7k2m9p4q1w8e5r3t",
      "role": "ultimate_beneficial_owner",
      "is_signer": true,
      "email": "jane@acme.example",
      "phone_number": "+6581234567",
      "verification_status": "under_review",
      "hosted_url": "https://verify.platform.example/s/3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
      "hosted_url_expires_at": "2026-06-30T04:20:00Z"
    }
  ],
  "rejection_reasons": null,
  "created": "2026-05-01T10:00:00Z",
  "updated": "2026-05-01T10:05:00Z",
  "created_by": "ak_x7k2m9p4q1w8e5r3t6y0u2i4",
  "updated_by": null
}

GET

customers

{customer_id}

accounts

{account_id}

Get Account

curl --request GET \
  --url https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id} \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.hopnow.io/va/v1/customers/{customer_id}/accounts/{account_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "object": "account",
  "id": "acct_3mnq7c1e6a2b4f3c9b8d2e5a",
  "customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
  "type": "business",
  "kyc_status": "not_started",
  "display_name": "Acme Pte Ltd",
  "contact_email": "ops@acme.example",
  "country_code": "SG",
  "onboarding": {
    "requirements_version": "ads_business_sgp_v1",
    "ready_for_submission": false,
    "submission_status": "not_ready"
  },
  "requirements": {
    "complete": ["company.proof_of_address", "company.register_of_directors"],
    "pending": [],
    "missing": [
      {
        "key": "company.certificate_of_incorporation",
        "type": "company_document",
        "label": "Certificate of incorporation",
        "accepted_document_types": ["certificate_of_incorporation"]
      },
      {
        "key": "associated_person.ubo.min_count",
        "type": "associated_person",
        "label": "At least one ultimate beneficial owner is required",
        "role": "ultimate_beneficial_owner",
        "min_count": 1
      }
    ],
    "issues": []
  },
  "individual": null,
  "associated_persons": [
    {
      "id": "aap_8rty2c1x7k2m9p4q1w8e5r3t",
      "role": "ultimate_beneficial_owner",
      "is_signer": true,
      "email": "jane@acme.example",
      "phone_number": "+6581234567",
      "verification_status": "under_review",
      "hosted_url": "https://verify.platform.example/s/3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
      "hosted_url_expires_at": "2026-06-30T04:20:00Z"
    }
  ],
  "rejection_reasons": null,
  "created": "2026-05-01T10:00:00Z",
  "updated": "2026-05-01T10:05:00Z",
  "created_by": "ak_x7k2m9p4q1w8e5r3t6y0u2i4",
  "updated_by": null
}

Fetches a single account with its full KYB response, including onboarding progress, requirements, and rejection reasons. Returns 404 if the account does not exist and 403 if the id resolves to an account owned by another organization.

Path Parameters

string

required

Platform customer id.

string

required

Account id.

Response

Returns the full account object.

string

Always account.

string

Account id (e.g. acct_3mnq7c1e6a2b4f3c9b8d2e5a).

string

Platform customer id.

enum | null

Entity type: individual or business. null until KYC starts.

enum | null

Verification status: not_started, under_review, action_needed, approved, or rejected. Newly created accounts remain not_started until the requirements returned by this endpoint are complete; Hop then starts verification review automatically.

string | null

Account display name.

string | null

Primary contact email.

string | null

ISO 3166-1 alpha-2 country code. Derived from registered_address.country.

object

Onboarding state.

Show child attributes

string

Opaque identifier of the requirement set applied to this account. Treat it as an opaque value; do not parse it.

boolean

Whether all requirements are complete and the account is ready for final submission.

enum

One of not_ready, ready, submitting, or submitted.

object

Requirement state: complete (string[]), pending (string[]), missing (object[]), and issues (object[]). This is the preferred source for rendering the next onboarding action. issues holds blocking items that need your action: rfi.* review requests, and requirements whose document was rejected during submission — those entries carry rejected_documents (object[] of document_id + reason). Upload a corrected file with the entry’s key as requirement_key to resolve either kind; re-submission happens automatically.

object | null

Echo of the onboarded individual profile — present for type: "individual" accounts only, null for business. Carries the submitted profile as stored: first_name, middle_name, last_name, email, phone_number, description, date_of_birth, place_of_birth, document_number, nationality, address, tax_identification, cdd, and reference (same shapes as on Create Account).

object[]

Associated-person progress, including verification_status, hosted_url, and hosted_url_expires_at when hosted verification is required. For individual accounts this contains the account holder (role account_holder), whose entry carries the hosted verification session state; the role is reserved and cannot be created or edited through the Associated Persons endpoints.

Show child attributes

string

Associated person id (aap_…).

enum

Person’s role (e.g. ultimate_beneficial_owner, director, control_person).

boolean

Whether the person is an authorized signer.

string

Person’s email address.

string

Person’s phone number.

enum

Person’s verification status.

string | null

Hosted verification URL, present when hosted verification is required.

string | null

ISO 8601 expiry timestamp of the hosted verification URL.

object[] | null

Review rejection reasons, populated only when kyc_status is rejected (terminal). Null otherwise. Recoverable review requests (action_needed) appear as rfi.* entries under requirements.issues, each carrying its own reason, developer_reason, and accepted_document_types; a document the verification provider could not process appears the same way, as an issue entry with rejected_documents. In both cases, upload the corrected document with the entry’s key as requirement_key and re-submission happens automatically. During such a cycle, onboarding.submission_status returns to not_ready / ready until the corrected documents are re-submitted.

Show child attributes

string

User-safe rejection reason — safe to display to your end customer.

string

Machine-readable reason for your integration logic. Must not be shown to end customers.

string

ISO 8601 timestamp when created (standard envelope).

string

ISO 8601 timestamp when last updated (standard envelope).

string | null

Actor that created the account (standard envelope).

string | null

Actor that last updated the account (standard envelope).

{
  "object": "account",
  "id": "acct_3mnq7c1e6a2b4f3c9b8d2e5a",
  "customer_id": "cus_x7k2m9p4q1w8e5r3t6y0u2i4",
  "type": "business",
  "kyc_status": "not_started",
  "display_name": "Acme Pte Ltd",
  "contact_email": "ops@acme.example",
  "country_code": "SG",
  "onboarding": {
    "requirements_version": "ads_business_sgp_v1",
    "ready_for_submission": false,
    "submission_status": "not_ready"
  },
  "requirements": {
    "complete": ["company.proof_of_address", "company.register_of_directors"],
    "pending": [],
    "missing": [
      {
        "key": "company.certificate_of_incorporation",
        "type": "company_document",
        "label": "Certificate of incorporation",
        "accepted_document_types": ["certificate_of_incorporation"]
      },
      {
        "key": "associated_person.ubo.min_count",
        "type": "associated_person",
        "label": "At least one ultimate beneficial owner is required",
        "role": "ultimate_beneficial_owner",
        "min_count": 1
      }
    ],
    "issues": []
  },
  "individual": null,
  "associated_persons": [
    {
      "id": "aap_8rty2c1x7k2m9p4q1w8e5r3t",
      "role": "ultimate_beneficial_owner",
      "is_signer": true,
      "email": "jane@acme.example",
      "phone_number": "+6581234567",
      "verification_status": "under_review",
      "hosted_url": "https://verify.platform.example/s/3f6b2a91-4c8e-4f27-9d15-8a2e6c1b7d40",
      "hosted_url_expires_at": "2026-06-30T04:20:00Z"
    }
  ],
  "rejection_reasons": null,
  "created": "2026-05-01T10:00:00Z",
  "updated": "2026-05-01T10:05:00Z",
  "created_by": "ak_x7k2m9p4q1w8e5r3t6y0u2i4",
  "updated_by": null
}

Getting Started

Integration Flows

Webhooks

Endpoints

Get Account

Path Parameters

Response

​Path Parameters

​Response

Path Parameters

Response