List check history

GET

/api/v1/kyc/lookups

const url = 'https://connect.payhero.africa/api/v1/kyc/lookups?limit=50';
const options = {method: 'GET', headers: {Authorization: 'Basic <credentials>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://connect.payhero.africa/api/v1/kyc/lookups?limit=50' \
  --header 'Authorization: Basic <credentials>'

Every check — live, cached or failed — in reverse chronological order. Identifiers are never stored in the clear; each entry carries a masked identifier_masked.

Authorizations

basicAuth

Parameters

Query Parameters

limit

integer

Maximum entries to return. Defaults to 100, capped at 500.

Example

Responses

200

The check history.

application/json

Array<object>

One entry in the check history.

object

string

check

string

country

string

status

verified — the identifier was confirmed. not_verified — the check ran and found no match. error — the check could not be completed.

string

Allowed values: verified not_verified error

verification_status

string

actor_type

C for a company, I for a natural person. Absent when the check cannot tell. Only tax_id and company checks can distinguish; an ID card or a phone line always reports I.

string

Allowed values: C I

subject_name

string

identifier_masked

string

reference

string

detail

string

source

string

charged_amount

number

charge_currency

string

charge_reference

string

charge_status

string

duration_ms

integer

created_at

string format: date-time

Example

[
  {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2",
    "check": "kra_pin",
    "country": "KE",
    "status": "verified",
    "verification_status": "VERIFIED",
    "actor_type": "C",
    "subject_name": "ACME TRADING LIMITED",
    "identifier_masked": "P00•••••00X",
    "source": "cache",
    "charged_amount": 20,
    "charge_currency": "KES",
    "charge_status": "charged"
  }
]

401

Missing or invalid Basic auth credentials.

application/json

object

error_code

string

error_message

string

status_code

integer

Example

{
  "error_code": "invalid_argument",
  "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)",
  "status_code": 400
}