---
updatedAt: 2026-09-09T09:27:29.000Z
agentTools:
  projectIndex: https://docs.getsmileapi.com/llms.txt
---

# Income Estimators

The Income Estimator predicts the likelihood that a subject belongs to a higher income segment, using behavioral signals derived from their email address. It does not verify actual income or predict an individual's exact monthly earnings. Instead, it returns a probability score that the subject is a high earner, along with a simplified income tier and a reference income range associated with that tier.

Income Estimator is well-suited for pre-screening, customer segmentation, and enriching credit decisioning workflows where verified income documentation is unavailable or impractical to collect.

Income Estimator checks are **synchronous**: the result is returned immediately in the API response.

<Callout icon="📘" theme="info">
  ### Alpha Access

  Income Estimator is currently in **Alpha**. Access is by invitation only. Contact your Smile representative to enable it for your account.
</Callout>

***

## Supported Markets

| Template ID               | Market           | Required Parameters                      |
| :------------------------ | :--------------- | :--------------------------------------- |
| `tpl-incomeestimator-001` | Philippines (PH) | `consent`, `emailAddress`, `countryCode` |

***

## How an Income Estimator Request Works

1. **Submit a request** using `POST /incomes/alpha/incomeestimators`. Provide `templateId`, `consent`, `emailAddress`, and `countryCode`.

2. **Receive the result synchronously.** The API returns the complete IncomeEstimator object in the response body. When `resultCode` is `SUCCESS`, the `result` object contains the model outputs.

