Lookup a farmer

Resolve a farmer by their Rupa ID and return the data sections your account is entitled to. This is the only billed endpoint — see Billing & credits.

POST /v1/rupa/lookup

Request body

Valid sections values (subject to your entitlement): identity, bvn_nin_data, credit_history, outstanding_loans, transaction_volume, farms, underwriting_value, wallet, socioeconomic_profile.

Example — full lookup

curl -X POST https://api.riwe.io/v1/rupa/lookup \
  -H "X-API-KEY: rk_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "rupa_id": "rp-7lif9u" }'

Example — only what you need (cheaper)

curl -X POST https://api.riwe.io/v1/rupa/lookup \
  -H "X-API-KEY: rk_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "rupa_id": "rp-7lif9u", "sections": ["identity", "credit_history"], "source": "loan" }'

Response 200

The data object contains the farmer's rupa_id, a queried_at timestamp, one key per returned section, a meta block, and a billing breakdown. Below is a complete bank response (all five bank sections). See the Data sections pages for a field‑by‑field description of each block.

{
  "success": true,
  "data": {
    "rupa_id": "rp-7lif9u",
    "queried_at": "2026-07-03T12:02:54+00:00",

    "identity": {
      "full_name": "Bank Admin", "first_name": "Bank", "last_name": "Admin",
      "gender": null, "date_of_birth": null, "phone_number": null,
      "state": null, "lga": null, "community": null, "country": "Nigeria",
      "kyc_status": "pending", "kyc_verified_at": null,
      "identity_locked": false, "agent_enrolled": false
    },

    "bvn_nin_data": {
      "bvn": { "verified": false, "verified_at": null, "masked": null, "name_match": false, "dob_match": false },
      "nin": { "verified": false, "masked": null, "cross_matched_with_bvn": false },
      "verification_source": "NIBSS + NIMC via Prembly",
      "overall_confidence": "low"
    },

    "credit_history": {
      "credit_score": null, "credit_rating": null, "score_factors": null, "score_calculated_at": null,
      "prior_formal_loans_count": 0, "prior_informal_loans_count": 0,
      "prior_insurance_participation": false, "cooperative_membership": false, "vsla_membership": false,
      "repayment_record": [], "partner_reported_repayments": [], "bureau": null,
      "data_as_of": "2026-07-03T12:02:54+00:00"
    },

    "outstanding_loans": {
      "total_outstanding": 0, "currency": "NGN",
      "riwe_loans": [], "partner_loans": [], "data_as_of": "2026-07-03T12:02:54+00:00"
    },

    "transaction_volume": {
      "currency": "NGN", "sources": ["riwe_platform", "partner_network"],
      "summary": {
        "last_30_days":   { "total_received": 0, "total_sent": 0, "transaction_count": 0 },
        "last_90_days":   { "total_received": 0, "total_sent": 0, "transaction_count": 0 },
        "last_12_months": { "total_received": 0, "total_sent": 0, "transaction_count": 0 }
      },
      "data_as_of": "2026-07-03T12:02:54+00:00"
    },

    "meta": {
      "profile_tier": "bronze",
      "profile_completeness": 0,
      "tier_criteria": {
        "bvn_verified": false, "nin_verified": false, "agent_enrolled": false,
        "gps_farm": false, "ndvi_present": false, "harvest_history": false, "phone_verified": false
      },
      "rupa_profile_url": "https://api.riwe.io/rupa/rp-7lif9u"
    },

    "billing": {
      "amount_charged": 310,
      "currency": "NGN",
      "credits": 31000,
      "breakdown": {
        "riwe_fee.identity": 25, "riwe_fee.bvn_nin_data": 30, "riwe_fee.credit_history": 50,
        "riwe_fee.outstanding_loans": 20, "riwe_fee.transaction_volume": 20,
        "passthrough.bvn": 50, "passthrough.nin": 35, "passthrough.credit_bureau": 80
      }
    }
  }
}

meta block

meta.denied_sections

If you requested sections your account type can't read, the permitted ones are returned and the rest listed under meta.denied_sections (you are only billed for what's returned).

Errors

See Errors for the full list.

Side effect: consent

A successful lookup records (or refreshes) a consent entry for this Rupa ID on your roster. See Consents & account.