Verification ChecksEmployment & education

Reference collection (per referee)

Collect and analyse referee feedback.

Send REFERENCES in checksRequested to run this check.

At least one referee or an existing profile reference is required.

The request

POST /api/v1/reports
{
  "subject": {
    "fullName": "Jane Doe",
    "idNumber": "36901234",
    "email": "jane@example.com",
    "country": "KE",
    "subjectType": "INDIVIDUAL"
  },
  "checksRequested": [
    "REFERENCES"
  ],
  "checkInputs": {
    "references": {
      "referees": [
        {
          "name": "John Doe",
          "email": "john@example.com",
          "phone": "+254712345678",
          "relationship": "Former manager",
          "organisation": "Example Holdings",
          "role": "Finance Director",
          "yearsKnown": 4,
          "note": "Managed the candidate directly"
        }
      ]
    }
  },
  "purpose": "Employment screening",
  "consent": {
    "mode": "VERIFISHA_HOSTED"
  }
}

The acknowledgement

Creation is asynchronous. The report comes back as a draft; the check runs after.

201 Created
{
  "reports": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "status": "DRAFT",
      "paymentState": {
        "status": "NOT_REQUIRED",
        "amount": {
          "amount": 0.1,
          "currency": "KES"
        }
      },
      "consentState": {
        "status": "NOT_REQUIRED"
      }
    }
  ],
  "count": 1
}

The result

When the check finishes, this arrives at your webhook. COMPLETED means it ran — read riskLevel and flags to decide what it found.

On this page