List check history

GET

/api/v1/kyc/lookups

const url = 'https://connect.payhero.africa/api/v1/kyc/lookups?limit=50&check=phone&identifier=254712345678';
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&check=phone&identifier=254712345678' \
  --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.

Pass check and identifier together to list only the lookups of one subject, for example to reuse a name already verified for a phone number instead of paying to check it again.

Authorizations

basicAuth

Parameters

Query Parameters

limit

integer

Maximum entries to return. Defaults to 100 (20 when filtering by identifier), capped at 500.

Example

check

string

The check key to filter by. Required when identifier is set.

Example

phone

identifier

string

The subject to filter by: the value of the check’s first required field, exactly as sent on the verify call. Case-insensitive, but formatting must match (254712345678 is not 0712345678).

Example

254712345678

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"
  }
]

400

identifier was given without check.

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
}