The Blacklist API checks whether a subject's mobile number appears in Smile's blacklist data sources for a given country. A blacklist hit indicates that the mobile number has been associated with adverse events — such as fraud, delinquency, or defaulted obligations — recorded by financial institutions and other participating data providers in the Smile Network.

Blacklist checks are synchronous: results are returned immediately in the API response, with no need for webhooks or polling.

Smile Blacklist is currently in Alpha.

How a Blacklist Check Works

Submit a Blacklist request using the POST /alpha/blacklists endpoint. At minimum, provide the subject's mobileNumber and a valid consent object.
Receive the result synchronously. The API returns the full Blacklist object in the response body, including a result.hit boolean and a list of dates on which blacklist events were recorded for this mobile number.
Evaluate the result. If result.hit is true, the subject's mobile number was found on the blacklist. The result.dates array contains the dates on which the blacklist entries were recorded, which you can use to assess the recency and frequency of adverse events.

📘
About applicationDate
applicationDate is an optional field. When provided, Smile queries blacklist data recorded before that date, allowing you to perform point-in-time evaluations. If omitted, the check is evaluated against the current date, which is the recommended behavior for real-time screening.

Supported Markets

Template ID	Market	Required Parameters
`tpl-blk002001`	PH (default)	`consent`, `mobileNumber`, `countryCode`

If you require blacklist screening for other markets, contact your Smile account manager for available templates and the corresponding templateId.

The Blacklist Objects

Request Object

This is the object you send when creating a Blacklist check.

Attribute	Type	Required	Description
mobileNumber	string	Yes	The subject's mobile number, including country code. No leading zeros. Example: `639178912345`
countryCode	string	No	ISO 3166 alpha-2 country code for the market to screen against. Defaults to `PH`.
templateId	string	No	The blacklist template to use. If not provided, Smile uses the default template for the specified country. Contact your account manager for non-default templates.
applicationDate	date	No	The date for the point-in-time evaluation, in `YYYY-MM-DD` format. If omitted, the check is evaluated against the current date.
consent	object	Yes	Evidence of the subject's consent to the blacklist check. See Consent Templates for details.

Blacklist Object

This is the object returned in the response.

Attribute	Type	Description
id	string	Unique ID of this Blacklist record. IDs use the prefix `blacklist-`.
createdAt	date-time	Date and time when this Blacklist record was created
status	string	Current processing status of the request. See Blacklist Statuses below.
resultCode	string	Final result code of the check. See Result Codes below.
resultMessage	string	Human-readable description of the result
requestMeta	object	Echo of the original request parameters sent with the check
result	object	The blacklist check result. See Result Object below.

Result Object

Attribute	Type	Description
hit	boolean	`true` if the subject's mobile number was found on the blacklist; `false` if no match was found.
dates	array of dates	The dates on which blacklist events were recorded for this mobile number, in `YYYY-MM-DD` format. Empty if `hit` is `false`.

Blacklist Statuses

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

Result Codes

Result Code	Description	Billable
`SUCCESS`	The check completed successfully. Inspect `result.hit` for the outcome.	Yes
`NO_DATA`	Smile was unable to return a result for the provided input.	Yes
`SYSTEM_ERROR`	An internal error occurred. Contact Smile support if this persists.	No
`SERVICE_UNAVAILABLE`	The blacklist data source is temporarily unavailable.	No

📘
Billing Note
Blacklist checks are billed on request for both SUCCESS and NO_DATA result codes. Only the POST /alpha/blacklists endpoint is counted for billing — List and Get requests are not charged.

Sample Blacklist data

{
  "id": "blacklist-e35d521ef8f147c4aa01b7c1af85aaf7",
  "createdAt": "2021-04-14T09:30:24Z",
  "status": "COMPLETED",
  "resultCode": "SUCCESS",
  "resultMessage": "Success!",
  "requestMeta": {
    "mobileNumber": "639559991234",
    "countryCode": "PH",
    "applicationDate": "2021-04-14",
    "templateId": "tpl-blk002001",
    "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
    }
  },
  "result": {
    "hit": true,
    "dates": [
      "2021-04-14",
      "2021-03-14",
      "2021-02-14"
    ]
  }
}

Sandbox Testing

Use the following values to trigger a blacklist hit in the Sandbox environment. All other valid mobile number and country code combinations will return resultCode: SUCCESS with hit: false.

Parameter	Value	Expected Response
`mobileNumber`	`639559991234`	`resultCode: SUCCESS`, `hit: true`
`countryCode`	`PH`

Endpoints

Endpoint
Create Blacklist check	`POST /alpha/blacklists`
List Blacklist checks	`GET /alpha/blacklists`
Retrieve one Blacklist check	`GET /alpha/blacklists/{id}`

How a Blacklist Check Works

About applicationDate

Supported Markets

The Blacklist Objects

Request Object

Blacklist Object

Result Object

Blacklist Statuses

Result Codes

Billing Note

Sample Blacklist data

Sandbox Testing

Endpoints

About `applicationDate`