canonical: https://jentic.com/apis/getsmileapi.com/smileapi

# Getsmileapi Smile API

Smile API provides employment, payroll, and income data through user-permissioned account linking, primarily for fintech, lending, and HR-tech use cases in Asia. The platform's full API surface exposes 103 endpoints covering users, providers, accounts, consent templates, webhooks, tasks, invites, and detailed records such as identities, employments, incomes, transactions, and documents. It is the canonical surface for verifying applicant income, pre-filling onboarding flows from authoritative payroll sources, and monitoring continued account-linkage health.

## For AI agents

Link payroll and employment accounts, fetch user-permissioned identity, income, and transaction records, and manage webhooks and consent templates through HTTP basic auth.

## Scope

Does not handle KYC document verification, payment disbursement, or credit scoring - use for user-permissioned employment, payroll, and income data linking only.

## Capabilities

- Create users and mint session payloads that drive the Smile Link account-linking flow
- List supported payroll and employment data providers and inspect a single provider
- Fetch identity, employment, income, transaction, and document records once a user has linked an account
- Manage consent templates that govern what data scopes a user is asked to authorise
- Subscribe to webhooks for events such as account linked, refresh, or revoke
- Generate account exports and disable monitoring on a per-account basis

## Use cases

### Income verification for lending

Lenders verify applicant income by asking the borrower to link their payroll provider through Smile Link, then pulling normalised income and employment records via the API. This replaces document uploads and manual review with structured, source-of-truth payroll data, shortening the underwriting cycle.

Example prompt: Create a user, drive the linking flow, and once linked fetch the latest 6 months of income records for underwriting

### Onboarding pre-fill from payroll

HR-tech and benefits platforms pre-fill onboarding forms with employer name, role, and pay frequency by reading the user's linked employment record. The /employments and /identities endpoints give a stable shape so the form can render fields consistently across providers.

Example prompt: On user usr_123, fetch the most recent employment record and pre-fill the onboarding form

### Webhook-driven monitoring

Continuous-verification products subscribe to Smile webhooks for events like new income deposit or employment change and update the customer's risk profile in real time. The /webhooks endpoints handle subscription CRUD and the /tasks endpoint exposes background-refresh state when an account needs re-authentication.

Example prompt: Create a webhook on event 'income.received' pointing at our backend and verify the first delivery

### AI agent for compliant data export

An AI agent connected through Jentic accepts an end-user request to download their data, calls `/accounts/{id}/exports/generate`, polls until ready, and returns the export URL. Jentic injects the basic-auth header so the agent never holds the raw API secret.

Example prompt: Generate an export for account acc_456 and return the download URL once the task completes

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/users` | Create a Smile user |
| GET | `/users/{id}/payload` | Get session payload for Smile Link |
| GET | `/providers` | List supported data providers |
| GET | `/accounts` | List linked accounts |
| POST | `/accounts/{id}/exports/generate` | Generate an account data export |
| POST | `/webhooks` | Create a webhook subscription |
| POST | `/consentTemplates` | Create a consent template |

## Key resources

- **Users** — End users who authorise account linking through the Smile Link flow
- **Providers** — Supported payroll, employment, and gig-economy data sources
- **Accounts** — Per-user linked accounts with payload, export, and monitor controls
- **Records** — Normalised identities, employments, incomes, transactions, and documents
- **Consent templates** — Configurable data-scope prompts shown to end users
- **Webhooks** — Event subscriptions for linkage and refresh lifecycle
- **Tasks and invites** — Background work and invite-flow controls for account linking

## Why Jentic

- **Setup:** Wiring the Smile API by hand means encoding your client id and secret into a basic-auth header, choosing between the sandbox and open smileapi.io hosts, and handling user-permissioned data flows yourself. Through Jentic you install once, import the Smile API from the API Directory, store the client id and secret once, and your agent calls it.
- **Permission scoping:** Smile puts the user and account id in the URL path (`/users/{id}/payload`, `/accounts/{id}/exports/generate`), so a rule can pin your agent to one user's linked records: it can read that payload and generate its exports and nothing else. You choose the operations it may call, so creating users or webhooks is not included unless you add them.
- **Credential handling:** Your Smile client id and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fetch a user's income records' or 'link a payroll provider', and Jentic returns the matching Smile operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Plaid API** — Bank-account aggregation and income verification, primarily in North America and Europe
- **Stripe API** — Payment rails that often pair with Smile-verified income for lending or BNPL flows
- **Onfido API** — Identity verification through document and biometric checks alongside Smile's income data

## FAQ

### What authentication does the Smile API use?

Smile API uses HTTP basic authentication with your client id and client secret. Through Jentic the credentials are stored encrypted in the vault and the basic-auth header is built per request, so the raw secret never enters agent context.

### Can I fetch a user's income records once they have linked an account?

Yes. Once the user completes account linking, GET /incomes returns paged income records for that user across their accounts, and GET `/incomes/{id}` retrieves a specific record. The same pattern applies to /employments, /identities, /transactions, and /documents.

### What are the rate limits for the Smile API?

The OpenAPI spec does not encode explicit rate limits. Practical guidance is to use webhooks for change-driven workflows rather than polling /accounts or /incomes in tight loops, and to back off on any 429 response with exponential delay before retrying.

### How do I start the account-linking flow through Jentic?

Search Jentic for 'create smile user session', load the POST /users and GET `/users/{id}/payload` schemas, and execute them in sequence to receive the session payload Smile Link consumes on the front end. Jentic handles the basic-auth credential injection.

### Can I subscribe to webhooks for linkage events?

Yes. POST /webhooks creates a subscription for events such as 'account.linked' or 'income.received', and DELETE `/webhooks/{id}` removes one. Pair this with /tasks to inspect background-refresh state for accounts that need re-authentication.

### Is the Smile API free?

Smile offers a sandbox environment for development at no charge against sandbox.smileapi.io. Production usage at open.smileapi.io is metered and requires a commercial agreement; check getsmileapi.com or contact info@getsmileapi.com for current pricing tiers.

### Can I limit what my agent is allowed to do with the Smile API?

Yes. Because you run Jentic One yourself, your own rules decide which Smile operations and credentials the agent may use, and Smile puts the user and account id in the URL path, so a rule can pin the agent to a single user's linked records. For example, you can allow it to read GET `/users/{id}/payload` and call POST `/accounts/{id}/exports/generate` for one account while denying everything else. Operations like POST /users, POST /webhooks, and POST /consentTemplates stay off limits unless you explicitly add them to the agent's allowed set.