PeriOne GST API platform logo

Developer integration guide

Integrate GST, invoicing and verification APIs into your application

Choose the right API, follow its authentication flow, and reconcile responses before updating business records. Use this guide alongside the current API reference for exact request and response schemas.

Updated 24 September 2026

1. Confirm account access and environment

Production uses https://api.perione.in. Where sandbox access is supported, the base URL is https://staging.perione.in. Confirm availability for your suite; e-KYC and VAHAN currently provide production access. Do not apply one service's token or header format to every API.

Store credentials on your server, separate sandbox and production settings, and avoid logging passwords, tokens or complete sensitive payloads. Start with the authentication reference.

GST return filing and reconciliation

Choose the return period and the return or reconciliation workflow before selecting endpoints. GST return APIs and public GSTIN lookups have different access needs.

  1. Start with the authentication and taxpayer-consent steps required by your account reference.
  2. Select the relevant GSTR-1, GSTR-1A, GSTR-3B or other return group; use GSTR-2A, GSTR-2B and IMS for the documented purchase and invoice workflows.
  3. Separate reading data, preparing a return and filing it in your application. Require an explicit user action for filing.
  4. Save response identifiers and reconcile status before treating a filing as complete.

The service reference also covers GSTR-2X, GSTR-4A, GSTR-4 Annual, GSTR-9, GSTR-9C, notices and ledgers.

View gst return filing and reconciliation APIs

e-Invoice and IRN lifecycle

Map invoice data to the documented request schema before generating an IRN. Keep credentials and authentication requests in your server application.

  1. Authenticate with GET /einvoice/authenticate using the documented headers and email parameter.
  2. Use GSTIN lookup or synchronization when needed; validate the invoice fields and master codes against the reference.
  3. Generate the IRN using POST /einvoice/type/GENERATE/version/V1_03. Store the returned identifiers with the original invoice.
  4. If a request times out, use the documented retrieval flow to reconcile the result before deciding whether to retry. Use the cancellation and IRN-linked e-Way Bill APIs only when applicable.

Follow the current reference for retrieval windows, cancellation eligibility and response fields. Do not infer success from an HTTP status alone.

View e-invoice and irn lifecycle APIs

e-Way Bill generation and transport updates

Keep invoice, dispatch and vehicle details connected to one shipment record so operations staff can reconcile each update.

  1. Complete e-Way Bill authentication and check supply, document, transport and vehicle codes.
  2. Generate with POST /ewaybillapi/v1.03/ewayapi/genewaybill and store the returned e-Way Bill reference.
  3. Use the documented Part-B, transporter, validity or multi-vehicle operations as the shipment changes.
  4. Retrieve the bill and related reports to confirm state. Use cancellation, rejection or closure only for the applicable workflow.

Consolidated bills have separate generation, regeneration and retrieval operations. Do not treat them as another name for an individual e-Way Bill.

View e-way bill generation and transport updates APIs

PAN, GST, MCA and Udyam verification

Select the lookup that matches the identifier provided by the user. The current e-KYC console exposes production access.

  1. Use PAN search, GST search or PAN-to-GSTIN for the corresponding identity/business lookup.
  2. Use CIN verification and director-by-CIN for company workflows; use DIN verification for a director identifier.
  3. Use Udyam verification for the documented MSME registration workflow.
  4. Read the response schema and failure result for the selected endpoint. Keep only the data your application needs and restrict access to verification results.

A successful lookup is one input to your onboarding process; define your own review and exception workflow around the documented result.

View pan, gst, mca and udyam verification APIs

Vehicle, driving licence and toll verification

The VAHAN/SARATHI suite exposes separate operations for vehicle, licence, e-Challan, GST and toll workflows. Its current console provides production access.

  1. Choose vehicle-number, chassis-number or engine-number lookup according to the identifier you hold.
  2. Use the driving-licence or e-Challan operation for the corresponding check; do not assume those details are part of every vehicle response.
  3. Choose FASTag lookup by vehicle number or tag ID, or search toll-plaza details using the documented operation.
  4. Validate required fields against the account reference and show an explicit no-result or review state when a lookup does not return usable data.

The service page lists all nine operations. Confirm account access and commercial terms before running production lookups.

View vehicle, driving licence and toll verification APIs

Handle failures without duplicating business actions

  • Authentication failure: check the selected environment, required credentials and token lifetime in that service's reference.
  • Validation failure: read the returned code and field message; compare required fields and master values before resending.
  • Timeout or uncertain outcome: reconcile using the documented status/retrieval operation before retrying a generation, update or filing request.
  • Rate limiting or service unavailability: respect documented retry guidance and avoid repeated uncontrolled requests.
Error-code referencesMaster-code references

Before production rollout

Verify successful and failed requests for your enabled endpoints, test reconciliation after a timeout, confirm operator permissions and credential rotation, and agree on support and commercial terms. Record which reference version your implementation uses. The workflows above describe the documented integration; they do not replace account-specific acceptance testing.

Discuss your integration with PeriOne