Endpoint Field Reference

Known integration endpoints, their required inputs, and available response fields. Use this reference during SRD validation to:

1. Verify that fields marked as "disabled (fetched)" are actually available from the endpoint
2. Identify the correct endpoint when the SRD describes a fetch pattern
3. Flag fields that cannot be prefilled because they don't exist in the endpoint response
4. For unknown endpoints, specify what inputs and response the partner must provide

NIDA Endpoints (Adapter: FNIDAFETCH)

All NIDA endpoints use the same adapter (FNIDAFETCH) and return the same response structure.

NIDAVERIFYPHONE — Phone-based NID Verification (Primary)

The main NIDA endpoint used for NID verification with phone OTP.

Widget: customotpdatafetch or customidinput Required Input: documentNumber (16-digit NID), msidn (phone number)

Available Response Fields:

NIDAGETIDINFO — Child ID Verification

Widget: customidinput with idType: "CHILD_ID" Required Input: documentNumber (Child application/ID number) Available Response Fields: Same as NIDAVERIFYPHONE

NIDA_NIN — NIN Verification

Widget: customidinput with idType: "NIN" Required Input: documentNumber (NIN) Available Response Fields: Same as NIDAVERIFYPHONE

CRVS Endpoints — Civil Registration and Vital Statistics

All CRVS adapters automatically inject keyphrase from configuration. The input is typically a document number or CRVS reference number.

FGETBIRTHRECORD — Birth Record Fetch

Widget: customcrvsidinput or customgenericdatafetch Required Input: documentNumber or crvsReferenceNumber

Available Response Fields:

FGETDEATHRECORD — Death Record Fetch

Required Input: documentNumber or crvsReferenceNumber

Available Response Fields:

FGETMARRIAGERECORD — Marriage Record Fetch

Required Input: crvsReferenceNumber

Available Response Fields:

FGETDIVORCERECORD — Divorce Record Fetch

Required Input: crvsReferenceNumber Available Response Fields: Similar to marriage record + dateOfDivorce, courtOrderNumber

FGETRECOGNITIONRECORD — Child Recognition Record Fetch

Required Input: crvsReferenceNumber Available Response Fields: Similar to birth record + recognition-specific parent details

RRA — TIN Lookup (Adapter: FGETTINDETAILS, endpointCode: FTINDETAILS)

Widget: customtininput Form url: /integration/v1/fetch/sync (standard integration gateway path) Required Input: tinNumber (passed as URL path parameter)

The payload is wrapped in an RRA envelope — the fetchable fields live under ResponseObject:

{
  "MessageCode": 1,
  "MessageDescription": "SUCCESS",
  "ResponseObject": {
    "Category": "Small taxpayer",
    "Cell": "NGOMA",
    "DetailedAddress": "131 kigali",
    "ManagerNames": "Michael Oliver",
    "District": "KICUKIRO",
    "EmailAddress": "test_business@yopmail.com",
    "PhoneNumber": "250794772376",
    "Province": "KIGALI CITY",
    "Sector": "KICUKIRO",
    "Village": "AHITEGEYE",
    "Fax": null,
    "NationalId": "1193380008234704",
    "SupplierName": "Company Ltd - ZXUJP",
    "SupplierTin": "100005000"
  }
}

Available Response Fields (PascalCase as returned by the endpoint):

Category (taxpayer category) is available, and it takes exactly two values: "Small taxpayer" and "Large taxpayer". There is no medium category. It is the usual driver for dynamic pricing, conditional attachments and small/large workflow branches.

It is matched as an exact string, so use that spelling verbatim in pricing conditions, display rules and workflow conditions — "Small taxpayer" is not "Small Taxpayer" and not "SMALL COMPANY". Two conditions cover the whole value set, but keep a catch-all on dynamic pricing anyway: a price whose conditions don't match the submitted value does not resolve and no bill is generated.

If the field is hidden on the form but still read downstream, it must be hidden with props.hideField (value kept and submitted), never hide (clears the model) or disabled (not submitted).

Note: Some TIN endpoints return vehicle details instead (plateNumber, chassisNumber, etc.). Confirm with the partner which fields their specific endpoint returns.

NLA — UPI Land Parcel Lookup (Adapter: FGETUPIDETAILS)

The flatter of the two UPI endpoints. Returns parcel coordinates, which LAIS does not — but less owner, tenure and location-code detail. See LAIS_UPI_FETCH and the comparison table below it before choosing.

Widget: customgenericdatafetch or custom input Required Input: upi (Unique Parcel Identifier, passed as query parameter)

