Team KYC

Each Team carries its own KYC. A Team’s KYC tier determines what it can collect and pay out — see KYC tiers & limits. Submit KYC per Team; approval is handled by PayHero review.

Submit KYC

Attach identity and (for businesses) entity information to a Team. Document fields under upload_information are references to uploaded files.

curl -X POST "$PH_BASE_URL/api/v2/account_kycs" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 63,
    "entity_type": "business",
    "country_code": "KE",
    "country": "Kenya",
    "kyc_tier": 3,
    "contact_information": {
      "first_name": "Jane",
      "last_name": "Doe",
      "identification_number": 12345678,
      "identification_type": "national_id",
      "phone_number": "+254712345678",
      "upload_information": {
        "identification_front_document": "https://cdn.acme.co/kyc/id-front.jpg",
        "identification_back_document": "https://cdn.acme.co/kyc/id-back.jpg",
        "selfie_image": "https://cdn.acme.co/kyc/selfie.jpg"
      }
    },
    "entity_information": {
      "entity_name": "Vendor A Ltd",
      "nature_of_business": "Internet Service Provider",
      "business_type": "limited_company",
      "entity_address": "Westlands, Nairobi",
      "upload_information": {
        "tax_document": "https://cdn.acme.co/kyc/kra-pin.pdf",
        "entity_certificate_document": "https://cdn.acme.co/kyc/cert-incorp.pdf"
      }
    },
    "account_information": {
      "currency": "KES",
      "organization_id": "9",
      "account_name": "Vendor A",
      "email": "vendor-a@acme.co",
      "phone_number": "+254711000111"
    }
  }'

POST /api/v2/account_kycs

Field	Type	Notes
`account_id`	integer	Required — the Team this KYC belongs to.
`entity_type`	string	`individual` or `business`.
`country_code`	string	ISO country code, e.g. `KE`.
`country`	string	Country name.
`kyc_tier`	integer	Target tier for this submission.
`contact_information`	object	Primary contact identity + `upload_information` documents.
`entity_information`	object	Business details (for `entity_type: business`).
`account_information`	object	Snapshot of the Team’s account details.
`notes`	string	Optional free-text notes.

{
  "account_kyc": {
    "id": 501,
    "account_id": 63,
    "entity_type": "business",
    "status": "pending",
    "country_code": "KE",
    "country": "Kenya",
    "kyc_tier": 3,
    "contact_information": { "first_name": "Jane", "last_name": "Doe", "phone_number": "+254712345678" },
    "entity_information": { "entity_name": "Vendor A Ltd", "nature_of_business": "Internet Service Provider" },
    "account_information": { "account_name": "Vendor A", "currency": "KES", "email": "vendor-a@acme.co" },
    "created_at": "2026-07-06T09:20:10Z",
    "updated_at": "2026-07-06T09:20:10Z"
  }
}

Update KYC

Amend a submission — for example to attach a missing document or correct a detail. Identify the record with the id in the path.

curl -X PUT "$PH_BASE_URL/api/v2/account_kycs/501" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 501,
    "entity_type": "business",
    "country_code": "KE",
    "country": "Kenya",
    "kyc_tier": 3,
    "entity_information": {
      "entity_name": "Vendor A Ltd",
      "upload_information": {
        "proof_of_address_document": "https://cdn.acme.co/kyc/utility-bill.pdf"
      }
    }
  }'

PUT /api/v2/account_kycs/{id} — accepts the same fields as Submit and returns the updated { "account_kyc": { … } }.