Get E-Way Bill Details by IRN

Authentication

Pass your key in the X-API-Key header. Use a test_ key against the sandbox and a live_ key in production. Send an optional Idempotency-Key header to safely retry — the same key returns the same response for 24h.

Request

Endpoint: POST https://apisathi.in/gw/v1/einvoice-get-ewb-by-irn-v1/

The trailing slash is required. /v1/einvoice-get-ewb-by-irn-v1/ works; /v1/einvoice-get-ewb-by-irn-v1 returns 404 Not Found. This applies to every product.

Code snippets

curl -X POST https://apisathi.in/gw/v1/einvoice-get-ewb-by-irn-v1/ \
  -H "X-API-Key: $API_SATHI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"gstin":"29AAACR5055K1Z5","username":"your_portal_username","password":"your_portal_password","query_string":"irn=a5c12d...64charirn"}'

Response

Sample response

{
  "success": true,
  "data": {
    "note": "The portal response, relayed unchanged."
  }
}

Reading a 400

A schema rejection returns INVALID_REQUEST with a details array naming the exact field. Read it before guessing — it gives you the JSON path and what was wrong with it.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request body failed schema validation",
    "details": [
      { "path": "/callback_url",
        "message": "unexpected property 'callback_url' — this endpoint does not accept unknown fields" }
    ]
  }
}

Most endpoints reject unknown top-level fields outright, so an extra key you added for your own bookkeeping will fail the call. Enum errors list the accepted values, and a missing required field is named with its full path.

Error codes

OpenAPI 3.1

Generated from this product's request/response JSON Schemas.

{
  "openapi": "3.1.0",
  "info": {
    "title": "API Sathi — Get E-Way Bill Details by IRN",
    "version": "1.0.0",
    "description": "Fetch the e-way bill details attached to a registered IRN.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample."
  },
  "servers": [
    {
      "url": "https://apisathi.in/gw/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your live or test key, e.g. `live_xxxxxxxxxxxx`."
      }
    }
  },
  "paths": {
    "/einvoice-get-ewb-by-irn-v1": {
      "post": {
        "operationId": "einvoiceGetEwbByIrnV1",
        "tags": [
          "gst"
        ],
        "summary": "Get E-Way Bill Details by IRN",
        "description": "Fetch the e-way bill details attached to a registered IRN.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional. Same key returns the same response for 24h."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "gstin",
                  "username",
                  "password"
                ],
                "properties": {
                  "gstin": {
                    "type": "string",
                    "description": "GSTIN this request is filed for."
                  },
                  "username": {
                    "type": "string",
                    "description": "The taxpayer’s GST portal API username. Write-only."
                  },
                  "password": {
                    "type": "string",
                    "description": "The taxpayer’s GST portal API password. Write-only."
                  },
                  "query_string": {
                    "type": "string",
                    "default": "",
                    "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged."
                  }
                }
              },
              "example": {
                "gstin": "29AAACR5055K1Z5",
                "username": "your_portal_username",
                "password": "your_portal_password",
                "query_string": "irn=a5c12d...64charirn"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful, normalized response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "True only when the portal accepted the request."
                    },
                    "message": {
                      "type": "string",
                      "description": "The portal’s reason when it rejected one."
                    },
                    "data": {
                      "type": "object",
                      "description": "The portal response, passed through in full."
                    }
                  }
                },
                "example": {
                  "success": true,
                  "data": {
                    "note": "The portal response, relayed unchanged."
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or revoked X-API-Key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Wallet balance is below the per-call sale price. Recharge and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "API key is not scoped for this product.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Upstream vendor rejected our credentials (our config issue). Not charged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "call_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}