3. **Evaluate the outputs.** Use `probability` as the primary decisioning signal. `tier` is a convenience label for segmentation and display purposes. See [Interpreting the Outputs](#interpreting-the-outputs) below.

***

## The IncomeEstimator Object

### Request Object

| Attribute      | Type   | Required | Description                                                                               |
| :------------- | :----- | :------- | :---------------------------------------------------------------------------------------- |
| `templateId`   | string | Yes      | The template to use. Must be `tpl-incomeestimator-001`.                                   |
| `consent`      | object | Yes      | Evidence of the subject's consent. See [Consent Templates](https://docs.getsmileapi.com/reference/consent-templates). |
| `emailAddress` | string | Yes      | The subject's email address. Must be a valid email format.                                |
| `countryCode`  | string | Yes      | ISO 3166 alpha-2 country code for the subject's market. Example: `PH`.                    |

### IncomeEstimator Object

This is the object returned in the API response.

| Attribute       | Type      | Description                                                                                |
| :-------------- | :-------- | :----------------------------------------------------------------------------------------- |
| `id`            | string    | Unique ID of this IncomeEstimator record. IDs use the prefix `iest-`.                      |
| `createdAt`     | date-time | Date and time when the record was created.                                                 |
| `status`        | string    | Current processing status. See [Statuses](#statuses) below.                                |
| `resultCode`    | string    | Final result code of the check. See [Result Codes](#result-codes) below.                   |
| `resultMessage` | string    | Human-readable description of the result. `null` on success.                               |
| `requestMeta`   | object    | Echo of the original request parameters.                                                   |
| `result`        | object    | The model outputs. Present only when `resultCode` is `SUCCESS`. See *Result Object* below. |

### Result Object

| Attribute      | Type   | Description                                                                                                                                                                              |
| :------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `income`       | object | The income range and tier associated with the model's prediction. See *Income Object* below.                                                                                             |
| `probability`  | number | The model's raw probability (0–1) that the subject is a high earner. **Use this as the primary decisioning signal.** A higher value indicates a stronger high-income signal.             |
| `certainty`    | string | A categorical measure of how far `probability` is from the model's decision boundary of 0.5. One of: `HIGH`, `MEDIUM`, `LOW`. See [Interpreting the Outputs](#interpreting-the-outputs). |
| `modelVersion` | string | The version of the model used to produce the result.                                                                                                                                     |

### Income Object

| Attribute    | Type   | Description                                                                                                                                       |
| :----------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `monthlyMin` | number | The lower bound of the income range associated with the predicted tier. In the currency specified by `currency`.                                  |
| `monthlyMax` | number | The upper bound of the income range associated with the predicted tier. In the currency specified by `currency`.                                  |
| `currency`   | string | ISO 4217 currency code for the income range values. Example: `PHP`.                                                                               |
| `tier`       | string | A convenience label for the predicted income segment. One of: `LOW`, `MIDDLE`, `HIGH`. See [Interpreting the Outputs](#interpreting-the-outputs). |

***

## Statuses

| Status       | Description                                                     |
| :----------- | :-------------------------------------------------------------- |
| `PROCESSING` | The check is in progress.                                       |
| `COMPLETED`  | The check has completed. Evaluate `resultCode` for the outcome. |
| `ERROR`      | The check encountered an error and could not complete.          |

Because Income Estimator checks are synchronous, responses typically return with `status: COMPLETED` immediately.

***

## Result Codes

| Result Code           | Description                                                                  | Billable |
| :-------------------- | :--------------------------------------------------------------------------- | :------- |
| `SUCCESS`             | The check completed and model outputs are available in the `result` object.  | Yes      |
| `NO_DATA`             | Smile was unable to generate a prediction for the provided email address.    | No       |
| `SYSTEM_ERROR`        | An internal error occurred. Contact Smile support if this persists.          | No       |
| `SERVICE_UNAVAILABLE` | A required service is temporarily unavailable. Retry after a short interval. | No       |

<Callout icon="📘" theme="info">
  ### Billing Note

  Income Estimator checks are billed on `SUCCESS` only. `NO_DATA` results are not charged. Only the `POST /incomes/alpha/incomeestimators` endpoint counts toward billing — List and View requests are not charged.
</Callout>

***

## Interpreting the Outputs

### Probability (Primary Signal)

`probability` is the model's raw prediction score — the likelihood that the subject is a high earner. It ranges from 0 to 1. Use it as the primary decisioning input.

| Probability | Interpretation              |
| :---------- | :-------------------------- |
| ≥ 0.85      | Strong high-income signal   |
| 0.70 – 0.84 | Moderate high-income signal |
| 0.50 – 0.69 | Near the decision boundary  |
| < 0.50      | Non-high-income signal      |

Two subjects can receive the same `tier` while having meaningfully different `probability` values. For automated decisioning, always use `probability` directly rather than relying on tier alone.

> Recommended thresholds in the table above are illustrative. Calibrate against your organization's risk appetite and historical performance data.

### Tier

`tier` maps the `probability` score to a simplified income segment. It is intended for customer segmentation, UI display, and portfolio reporting — not for direct use as a decisioning threshold.

| Tier     | Monthly Income Reference (PHP) |
| :------- | :----------------------------- |
| `LOW`    | ≤ 17,250                       |
| `MIDDLE` | 17,251 – 29,250                |
| `HIGH`   | > 29,250                       |

### Income Range (`monthlyMin` / `monthlyMax`)

The `income` object returns the predefined range boundaries for the predicted tier. These values are **not a personalized income estimate** — every subject classified into the same tier receives the same `monthlyMin` and `monthlyMax`. The range represents the tier boundary, not an individual prediction.

### Certainty

`certainty` measures how far `probability` is from the model's decision boundary of 0.5. A `HIGH` certainty means the model's prediction is decisive in either direction — it does not indicate which direction. This can be counterintuitive:

| Probability | Certainty | Meaning                                                       |
| :---------- | :-------- | :------------------------------------------------------------ |
| 0.92        | HIGH      | Model is very confident the subject **is** a high earner.     |
| 0.51        | LOW       | Model prediction is close to the boundary — less decisive.    |
| 0.08        | HIGH      | Model is very confident the subject **is not** a high earner. |

Use `certainty` alongside `probability` to gauge result reliability, not to interpret direction.

***

## What Income Estimator Is Not

Income Estimator is a behavioral prediction tool, not an income verification product. Avoid using it as:

* An exact prediction of a subject's monthly income
* A substitute for verified income documentation
* The sole approval criterion for any lending or credit decision

***

## Sample IncomeEstimator Data

```json
{
  "id": "iest-9ae6f7f14b0640e69c5199c2453d2f92",
  "createdAt": "2026-08-18T06:32:14Z",
  "status": "COMPLETED",
  "resultCode": "SUCCESS",
  "resultMessage": null,
  "requestMeta": {
    "templateId": "tpl-incomeestimator-001",
    "emailAddress": "gpalomero1234@smileapi.io",
    "countryCode": "PH",
    "consent": {
      "type": "Terms And Conditions",
      "version": "1",
      "consentedAt": "2021-04-14T09:30:24Z",
      "consentedWith": "I agree to the terms and conditions.",
      "consentTemplateId": null
    }
  },
  "result": {
    "income": {
      "monthlyMin": 17251,
      "monthlyMax": 29250,
      "currency": "PHP",
      "tier": "HIGH"
    },
    "probability": 0.7388,
    "certainty": "MEDIUM",
    "modelVersion": "1.0.0"
  }
}
```

***

## Sandbox Testing

Use the following values to trigger a `SUCCESS` response in the Sandbox environment. Any other valid input combination will return `resultCode: NO_DATA`.

| Parameter      | Test Value                  | Expected Response     |
| :------------- | :-------------------------- | :-------------------- |
| `templateId`   | `tpl-incomeestimator-001`   |                       |
| `countryCode`  | `PH`                        |                       |
| `emailAddress` | `gpalomero1234@smileapi.io` | `resultCode: SUCCESS` |

***

## Endpoints

| Endpoint                                                                  |                                            |
| :------------------------------------------------------------------------ | :----------------------------------------- |
| [Create Income Estimator check](https://docs.getsmileapi.com/reference/create-alpha-income-estimator) | `POST /incomes/alpha/incomeestimators`     |
| [List Income Estimator checks](https://docs.getsmileapi.com/reference/list-alpha-income-estimators)   | `GET /incomes/alpha/incomeestimators`      |
| [View an Income Estimator check](https://docs.getsmileapi.com/reference/get-alpha-income-estimator)   | `GET /incomes/alpha/incomeestimators/{id}` |