{
  "upi": "1/03/01/04/30",
  "area": 2,
  "landUseNameEnglish": "Commercial",
  "landUseNameKinyarwanda": "",
  "rightType": "",
  "remainingLeaseTerm": "",
  "xCoordinate": "-1.9426",
  "yCoordinate": "30.0567",
  "coordinateReferenceSystem": "Geographic Coordinate System",
  "parcelLocation": {
    "village": { "villageCode": "101010111", "villageName": "Umurabyo" },
    "cell": { "cellCode": "1010101", "cellName": "Akabahizi" },
    "sector": { "sectorCode": "010101", "sectorName": "Gitega" },
    "district": { "districtCode": "101", "districtName": "Nyarugenge" },
    "province": { "provinceCode": "1", "provinceName": "Kigali" }
  },
  "isUnderRestriction": false,
  "hasMortgage": false,
  "inProcess": false,
  "owners": [
    {
      "fullName": "George R. Kim",
      "idNo": "1193380008248067",
      "idTypeName": "National ID",
      "countryName": "Rwanda",
      "sharePercentage": "40",
      "gender": "Male",
      "maritalStatus": "Married",
      "succession": true,
      "minor": false
    }
  ],
  "representative": {
    "surname": "Muhire",
    "foreNames": "Benjamin",
    "idNo": "34567891",
    "idTypeName": "National ID",
    "countryName": "Rwanda",
    "gender": "Male",
    "maritalStatus": "Single",
    "address": {
      "village": { "villageCode": "101010111", "villageName": "Umurabyo" },
      "cell": { "cellCode": "1010101", "cellName": "Akabahizi" },
      "sector": { "sectorCode": "010101", "sectorName": "Gitega" },
      "district": { "districtCode": "101", "districtName": "Nyarugenge" },
      "province": { "provinceCode": "1", "provinceName": "Kigali" }
    }
  },
  "restrictions": [{ "restrictionTypeId": "", "restrictionText": "" }]
}

Available Response Fields:

Not returned — do not mark these as fetched:

owners and restrictions are arrays. A single text field cannot hold them. Either render a read-only table, or project a joined summary (e.g. owner names) into a flat field via a form expression. Note the arrays can be empty.

Coordinates are available via xCoordinate / yCoordinate — an SRD asking the applicant to type GPS coordinates for a parcel that was just looked up should normally prefill them instead.

NLA — UPI Land Parcel Lookup (LAIS_UPI_FETCH)

The richer of the two UPI endpoints. Returns trilingual land use, tenure/right type, NISR location codes, full owner and representative records, and pre-flattened owner/restriction/mortgage strings.

Widget: customgenericdatafetch or custom input Required Input: upi (Unique Parcel Identifier)

{
  "data": {
    "upi": "1/03/05/01/3788",
    "inTransaction": false,
    "area": 538,
    "remainingLeaseTerm": 49,
    "landUse": {
      "landUseId": 11,
      "landUseTypeNameKinyarwanda": "Gutura",
      "landUseTypeNameEnglish": "Residential",
      "landUseTypeNameFrench": "Usage résidentiel",
      "endDate": null,
      "leaseTerm": 49
    },
    "tenure": {
      "rightTypeId": "EL",
      "rightTypeName": "Emphyteutic Lease",
      "rightTypeCategory": "Real Right",
      "rightTypeKind": "Property",
      "isInquiry": true,
      "onCertificate": true
    },
    "address": {
      "villageName": "Radari",
      "villageId": "103050110",
      "cellName": "BUSANZA",
      "cellId": "1030501",
      "sectorName": "KANOMBE",
      "sectorId": "10305",
      "districtName": "Kicukiro",
      "districtId": "103",
      "provinceNameEnglish": "Kigali City",
      "provinceNameKinyarwanda": "Umujyi wa Kigali",
      "provinceNameFrench": "Ville de Kigali",
      "provinceId": "01",
      "string": "Kigali City,Kicukiro,KANOMBE,BUSANZA,Radari"
    },
    "mortgages": [],
    "restrictions": [],
    "owners": [
      {
        "rightId": "15453145",
        "upi": "1/03/05/01/3788",
        "partyId": "1199080036009082_RW",
        "startTransactionId": "103050137881516253541557",
        "endTransactionId": null,
        "naturalPerson": {
          "partyId": "1199080036009082_RW",
          "idTypeId": "NID",
          "countryId": "RW",
          "idNo": "1199080036009082",
          "tin": null,
          "villageId": "102100306",
          "boxNo": null,
          "streetName": null,
          "addressLine1": "",
          "surname": "KANYAMAHANGA",
          "foreNames": "JEAN CLAUDE",
          "maritalStatus": null,
          "gender": "M",
          "isProvisional": false,
          "fullName": "KANYAMAHANGA JEAN CLAUDE"
        },
        "party": {
          "partyId": "1199080036009082_RW",
          "partyTypeId": "NATURAL_PERSON",
          "startTransactionId": "103050137881516253541557",
          "endTransactionId": null,
          "party_id": "1199080036009082_RW"
        },
        "businessType": "NATURAL_PERSON",
        "share": "100.00"
      }
    ],
    "representative": {
      "person": {
        "partyId": "1199080036009082_RW",
        "idTypeId": "NID",
        "countryId": "RW",
        "idNo": "1199080036009082",
        "surname": "KANYAMAHANGA",
        "foreNames": "JEAN CLAUDE",
        "fullName": "KANYAMAHANGA JEAN CLAUDE",
        "gender": "M",
        "maritalStatus": null,
        "tin": null,
        "villageId": "102100306",
        "boxNo": null,
        "streetName": null,
        "addressLine1": "",
        "isProvisional": false,
        "address": {
          "villageName": "Kagarama",
          "villageId": "102100306",
          "cellName": "KAGUGU",
          "cellId": "1021003",
          "sectorName": "KINYINYA",
          "sectorId": "10210",
          "districtName": "Gasabo",
          "districtId": "102",
          "provinceNameEnglish": "Kigali City",
          "provinceNameKinyarwanda": "Umujyi wa Kigali",
          "provinceNameFrench": "Ville de Kigali",
          "provinceId": "01",
          "string": "Kigali City,Gasabo,KINYINYA,KAGUGU,Kagarama"
        }
      }
    }
  },
  "owners": "[{\"fullName\":\"KANYAMAHANGA JEAN CLAUDE\",\"idOrPassport\":\"1199080036009082\",\"sharePercent\":\"100\",\"partyId\":\"1199080036009082_RW\",\"tin\":null}]",
  "restrictions": "[]",
  "mortgages": "[]"
}

