Utility Bill OCR API
New
Read an electricity, water, gas, phone or broadband bill and get the provider, consumer number, customer name, address, PIN code, bill dates and amount due as fields.
Overview
Utility Bill OCR reads a utility bill an applicant uploads, often as proof of address, and returns what is printed on it as structured fields. The response carries the bill type, the provider name, the consumer number, the customer name, the address and PIN code, the bill number and date, the due date, the billing period, and the amount due. A bill shows where a service is supplied and in whose name. OCR reads it; it does not confirm the account with the provider. Compare the name and address with the rest of the application.
- Category
- Document OCR APIs
- Coverage
- Electricity, water, gas, telephone and broadband bills issued in India, as images or PDFs
- Input
- A utility bill image or PDF uploaded by the applicant, with consent
- Output
- Bill type, provider, consumer number, customer name, address, PIN code, bill number, bill and due dates, billing period and amount due
- Typical users
- Lending, banking, insurance, rental and utility onboarding teams
- Coverage note
- Reads the printed bill; it does not confirm the account with the provider
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._:-]+$ |
FinSour-Version | string | Required | Send 2026-11-01 on this call and on every poll to get the receipt and the result described on this page. A call without it is served under 2026-09-01, whose job has a different shape. | — |
Body
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
file | file | Required | The document to read. | — |
payload | string (JSON) | Required | A JSON string carrying the call's options. | — |
payload. | object | Required | Settings for this call. This API requires consent. | — |
payload. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
payload. | object | Required | The person's consent to this check. | — |
payload. | boolean | Required | Send true once the person has agreed to the check. | Always true |
payload. | string (date-time) | Required | When the person gave consent. | — |
payload. | 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/documents/utility-bill \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "FinSour-Version: 2026-11-01" \
-F "file=@<path-to-document>" \
-F 'payload={"options":{"consent":{"obtained":"<obtained>","at":"<at>","purpose":"<purpose>"}}}'Node.js
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("file", await openAsBlob("<path-to-document>"));
form.append("payload", JSON.stringify({
"options": {
"consent": {
"obtained": "<obtained>",
"at": "<at>",
"purpose": "<purpose>"
}
}
}));
const response = await fetch("https://gateway.staging.finsour.io/v1/documents/utility-bill", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"FinSour-Version": "2026-11-01",
},
body: form,
});
console.log(response.status, await response.json());Python
import os
import uuid
import json
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/documents/utility-bill",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
"FinSour-Version": "2026-11-01",
},
files={"file": open("<path-to-document>", "rb")},
data={"payload": json.dumps({
"options": {
"consent": {
"obtained": "<obtained>",
"at": "<at>",
"purpose": "<purpose>",
},
},
})},
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 job that will read the document. | — |
data. | string | Always | The job's id. Poll GET /v1/jobs/{jobId} with it. | Matches ^[0-9A-HJKMNP-TV-Z]{26}$ |
data. | string | Always | Always queued: the job is accepted and has not started. | Always "queued" |
The result
Poll GET /v1/jobs/{jobId}. Once the job has finished, data holds these fields:
| Name | Type | Present | Description | Constraints |
|---|---|---|---|---|
jobId | string | Always | — | — |
status | string | Always | — | One of queued, processing, completed, needs_review, unreadable, failed, expired, cancelled |
documentType | string or null | Always | The kind of document found, once it has been read; null before that. | — |
confidence | number or null | Always | The document's confidence, 0 to 1, to two places; null until it has been read. | Minimum 0. Maximum 1 |
fields | object | Always | What was read. Every key is always present: null means the document does not carry it, or it could not be read with enough confidence. | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | — | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | ISO date, YYYY-MM-DD; a year or month alone is YYYY or YYYY-MM. | — |
fields. | string or null | Always | Decimal rupees as text, for example "12345.50". | — |
fieldsToReview | array of strings | Always | When status is needs_review, the fields a person should confirm; empty otherwise. | — |
failureReason | string | Sometimes | Present only when status is unreadable or failed. | One of UNREADABLE_IMAGE, LOW_CONFIDENCE, DOCUMENT_TYPE_MISMATCH, UNSUPPORTED_MEDIA_TYPE, FILE_TOO_LARGE, INPUT_CORRUPT, PAGE_LIMIT_EXCEEDED, TIMEOUT, PROCESSING_ERROR |
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 |
OCR_UNSUPPORTED_MEDIA_TYPE | 415 | That document format is not accepted. | 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 |
OCR_QUEUE_SATURATED | 429 | The document queue is full. Retry shortly. | 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 |
OCR_UNAVAILABLE | 503 | Document reading is unavailable right now. Retry later. | 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
- Lending: reading proof of address during loan onboarding
- Banking and payments: confirming address during account opening
- Insurance: recording the proposer address
- Rental and co-living: checking a tenant's current address
- Utilities and telecom: reading previous bills for new connections
What this service does
What an address check needs
Customer name, address and PIN code come back as fields, with the provider and consumer number.
Dates for a recency rule
The bill date, due date and billing period are returned in ISO form, so a policy on bill age is a simple check.
Many kinds of bill
The bill type is a field, so electricity, water, gas, phone and broadband bills can share one flow.
A reading, not an account check
OCR reports what the bill says. It does not confirm the connection with the provider.
How a check runs
Arrange access
Tell us where Utility Bill OCR fits in your process. We arrange access for your organization under the applicable service contract, which also sets the file formats and sizes you can send.
Upload the bill with consent
The applicant uploads the bill. Your request names the file and records the consent you took for this purpose.
Let the reading run
The request is accepted with a job reference and read in the background.
Collect the fields
Collect the provider, name, address, PIN code, dates and amount by the job reference, with any fields to review.
Match and decide
Match the name and address with the application, check the bill date, and send mismatches to a reviewer.
Questions
- What is a Utility Bill OCR API?
- An interface that reads a utility bill image or PDF and returns the provider, consumer number, customer name, address, PIN code, bill dates and amount due as structured fields.
- Can I use it for proof of address?
- It reads the name and address printed on the bill, which is what a proof of address check compares. Which bills you accept as proof is your own policy.
- Which bills can it read?
- Electricity, water, gas, telephone and broadband bills. The bill type is returned so your flow can treat them differently if it needs to.
- Does it confirm the account with the provider?
- No. It reads what the bill says. It does not contact the provider.
- Do I need consent to read a utility bill?
- Yes. A bill carries a person's name and address. Take consent for the stated purpose and send it with the request.
- How do I reject an old bill?
- The bill date is returned in ISO form. Compare it with the age your policy accepts and ask for a newer bill when it is too old.
Catalog entry last updated .