e-Way Bill API
New
Look up the e-Way Bill details available for a bill number. Your dispatch, gate and settlement teams can then confirm a consignment's paperwork before the goods move.
Overview
An e-Way Bill is the movement document raised for a consignment of goods before it travels. It ties a supply document to the parties, the goods and the route. Once the transport leg is recorded, it also names the vehicle the consignment actually moves under. If you dispatch, receive, finance or insure freight, you often need to confirm the bill quoted for a consignment. It has to exist and match the movement in front of you. Doing that by hand for every trip stops working past a small operation. This API returns the e-Way Bill information available for a bill number in a structured response. The check can then sit inside a transport management system, a warehouse gate process or a finance review. The fields you get back vary by data source and by the individual bill record.
- Category
- Tax & Compliance Services
- Coverage
- e-Way Bills raised for goods movement across India
- Input
- e-Way Bill number
- Output
- The bill details available: supply document reference, parties, goods description, validity and transport information
- Typical users
- Fleet and logistics operators, warehousing teams, marketplaces, lenders, insurers, ERP and finance teams
- Coverage note
- Bills raised for goods movement in India. Available fields vary by data source, by record and by how far the movement has progressed.
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 ^[0-9]{12}$ |
options | object | Optional | Settings for this call. | — |
options. | string | Optional | Your own reference for this call. It comes back unchanged as meta.reference. | 1 to 128 characters |
options. | object | Optional | 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/logistics/eway-bill \
-H "X-Api-Key: $FINSOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"input": {
"ewayBillNumber": "<ewayBillNumber>"
}
}'Node.js
const response = await fetch("https://gateway.staging.finsour.io/v1/logistics/eway-bill", {
method: "POST",
headers: {
"X-Api-Key": process.env.FINSOUR_API_KEY,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"input": {
"ewayBillNumber": "<ewayBillNumber>"
}
}),
});
console.log(response.status, await response.json());Python
import os
import uuid
import requests
response = requests.post(
"https://gateway.staging.finsour.io/v1/logistics/eway-bill",
headers={
"X-Api-Key": os.environ["FINSOUR_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"input": {
"ewayBillNumber": "<ewayBillNumber>",
},
},
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 | — | Matches ^[0-9]{12}$ |
data. | string or null | Always | The bill's status code, upper-case, as the e-way bill system states it (ACT is an active bill). | — |
data. | string or any or null | Always | When the bill was generated. | — |
data. | string or any or null | Always | When the bill's validity ends; null when the record gives no full date. | — |
data. | string or any or null | Always | The PIN code the consignment is sent from. | — |
data. | string or any or null | Always | The PIN code the consignment is sent to. | — |
data. | string or any or null | Always | The main HSN code of the consignment. | — |
data. | array of objects | Always | The vehicles recorded against the bill; empty when there are none. | — |
data. | string or any or null | Always | The vehicle's registration number, upper-case with separators removed. | — |
data. | string or any or null | Always | When the vehicle was recorded against the bill. | — |
data. | string or null | Always | The transport mode code, as the e-way bill records 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 |
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
- Logistics and fleet - trip validation before a vehicle leaves the dock
- Warehousing - gate-in check against the bill quoted on arrival
- Marketplaces - dispatch check on seller-shipped consignments
- Lending and NBFC - movement corroboration on invoice discounting files
- Insurance - goods-in-transit claim review against the movement record
- Healthcare distribution - inbound consignment check at the depot
What this service does
Fields an e-Way Bill lookup can return
You can get the supply document reference, consignor and consignee details, the goods description, the validity recorded for the movement and the transport details attached to the bill. Each one appears where it is available. The exact fields returned vary by data source and by the individual bill record.
A check at the point the goods move
Connect the lookup to trip creation, a warehouse gate application, an ERP dispatch process or a freight settlement queue. Consignment paperwork is then confirmed where the goods and the decision actually are.
Check the same bill more than once
You can check a bill when a trip is created, again when a vehicle reaches a gate, and again when the freight invoice arrives. One lookup supports all three controls.
Evidence for a claim or a receivable
Retrieved bill information can support a goods receipt, a freight settlement, an insurance claim review or a supply-chain finance file. It sits alongside the other checks those decisions rely on.
How a check runs
Agree where the bill check runs
Tell us where the check belongs in your movement or settlement process. Start with Get API, and we settle the service contract from there.
Wire the lookup into your dispatch systems
Add the retrieval to your transport management system, gate application, ERP or finance queue. We hand over the technical documentation at onboarding.
Send the e-Way Bill number
Your application sends the bill number quoted for the consignment, taken from the trip record, the booking or the paperwork you received.
Read the bill details returned
The information available for that bill comes back in a structured response. The data source and the individual record decide which fields you see.
Act on the movement record
Use the response for the dispatch, gate, settlement, claim or financing decision you collected it for, and attach it to the record it belongs to.
Questions
- What do I send to look up an e-Way Bill?
- The e-Way Bill number quoted for the consignment. You do not need a document image for this check.
- What details come back for an e-Way Bill?
- You get what is available for that bill. That covers the supply document reference, the parties, a description of the goods, the validity recorded for the movement and the transport details attached to it. Each appears where it is recorded, and the fields returned vary by data source and by the individual bill record.
- Can I check an e-Way Bill before a vehicle is assigned?
- Yes. A bill can exist before its transport leg is recorded, and the response shows the state of the record at the moment you retrieve it. Where the transport details matter to your decision, check again once that leg has been added.
- Do I need consent to retrieve an e-Way Bill?
- The record describes a commercial movement between businesses. Even so, retrieve it only for a consignment your organization has a legitimate operational or financial interest in, and handle it under your existing counterparty data rules.
- How do I get access to the e-Way Bill API?
- Use Get API and tell us about your movement volumes and where the check belongs in your process. We agree access and the integration documentation as part of the service contract.
- Why do e-Way Bill results differ from one bill to another?
- Bills differ in what has been recorded against them and in how far the movement has progressed, and data sources differ in what they can return. Transport details, for example, may be present for one bill and not yet recorded for another.
Catalog entry last updated .