Skip to content

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.

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

POSThttps://gateway.staging.finsour.io/v1/banking/bank-account-by-mobile

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

Scheme API key travels in the X-Api-Key header

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

Content type application/json

Headers

NameTypeRequiredDescriptionConstraints
Idempotency-KeystringRequiredA 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

NameTypeRequiredDescriptionConstraints
inputobjectRequiredThe details to check.—
input.mobilestringRequired—Matches ^[6-9][0-9]{9}$. Exactly 10 characters
optionsobjectRequiredSettings for this call. This API requires consent.—
options.referencestringOptionalYour own reference for this call. It comes back unchanged as meta.reference.1 to 128 characters
options.consentobjectRequiredThe person's consent to this check.—
options.consent.obtainedbooleanRequiredSend true once the person has agreed to the check.Always true
options.consent.atstring (date-time)RequiredWhen the person gave consent.—
options.consent.purposestringRequiredWhat 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

Status 200 · content type application/json

NameTypePresentDescriptionConstraints
dataobjectAlwaysThe result of the check.—
data.foundbooleanAlways——
data.maskedMobilestringAlwaysThe mobile number sent, as its display form.Matches ^X{6}[0-9]{4}$
data.maskedAccountNumberstring or any or nullAlwaysThe linked account's display form. The platform never holds or returns the full number.—
data.ifscstring or any or nullAlways——
data.nameAtBankstring or nullAlwaysThe account holder's name as the bank holds it.—
data.sourceobjectAlways——
data.source.fetchedAtstringAlwaysWhen 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

CodeStatusMeaningRetrying
API_VERSION_UNSUPPORTED400That API version is no longer supported.Do not retry automatically
IDEMPOTENCY_KEY_INVALID400That Idempotency-Key does not meet the required format.Do not retry automatically
IDEMPOTENCY_KEY_REQUIRED400An Idempotency-Key header is required for this request.Do not retry automatically
REQUEST_MALFORMED400The request could not be parsed.Do not retry automatically
AUTH_KEY_EXPIRED401The API key is not valid.Do not retry automatically
AUTH_KEY_INVALID401The API key is not valid.Do not retry automatically
AUTH_KEY_MISSING401No API key was presented.Do not retry automatically
AUTH_KEY_REVOKED401The API key is not valid.Do not retry automatically
INSUFFICIENT_BALANCE402The available balance is not enough for this request.Do not retry automatically
AUTH_IP_NOT_ALLOWED403This API key may not be used from this address.Do not retry automatically
ENTITLEMENT_MISSING403This organization is not entitled to that product in this environment.Do not retry automatically
ORGANIZATION_SUSPENDED403This organization is not active.Do not retry automatically
PRODUCT_NOT_AVAILABLE403That product is not available.Do not retry automatically
PRODUCT_RETIRED403That product has been withdrawn.Do not retry automatically
SCOPE_INSUFFICIENT403This API key does not carry the scope this product requires.Do not retry automatically
PRODUCT_NOT_FOUND404No such product.Do not retry automatically
IDEMPOTENCY_KEY_REUSED409That idempotency key was already used for a different request.Do not retry automatically
PRICE_UNAVAILABLE409No active price covers this product right now.Safe to retry
REQUEST_IN_PROGRESS409An earlier attempt with this key is still running.Safe to retry
SETTLEMENT_PENDING409This request is awaiting reconciliation by an operator.Do not retry automatically
API_VERSION_SUNSET410That API version passed its announced sunset date.Do not retry automatically
REQUEST_TOO_LARGE413The request body is too large.Do not retry automatically
UNSUPPORTED_MEDIA_TYPE415That content type is not accepted on this route.Do not retry automatically
CONSENT_REQUIRED422This product requires an explicit consent flag.Do not retry automatically
SANDBOX_FIXTURE_MISSING422No sandbox fixture exists for this input. Use a different test value.Do not retry automatically
UPSTREAM_REJECTED422The upstream source rejected the input.Do not retry automatically
VALIDATION_FAILED422The request payload is invalid.Do not retry automatically
CONCURRENCY_LIMIT429Too many simultaneous requests.Safe to retry
QUOTA_EXCEEDED429The allowance for this window is spent.Do not retry automatically
RATE_LIMITED429Too many requests.Safe to retry
INTERNAL_ERROR500An unexpected error occurred.Safe to retry
OUTCOME_UNCERTAIN502The outcome of this request is not yet known. Retry with the same Idempotency-Key.Do not retry automatically
UPSTREAM_UNAVAILABLE502The upstream source is unavailable. Retry shortly.Safe to retry
MAINTENANCE_MODE503The service is in a maintenance window.Safe to retry
NO_PROVIDER_AVAILABLE503No provider can serve this product right now.Safe to retry
SERVICE_OVERLOADED503The service is shedding load. Retry shortly.Safe to retry
UPSTREAM_TIMEOUT504The 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

ScopeLimitWindowAt the limit
Your API key, within your organisation's limitThe figure in X-RateLimit-LimitPer minute429 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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 .