A TIN (Tax Identification Number) input that verifies the number against the RDB/RRA registry and auto-populates downstream fields from the company record.
Read Form Rules before using this component — keys, labels, required fields, expressions, visibility, and validation all follow shared conventions.
Instead of customtininput, use… |
For… |
|---|---|
customidinput |
Individual (citizen) NID, Foreigner ID, Child ID, or NIN verification |
input |
Plain reference numbers with no external registry verification |
| Prop | Type | Required? | Description |
|---|---|---|---|
label |
string |
required | Visible label. Must be unique across the form. |
required |
boolean |
required | Always false. The expression controls the runtime value. |
defaultRequired |
boolean |
required | true for required fields, false for optional ones. |
url |
string |
required | Integration endpoint path. Always /integration/v1/fetch/sync. |
endpointCode |
string |
required | Integration endpoint code. Always "FTINDETAILS" for production forms. |
useBaseUrl |
boolean |
required | Always true — prepends the API gateway base URL. |
populates |
array |
optional | { valueKey, targetKey } pairs mapping API response keys to form field keys. |
usePrefetch |
boolean |
optional | When true, auto-fetches the TIN from the logged-in user's business profile on load. Only for logged-in business users. |
tinLength |
number |
optional | Overrides the default 9-digit TIN length validation. |
placeholder |
string |
optional | Ghost text shown inside the field. |
hint |
string |
optional | Help text rendered below the field. |
readonly |
boolean |
optional | Renders the field non-editable. |
hideField |
boolean |
optional | Hides the field and excludes its value. Toggle via expressions["props.hideField"]. |
populates.valueKey)Keys returned by the FTINDETAILS endpoint. The adapter unwraps the RRA envelope, so
valueKey refers to a field inside ResponseObject — write SupplierName, not
ResponseObject.SupplierName.
valueKey |
Description |
|---|---|
SupplierName |
Company name |
SupplierTin |
Company TIN |
Category |
Taxpayer category — "Small taxpayer" or "Large taxpayer" |
ManagerNames |
Manager / representative full name |
NationalId |
Manager national ID — can be null |
EmailAddress |
Company email address |
PhoneNumber |
Company phone number |
Province |
Company province |
District |
Company district |
Sector |
Company sector |
Cell |
Company cell |
Village |
Company village |
DetailedAddress |
Free-text street address on the RRA record |
Fax |
Fax number — frequently null, don't rely on it |
Category is the field dynamic pricing, conditional attachments and small/large workflow branches
usually key on. It has exactly two values — "Small taxpayer" and "Large taxpayer" — and is
matched as an exact string, so use that spelling verbatim across pricing, display rules and
workflow conditions. If the field is hidden but still read downstream, hide it with
props.hideField — hide clears the model and disabled excludes the value from submission.
See Endpoint Field Reference for the full sample payload.
| Key | When it fires |
|---|---|
required |
Field is empty on submit |
invalidTIN |
TIN was entered but no company record was found |
invalidInput |
Input does not match the expected 9-digit TIN format |
{
"key": "TIN_NUMBER",
"type": "customtininput",
"props": {
"label": "TIN Number",
"placeholder": "Enter TIN Number",
"required": false,
"defaultRequired": true,
"url": "/integration/v1/fetch/sync",
"useBaseUrl": true,
"endpointCode": "FTINDETAILS"
},
"expressions": {
"props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
},
"validation": {
"messages": {
"required": "Please fill in this field",
"invalidTIN": "No details found for this TIN",
"invalidInput": "TIN number must be 9 digits"
}
}
}
{
"key": "COMPANY_TIN",
"type": "customtininput",
"props": {
"label": "Company TIN",
"placeholder": "Enter company TIN",
"required": false,
"defaultRequired": true,
"url": "/integration/v1/fetch/sync",
"useBaseUrl": true,
"endpointCode": "FTINDETAILS",
"populates": [
{ "valueKey": "SupplierName", "targetKey": "COMPANY_NAME" },
{ "valueKey": "SupplierTin", "targetKey": "COMPANY_TIN_CODE" },
{ "valueKey": "EmailAddress", "targetKey": "COMPANY_EMAIL" },
{ "valueKey": "PhoneNumber", "targetKey": "COMPANY_PHONE" }
]
},
"expressions": {
"props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
},
"validation": {
"messages": {
"required": "Company TIN is required",
"invalidTIN": "No company found for this TIN",
"invalidInput": "TIN number must be 9 digits"
}
}
}
{
"key": "GUARANTORS_COMPANY_TIN",
"type": "customtininput",
"props": {
"label": "Guarantor Company TIN",
"placeholder": "Enter TIN",
"required": false,
"defaultRequired": true,
"url": "/integration/v1/fetch/sync",
"useBaseUrl": true,
"endpointCode": "FTINDETAILS",
"usePrefetch": true,
"populates": [{ "valueKey": "SupplierName", "targetKey": "GUARANTORS_COMPANY_NAME" }]
},
"expressions": {
"props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
},
"validation": {
"messages": {
"required": "Please fill in this field",
"invalidTIN": "No details found for supplier",
"invalidInput": "TIN number must be 9 digits"
}
}
}
required: true directly — use required: false + defaultRequired: true + the expression. See Required fields.url — the component throws at runtime. Always set to /integration/v1/fetch/sync.endpointCode — the component throws at runtime. Always required.required, invalidTIN, and invalidInput.usePrefetch: true for citizen applicants — the prefetch silently finds nothing and leaves the field empty. Only use for logged-in business users.customtininput for individual citizens — use customidinput instead. customtininput is for company TINs only.key is UPPER_SNAKE_CASE and unique across the entire formprops.label is present, unique, and correctly casedsections > formly-group > block > customtininputrequired: false (never true)defaultRequired is setexpressions["props.required"] is present with the exact required expressionurl is /integration/v1/fetch/syncendpointCode is "FTINDETAILS"useBaseUrl: truevalidation.messages includes required, invalidTIN, and invalidInputusePrefetch: true only when the applicant is a logged-in business user