> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/kyc-api/government-registry-check-ghana.md).

# Government Registry Check: Ghana

Configure a Ghana registry check, supply an identifier, and interpret the result in a KYC flow.

Use Government Registry Check within a Vove ID KYC flow to look up a Ghana identity record. A registry lookup alone does not prove that the person presenting an identifier owns that identity. Review the whole verification result alongside the other checks in your flow.

For Nigerian checks, use the separate [NIN and BVN guide](https://docs.voveid.com/docs/kyc-api/government-registry-check.md).

## Before you start

* Confirm that Government Registry Check and your chosen Ghana check are enabled for your organization in your integration environment. Access is off by default. Availability depends on organization enablement and compatible API, dashboard and Web verification versions; this guide does not announce a Production or mobile release.
* Decide whether your backend supplies the identifier or the applicant enters it in Web verification. SDK collection needs separate organization enablement.
* Create sessions from your backend. Keep your private API key there; the client receives only the credentials needed to start its verification session.
* Obtain appropriate consent and apply your approved retention and access controls to identifiers, identity information and any biometric material.

Start with [environments and credentials](https://docs.voveid.com/docs/setup-your-credentials.md) and [session creation](https://docs.voveid.com/docs/kyc-api/verification-session.md).

## Choose the check

Confirm that the selected check is available for your organization before use.

All three checks use country `GH`:

* **Ghana Card** — registry `CARD`.
  * Lookup format: 6–20 ASCII letters, numbers or dashes.
  * Illustrative value: `GHA-100000001-1`.
* **Voter ID** — registry `VOTER_ID`.
  * Lookup format: 6–12 digits.
  * Illustrative value: `1100000001`.
* **Passport** — registry `PASSPORT`.
  * Lookup format: 6–12 ASCII letters or numbers.
  * Illustrative value: `G1000001`.

These are format-only synthetic values, not live identities, provider test credentials or guaranteed successful lookups. Keep identifiers as strings to preserve leading zeroes. Ghana validation trims outer whitespace; it does not remove interior letters or dashes. Do not apply Nigeria's 11-digit NIN rule.

## 2. Configure the flow

1. Open your KYC flow and add **Government Registry Check**.
2. Under **Registry configuration**, set **Country** to **Ghana** and select **Ghana Card**, **Voter ID** or **Passport** under **Registry**.
3. Under **Identifier collection**, select **API** for a number supplied during session creation, or **SDK** for applicant entry when authorized. **Document** extraction is unavailable for Ghana checks.
4. For lookup-only checks, leave **Face matching** off. Voter ID and Passport are lookup-only. See [Ghana Card facial matching](#ghana-card-facial-matching) for the separately enabled facial option.
5. Save the flow and use its matching flow ID when creating a session.

### Ghana Card facial matching

Ghana Card facial matching is a separate, explicit configuration that requires a compatible release, an earlier **Liveness** step and an eligible session selfie. Confirm availability before enabling **Face matching**. It is not an automatic part of a successful lookup.

Facial matching requires the tighter card format `AAA-123456789-X`: three uppercase letters, nine digits, and a final uppercase letter or digit, separated by dashes. The illustrative `GHA-100000001-1` matches that format. A value accepted for a lookup may not be accepted for facial matching.

The facial decision is match or mismatch, not a numeric confidence score. Do not apply Nigeria's confidence threshold or the document Face Match Level to this decision. Do not silently replace a facial-required check with a lookup-only check when its requirements cannot be met. Voter ID and Passport do not support facial matching.

## 3. Supply an identifier from your backend

For a flow that allows API collection, add `governmentRegistryChecks` to your existing `POST /v2/sessions` request along with its other required fields. The request uses your organization's private `x-api-key` on your backend. This example shows only the additional fields:

```json
{
  "governmentRegistryChecks": [
    {
      "country": "GH",
      "registry": "CARD",
      "identifier": "GHA-100000001-1"
    }
  ]
}
```

Use the country/registry pair configured in the flow. Supply an identifier for each required API-only check. For a Voter ID or Passport flow, replace this entry's registry and identifier with the matching values in [Choose the check](#choose-the-check). Do not submit extra entries for checks absent from the flow.

Supply registry identifiers through `governmentRegistryChecks`, not through the `user` prefill object. The country/registry pair must match the configured flow check. Start the session through your existing [Web SDK integration](https://docs.voveid.com/docs/sdks/web-sdk.md).

## 4. Interpret the result

Review the check in the authorized dashboard session details and then review the whole-session verdict. A completed request or HTTP success response is not automatically a passed verification.

This is an illustrative nested `result` fragment from check execution, not a complete session response or a recorded live lookup:

```json
{
  "country": "GH",
  "registry": "CARD",
  "source": "api",
  "outcome": "verified",
  "verificationStatus": "verified",
  "verificationReason": "registry_lookup_verified"
}
```

The surrounding response also carries flow/session state. Check-level `verified` and `not_verified` are different from whole-session verdicts such as `successful` and `caution`.

* **Lookup succeeded:** `verified` / `registry_lookup_verified`. Registry lookup succeeded; lookup alone does not prove ownership.
* **Record not found:** `not_verified` / `registry_record_not_found`. No matching record was returned. Check the supplied identifier; do not treat this as verified.
* **Cross-check mismatch:** `not_verified` / `registry_cross_check_mismatch`. Inconclusive cross-check. Review the result rather than treating it as a match.
* **Facial decision:** `face_match_verified` / `face_match_failed`. Applies only to an explicitly enabled Ghana Card facial check. Keep facial decisions separate from lookup-only success.
* **Technical failure:** `provider_error`. Technical failure, not an identity mismatch. Safe reasons can include `provider_unavailable`, `provider_rate_limited`, `provider_rejected_request` or `provider_authentication_failed`.

Only authorized reviewers may see retained identity data. Fields and the government portrait depend on the returned record, retained data and compatible dashboard/API versions. Missing values remain missing; do not infer a date of birth or substitute the submitted selfie for a government portrait.

Retrieve check results through `GET /v2/users/{refId}`. Its `governmentRegistryChecks` array includes each configured check's lifecycle, last persisted verdict, and available normalized registry data. See the [response examples, fields, and data rules](https://docs.voveid.com/docs/kyc-api/get-user-verification.md#government-registry-checks).

## Troubleshooting and retries

### Feature disabled (403)

Code: `GOV_REGISTRY_CHECK_FEATURE_DISABLED`.

Confirm organization enablement with Vove ID. Repeated submission cannot enable access.

### SDK collection disabled (403)

Code: `GOV_REGISTRY_CHECK_USER_INPUT_DISABLED`.

SDK collection is not enabled. Use an approved API-source flow; do not bypass the restriction.

### Invalid format or unsupported pair

Check the country/registry pair and its format. Preserve letters, dashes and leading zeroes.

### Identifier required

Code: `GOV_REGISTRY_CHECK_IDENTIFIER_REQUIRED`.

Supply the identifier through the source allowed by the current flow.

### Web asks again after API prefill

Confirm the pair, source and Web version. Mixed API/SDK collection can still prompt; use an agreed API-only configuration when entry is not intended.

### Selfie required

Code: `GOV_REGISTRY_CHECK_SELFIE_REQUIRED`.

Complete the supported enrollment/Liveness path for an explicitly facial-required Ghana Card check. Do not downgrade required matching or start capture for a lookup-only check.

### Check is not current (409)

Code: `GOV_REGISTRY_CHECK_NOT_CURRENT`.

Resume the correct current step. Do not replay a different pair.

### Session inactive (409)

Code: `GOV_REGISTRY_CHECK_SESSION_INACTIVE`.

Stop retrying the inactive session and follow your documented recovery process.

### Network interruption, rate limit or temporary service failure

Use the retry action only when allowed by the current session and remaining attempts. Contact support if the problem persists.

Transient failures have bounded server retries; definitive results are not automatically retried. Do not expect automatic switching to another provider. Provider failures can consume step attempts and may end the session with a caution verdict when attempts are exhausted. Avoid concurrent retries or repeated new sessions to work around an unclear result.

See [errors](https://docs.voveid.com/docs/api-fundamentals/errors.md) and [API conventions](https://docs.voveid.com/docs/api-fundamentals/api-conventions.md).

## Protect customer information

Keep raw identifiers, returned records, portraits, selfies, private keys and session tokens out of logs, analytics and support tickets. Share only an appropriate session reference and safe error code through your approved support channel. Restrict stored results to authorized staff and apply your retention policy. Never copy raw provider responses into customer integrations.
