Skip to content

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.

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

POSThttps://gateway.staging.finsour.io/v1/logistics/eway-bill

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.ewayBillNumberstringRequired—Matches ^[0-9]{12}$
optionsobjectOptionalSettings for this call.—
options.referencestringOptionalYour own reference for this call. It comes back unchanged as meta.reference.1 to 128 characters
options.consentobjectOptionalThe 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/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

Status 200 · content type application/json

NameTypePresentDescriptionConstraints
dataobjectAlwaysThe result of the check.—
data.foundbooleanAlways——
data.ewayBillNumberstringAlways—Matches ^[0-9]{12}$
data.statusstring or nullAlwaysThe bill's status code, upper-case, as the e-way bill system states it (ACT is an active bill).—
data.generatedAtstring or any or nullAlwaysWhen the bill was generated.—
data.validUntilstring or any or nullAlwaysWhen the bill's validity ends; null when the record gives no full date.—
data.fromPincodestring or any or nullAlwaysThe PIN code the consignment is sent from.—
data.toPincodestring or any or nullAlwaysThe PIN code the consignment is sent to.—
data.hsnCodestring or any or nullAlwaysThe main HSN code of the consignment.—
data.vehiclesarray of objectsAlwaysThe vehicles recorded against the bill; empty when there are none.—
data.vehicles[].registrationNumberstring or any or nullAlwaysThe vehicle's registration number, upper-case with separators removed.—
data.vehicles[].enteredAtstring or any or nullAlwaysWhen the vehicle was recorded against the bill.—
data.vehicles[].transportModestring or nullAlwaysThe transport mode code, as the e-way bill records 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
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

  • 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

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

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

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

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

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