The Borrower Screening API filters and evaluates potential borrowers through proprietary signals derived from a subject's mobile number. Using phone-based behavioral data from participating institutions across the Smile Network, it surfaces a curated set of signals that Smile has optimized for lending risk assessment in specific markets.

Unlike Credit Lifecycle, which returns a published set of 30+ general-purpose risk signals, Borrower Screening returns a proprietary signal set. The exact signals returned are not documented in a public data dictionary but clients are encouraged to test these signals in Sandbox and validate them against their existing models before committing to a production configuration.

Borrower Screening checks are synchronous: results are returned immediately in the API response.

Smile Borrower Screening is currently in Beta.

Supported Markets

A single default template covers six markets. Each market draws from its own regional data sources within the Smile Network.

Template ID	Supported Markets
`tpl-sgn002001`	India (IN), Mexico (MX), Philippines (PH), Indonesia (ID), Colombia (CO), Thailand (TH)

For markets or use cases not covered by the default template, or if you require a custom signal configuration, contact your Smile account manager to request a specialized templateId.

About Proprietary Signals

The signals returned in the items array are proprietary to Smile and are not published in a public data dictionary. Each signal represents a behavioral or activity-derived risk indicator compiled from cross-institutional data in the Smile Network.

The recommended approach for new integrations is:

Run requests in Sandbox using the test values below to receive a representative set of signal names and values for your market.
Evaluate the signals against your risk model. Examine which signal names are returned, their value types, and how they correlate with outcomes in your existing data.
Contact Smile to discuss which signals to include in your production configuration and whether a customized template would better serve your use case.
Go live with the finalized signal set, knowing it has been validated against your scoring model.

📘
Mobile Number Privacy
MD5-encrypted phone input is accepted. Submit the encrypted value as MD5(countryCode + phone) — for example, MD5(639559991234) for a Philippine number. This allows you to pass the identifier without transmitting the raw phone number in plaintext.

How a Borrower Screening Request Works

Submit a Borrower Screening request using POST /beta/signals/createSignal2. Provide templateId, phone, countryCode, and consent.
Receive the result synchronously. The API returns the full Borrower Screening object in the response body. The items array contains each signal returned for your account configuration.
Evaluate the signals. Each item has a name (the signal identifier), a value, and a valueType (STRING, NUMBER, or BOOLEAN). The specific signals returned depend on your template configuration. Contact Smile if you need assistance interpreting them.

The Borrower Screening Objects

Request Object

Attribute	Type	Required	Description
templateId	string	Yes	The signal template to use. Use `tpl-sgn002001` for the default multi-market template, or a specialized ID provided by Smile.
consent	object	Yes	Evidence of the subject's consent. See Consent Templates for details.
phone	string	Yes	The subject's mobile number including country code, no leading zeros. Example: `639559991234`. MD5-encrypted input is also accepted (see note above).
countryCode	string	No	ISO 3166 alpha-2 country code for the subject's market. Example: `PH`. Recommended to include for accurate market routing.

Borrower Screening Object

This is the object returned in the response.

Attribute	Type	Description
id	string	Unique ID of this Borrower Screening record. IDs use the prefix `signal-`.
createdAt	date-time	Date and time when this record was created
status	string	Current processing status of the request. See Borrower Screening Statuses below.
resultCode	string	Final result code of the check. See Result Codes below.
resultMessage	string	Human-readable description of the result
signalType	string	Always `Signal2` for requests made through this API
requestMeta	object	Echo of the original request parameters sent with the check
items	array	The proprietary signals returned for this request. See Item Object below.

Item Object

Each entry in the items array represents a single proprietary risk signal.

Attribute	Type	Description
name	string	The signal identifier. Specific signal names depend on your template configuration.
value	string	The signal value, always returned as a string regardless of the underlying type
valueType	string	The data type of the value. One of: `STRING`, `NUMBER`, `BOOLEAN`

Borrower Screening Statuses

Status	Description
`PROCESSING`	The check is currently in progress
`COMPLETED`	The check has completed and results are available
`ERROR`	The check encountered an error and could not be completed

Result Codes

Result Code	Description	Billable
`SUCCESS`	The check completed and signal data was returned in the `items` array.	Yes
`NO_DATA`	Smile was unable to return signal data for the provided phone number.	No
`SYSTEM_ERROR`	An internal error occurred. Contact Smile support if this persists.	No
`SERVICE_UNAVAILABLE`	A required data source is temporarily unavailable.	No

📘
Billing Note
Borrower Screening checks are billed only on SUCCESS. NO_DATA results are not charged. Only the POST /beta/signals/createSignal2 endpoint is counted for billing — List and Get requests are not charged.

Sample Borrower Screening data

{
  "id": "signal-e35d521ef8f147c4aa01b7c1af85aaf7",
  "createdAt": "2021-04-14T09:30:24Z",
  "status": "COMPLETED",
  "resultCode": "SUCCESS",
  "resultMessage": "Success",
  "signalType": "Signal2",
  "requestMeta": {
    "templateId": "tpl-sgn002001",
    "phone": "639559991234",
    "countryCode": "PH",
    "consent": {
      "type": "Terms And Conditions",
      "version": "1.0.0",
      "consentedWith": "I agree to the terms and conditions.",
      "consentedAt": "2021-04-14T09:30:24Z",
      "consentTemplateId": null
    }
  },
  "items": [
    {
      "name": "events_arbitrary_day30",
      "value": "0",
      "valueType": "NUMBER"
    },
    {
      "name": "events_preloan_day30",
      "value": "2",
      "valueType": "NUMBER"
    },
    {
      "name": "events_debt_day90_amount",
      "value": "A0",
      "valueType": "STRING"
    }
  ]
}

Sandbox Testing

Use the following values to trigger a successful response in the Sandbox environment. Any other valid phone and country code combination will return resultCode: NO_DATA with an empty items array.

Parameter	Value	Expected Response
`templateId`	`tpl-sgn002001`
`countryCode`	`PH`
`phone`	`639559991234`	`resultCode: SUCCESS`

Endpoints

📘
Shared List and Get Endpoints
The List and Get endpoints are shared with other Signals products, including Credit Lifecycle and Social Security Signals. When listing, use the signalType=Signal2 query parameter to filter for Borrower Screening records only.

Endpoint
Create Borrower Screening check	`POST /beta/signals/createSignal2`
List Borrower Screening checks	`GET /beta/signals`
Retrieve one Borrower Screening check	`GET /beta/signals/{id}`