Parcel

Tenure

rightTypeId is the stable code; rightTypeName is the display label. Drive display rules, pricing conditions and workflow branches off rightTypeId, never off the label.

Address

data.address and data.representative.person.address share the same shape.

The *Id codes are NISR location codes. Use them, not the names, for CODE_FROM_LOCATION office assignment — see Office Assignment. address.string is a ready-made read-only address line; no expression needed to build one.

Owners

Two representations of the same data are returned. Pick one — don't populate from both.

data.owners[] — full nested records:

Top-level owners — a pre-flattened JSON string:

"owners": "[{\"fullName\":\"NTIRIVAMUNDA JEAN\",\"idOrPassport\":\"1195180000318048\",\"sharePercent\":\"50\",\"partyId\":\"1622084_3\",\"tin\":null}]"

Keys: fullName, idOrPassport, sharePercent, partyId, tin. This is the convenient form for a read-only owners table — but note sharePercent is "50" here where data.owners[].share is "50.00", so don't mix the two in one display.

Gotchas in the owners block:

• owners, restrictions and mortgages at the top level are serialised strings, not arrays. They must be parsed before use. The arrays under data. are real arrays.
• data.owners[] carries both Party (capital P) and party (lowercase) with identical content. Use party; the capitalised duplicate is an artifact.
• Only naturalPerson has been observed. When businessType is not NATURAL_PERSON the owner object presumably carries a legal-person block instead — confirm the shape with TechOps before designing a form that must handle company-owned parcels.
• Names arrive unnormalised. One observed sample has foreNames: " JEAN" with a leading space, producing fullName: "NTIRIVAMUNDA JEAN" with a double space. Trim before printing on a certificate.
• A parcel can have several owners (two at 50% each in the observed samples). A single text field cannot hold them.

Representative

data.representative.person has the same shape as data.owners[].naturalPerson, plus a nested address object.

Restrictions and mortgages

data.restrictions[] and data.mortgages[] are arrays; the top-level restrictions and mortgages are the same content as serialised strings. Both were empty in every observed sample, so the element shape is unconfirmed — get a populated sample from TechOps before building a form that depends on restriction or mortgage detail.

Note there is no isUnderRestriction / hasMortgage boolean here, unlike FGETUPIDETAILS. Derive the flag from array length.

Not returned — do not mark these as fetched

Choosing between the two UPI endpoints

Default to LAIS_UPI_FETCH unless the form needs parcel coordinates. Name the chosen endpoint explicitly in the SRD — the two differ in shape, key names and nesting depth, so populates.valueKey paths are not interchangeable between them.

EPOBOX — Address Lookup (Adapter: FEPOBOXFETCH / FEPOBOXDETAILSFETCH)

Widget: customgenericdatafetch Required Input: phoneNumber (auto-prefixed with +25 if missing)

Available Response Fields (FEPOBOXDETAILSFETCH):

Inference Rules for Unknown Endpoints

When the SRD references a fetch that doesn't match any known endpoint above:

1. Infer the likely endpoint from context:

   • NID/National ID/Identity fields → NIDAVERIFYPHONE (via FNIDAFETCH)
   • Birth/Child/Certificate number → FGETBIRTHRECORD
   • Death certificate → FGETDEATHRECORD
   • Marriage certificate → FGETMARRIAGERECORD
   • TIN/Tax/Business → FGETTINDETAILS
   • UPI/Land/Parcel → LAIS_UPI_FETCH (default) or FGETUPIDETAILS (if coordinates are needed)
   • Phone + address/postal → FEPOBOXDETAILSFETCH
   • OTP + NID → NIDAVERIFYPHONE

2. If inference is possible, use the inferred endpoint's field reference to validate the SRD fields and note the inference in the API report.

3. If inference is not possible, the API report must explicitly state:

   • Required Inputs: What the user must provide to trigger the fetch
   • Required Response: What fields the SRD expects back (list every disabled/fetched field)
   • Status: Pending — Confirm API contract with partner
   • Raise a MEDIUM gap