Mobile to Account Lookup API
New
Find the bank account information linked to a mobile number your customer has given you, with their consent. Payout details get confirmed instead of typed from memory.
Overview
A mobile to account lookup takes a mobile number the customer has provided and returns the bank account information associated with it in available records. It suits journeys where you already hold a consented mobile number and need the account details that go with it. The customer does not have to recall an account number and IFSC code. Bank details typed from memory are where a great many payout errors begin. Resolving them from a number the customer has already confirmed removes a step from the form, and removes a class of transposition errors from the payout file. This is a personal-data service. Use it only where the customer has given informed consent for the lookup and you have a defined, lawful purpose for it. What comes back depends on available information and on the selected service contract.
- Category
- Banking Services
- Coverage
- Consented Indian mobile numbers. What resolves depends on available information and the selected service contract.
- Input
- A mobile number the customer has provided, with consent for this purpose
- Output
- Associated bank account information where available. Fields vary by data source and record.
- Typical users
- Lenders, insurers, payment service providers, marketplaces, gig and logistics platforms
- Consent note
- Requires informed customer consent and a defined, lawful purpose. Not for tracing, locating or profiling a person.
The overview and the sections after the reference are the FinSour API catalog’s own record for this service, rendered unaltered.
Endpoint URL and method
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Authentication
Send your API key in this header on every call, from your own server: a key sent from a browser is refused. A key starting fs_test_ calls the sandbox and one starting fs_live_ calls production, at the same address. Create keys in the FinSour console.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Request parameters
Headers
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
Idempotency-Key | string | Required | A key you generate for each attempt. Sending the same key again returns the first answer instead of running the check twice; the same key with a different body is refused. | 8 to 255 characters. Matches ^[A-Za-z0-9._:-]+$ |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
input | object | Required | The details to check. | — |
input. | string | Required | — | Matches ^[6-9][0-9]{9}$. Exactly 10 characters |
options | object | Required | Settings for this call. This API requires consent. | — |
options. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
options. | object | Required | The person's consent to this check. | — |
options. | boolean | Required | Send true once the person has agreed to the check. | Always true |
options. | string (date-time) | Required | When the person gave consent. | — |
options. | string | Required | What the check is for, for example kyc. | 1 to 64 characters |
Request samples
cURL
curl -X POST https://gateway.staging.finsour.io/v1/banking/bank-account-by-mobile \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": {
"mobile": "<mobile>"
},
"options": {
"consent": {
"obtained": true,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc"
}
}
}'Node.js
const response = await fetch("https://gateway.staging.finsour.io/v1/banking/bank-account-by-mobile", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"input": {
"mobile": "<mobile>"
},
"options": {
"consent": {
"obtained": true,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc"
}
}
}),
});
console.log(response.status, await response.json());Python
import os
import uuid
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/banking/bank-account-by-mobile",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"input": {
"mobile": "<mobile>",
},
"options": {
"consent": {
"obtained": True,
"at": "2026-09-01T10:00:00Z",
"purpose": "kyc",
},
},
},
timeout=30,
)
print(response.status_code, response.json())Generated from the fields above. Replace each value in angle brackets with your own; the key is read from FINSOUR_API_KEY.
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Response schema
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
data | object | Always | The result of the check. | — |
data. | boolean | Always | — | — |
data. | string | Always | The mobile number sent, as its display form. | Matches ^X{6}[0-9]{4}$ |
data. | string or any or null | Always | The linked account's display form. The platform never holds or returns the full number. | — |
data. | string or any or null | Always | — | — |
data. | string or null | Always | The account holder's name as the bank holds it. | — |
data. | object | Always | — | — |
data. | string | Always | When the answer was fetched: RFC 3339 UTC with a Z, never an epoch or an IST offset. | Matches ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Error codes
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
CONSENT_REQUIRED | 422 | This product requires an explicit consent flag. | Do not retry automatically |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The upstream source did not respond in time. | Safe to retry |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Rate limits
| Scope | Limit | Window | At the limit |
|---|---|---|---|
| Your API key, within your organisation's limit | The figure in X-RateLimit-Limit | Per minute | 429 RATE_LIMITED, with Retry-After in seconds. Every answer past authentication carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. |
Supplied by FinSour platform API contract (finsour development at 80e8b83bf) on . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.
Use cases
- Fintech and PSPs: prefill payout details from a consented mobile number
- Lending and NBFCs: confirm the account a borrower nominated for disbursal
- Insurance: resolve payee account details for a consented claimant
- Staffing and gig platforms: set up worker payouts without manual entry
- Logistics and fleet: onboard owner-drivers with fewer typed fields
- Marketplaces: confirm a seller settlement account at registration
What this service does
Starts from a number the customer gave you
The request begins with a mobile number the customer supplied and agreed you could use for this purpose. The account details that follow have a traceable origin.
Fewer typed fields in the payout file
A transposed digit in an account number passes every form validation and fails at payout. Resolving details, instead of asking a customer to recall them, removes a whole class of errors from the payout file.
Built for consented journeys only
The service belongs in journeys where the person has been told what the lookup is for and has agreed to it. Consent is specific to that purpose, and the result should be used only for it.
A structured result, and its limits
Where a match is available, the response can carry associated account information for use in your workflow. Available fields vary by data source and record, and a number may resolve nothing at all, which your flow should handle as an ordinary outcome.
How a check runs
Get consent for this lookup
Tell the customer in plain language what the lookup is for, and get their informed consent for that specific purpose. Record what they were told and when they agreed.
Send the consented mobile number
Your onboarding screen, payout setup flow or claims console sends the number through the API, as part of the journey the customer is already in.
Read the account details that come back
The response can carry bank account information associated with the number, subject to what the underlying data source holds for that record.
Ask the customer to confirm the account
Show the resolved details back on screen and ask the customer to confirm or correct them. The one person who knows the right account can then say so, before you set up a payout.
Save the account and the consent record
Keep the confirmed details, the consent record, the purpose and the timestamp together against the customer record. Then continue with account verification or payout setup.
Questions
- What does a mobile to account lookup return?
- It takes a mobile number the customer has provided and agreed you can use, and returns the bank account information associated with that number in available records. Payout details can then be confirmed on screen instead of typed from memory.
- Do I need consent for a mobile to account lookup?
- Yes. This service handles personal financial data. Run it only where the customer has given informed consent for the specific lookup and you have a defined, lawful purpose for it. Record that consent and be able to produce it later.
- Can I look up someone's bank account without asking them?
- No. The service is for consented journeys connected to a relationship the customer has with you, such as setting up a payout or confirming a nominated account. Do not use it to trace, locate or profile a person, or to check details for anyone who is not your consented customer.
- What account details come back from a mobile number?
- Where a match is available, the response can carry bank account information associated with the submitted number, along with the name held against the record. The available fields vary with the underlying data source and the record, and depend on the selected service contract.
- What happens if the mobile number resolves to nothing?
- An empty result is an ordinary outcome. Not every mobile number has an association that can be resolved, and information can be out of date. Your flow should fall back to asking the customer for their account details directly.
- Does a mobile to account lookup replace account verification?
- No. Resolving account details and confirming that an account can receive money are different questions. Where the payout matters, pair the lookup with a verification step such as a penny drop or penny less check before releasing funds.
Catalog entry last updated .