### Request Example (cURL) Source: https://developer.sandbox.co.in/guides/developer-resources/requests_and_responses Here's a complete example showing how to make an API request with all required headers. ```APIDOC ## Request example Here's a complete example showing how to make an API request with all required headers: ```bash cURL theme={null} curl -X POST 'https://api.sandbox.co.in/gst/compliance/public/gstin/search' \ -H 'x-api-key: key_live_SIethxxxxxxxx' \ -H 'authorization: eyJhbGcxxxxx.eyJhdJxxxx.Si29xxxxx' \ -H 'x-api-version: 1.0' \ -H 'Content-Type: application/json' \ -d '{ "gstin": "05ABNTY3290P8ZB" }' ``` ``` -------------------------------- ### GET Preference Response Example Source: https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/public/get_preference Example of a successful response for the GET preference endpoint, showing monthly filing preferences for all quarters. ```json { "code": 200, "timestamp": 1775825033134, "data": { "data": { "response": [ { "preference": "M", "quarter": "Q1" }, { "preference": "M", "quarter": "Q2" }, { "preference": "M", "quarter": "Q3" }, { "preference": "M", "quarter": "Q4" } ] }, "status_cd": "1" }, "transaction_id": "903962ca-bc29-45c5-b879-3e51c7f9887d" } ``` -------------------------------- ### GET Request Example (Not Recommended) Source: https://developer.sandbox.co.in/guides/developer-resources/post_for_get Illustrates a typical GET request with sensitive data in the URL, which is discouraged by Sandbox. ```http GET /api/kyc/pan/verify?pan=ABCDE1234F ``` -------------------------------- ### Initiate Session Request Example Source: https://developer.sandbox.co.in/api-reference/kyc/entitylocker/endpoints/initiate_session This example demonstrates how to initiate an EntityLocker session for an existing user. Ensure the `redirect_url` is an HTTPS URL. ```json { "@entity": "in.co.sandbox.kyc.entitylocker.session.request", "flow": "signin", "redirect_url": "https://sandbox.co.in/", "consent_expiry": 1765887697411 } ``` -------------------------------- ### Job Status Response Example (In Progress) Source: https://developer.sandbox.co.in/guides/developer-resources/job_based_apis Example JSON response indicating the job is currently being processed. ```json { "code": 200, "timestamp": 1767788517749, "data": { "created_at": 1767788396261, "updated_at": 1767788396261, "@entity": "in.co.sandbox.it.calculator.tax_pnl.securities.job", "security_type": "domestic", "status": "in_progress", "job_id": "11734cbd-8f18-45ea-9eab-0717a8b3c513" }, "transaction_id": "1f077f3e-524f-4f96-942a-a0daf7af4f5e" } ``` -------------------------------- ### GET Preference Request Example Source: https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/public/get_preference Example of a request to get the return filing preference for a given GSTIN. ```json { "gstin": "27ABCDE1234F1Z5" } ``` -------------------------------- ### 200 - Session Created Example Source: https://developer.sandbox.co.in/api-reference/kyc/entitylocker/endpoints/session_status This example shows the response when an Entity Locker session is successfully created but not yet completed. ```json { "code": 200, "timestamp": 1752580258171, "data": { "@entity": "in.co.sandbox.kyc.entitylocker.session", "id": "139fd8a0-d645-42e1-a904-bb43353b0139", "status": "created", "created_at": 1752579445983 }, "transaction_id": "900ff751-2191-4b7d-b20a-8301790a3e29" } ``` -------------------------------- ### Job Status Response Example (Succeeded) Source: https://developer.sandbox.co.in/guides/developer-resources/job_based_apis Example JSON response indicating the job has successfully completed, including the URL to download the output. ```json { "code": 200, "timestamp": 1767788721062, "data": { "id": "02f12d0c-e7e0-4021-943c-efcc827e6ea9", "created_at": 1767788696635, "updated_at": 1767788696635, "@entity": "in.co.sandbox.it.calculator.pnl.crypto.job", "url": "https://in-co-sandbox-it-calculator-pnl-crypto-dev.s3.ap-south-1.amazonaws.com/", "status": "succeeded" }, "transaction_id": "65b8a350-646b-467d-a980-01a38233d2f1" } ``` -------------------------------- ### Make your first API call Source: https://developer.sandbox.co.in/guides/get-started/quickstart Use your access token to call any Sandbox API. Ensure the authorization header contains only the access token value, without the 'Bearer' prefix. ```bash curl -X POST 'https://api.sandbox.co.in/gst/compliance/public/gstin/search' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'authorization: eyJ0eXAiOiJKV1QiLCJhbGc...' \ -H 'x-api-version: 1.0' \ -H 'Content-Type: application/json' \ -d '{ "gstin": "05ABNTY3290P8ZB" }' ``` -------------------------------- ### Successful Response for Get Filing Preference Source: https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/common/get_filing_preference This is an example of a successful JSON response when retrieving the filing preference. It includes the taxpayer's preference ('M' for Monthly) and the corresponding quarter. ```JSON { "code": 200, "data": { "data": { "response": [ { "preference": "M", "quarter": "Q1" }, { "preference": "M", "quarter": "Q2" }, { "preference": "M", "quarter": "Q3" }, { "preference": "M", "quarter": "Q4" } ] }, "status_cd": "1" }, "timestamp": "1685540172000", "transaction_id": "3733caed-31b1-45db-8cfa-0144afd983eb" } ``` -------------------------------- ### Submit Job - Form 26Q Example Source: https://developer.sandbox.co.in/api-reference/tds/compliance/certificate-form16%28a%29/endpoints/submit_job This example demonstrates submitting a job for Form 26Q. It includes the necessary TRACES credentials and security captcha details, with the 'remember_me' option enabled to save credentials for future use. ```json { "@entity": "in.co.sandbox.tds.compliance.traces.credentials", "username": "T.STARK", "password": "TEST1234", "tan": "AHMA09719B", "security_captcha": { "@entity": "in.co.sandbox.tds.compliance.traces.credentials.security_captcha", "quarter": "Q4", "financial_year": "FY 2023-24", "form": "26Q", "bsr_code": "0510002", "challan_date": 1701109800000, "challan_serial_no": "01905", "provisional_receipt_number": "770000211345676", "challan_amount": 21, "unique_pan_amount_combination_for_challan": [ [ "sr_no", "pan", "total_amount_deposited_against_pan" ], [ 1, "XXXPX1234A", 1 ] ] }, "remember_me": true } ``` -------------------------------- ### Initialize EntityLocker SDK Source: https://developer.sandbox.co.in/api-reference/kyc/entitylocker-sdk/getting-started/platforms/web Configure and launch the EntityLocker SDK when the user initiates document retrieval. Ensure you replace 'YOUR_API_KEY' and the session ID with your actual values. ```javascript function launch() { // Set your API key EntitylockerSDK.setAPIKey("YOUR_API_KEY"); // Configure the SDK options const options = { session_id: "a7fac865-61a9-4589-b80c....", // Replace with your session ID from Step 1 brand: { name: "MoneyApp", // Your business or app name logo_url: "https://example.com/your_logo", // Publicly accessible URL of your logo }, theme: { mode: "light", // Options: "light" or "dark" seed: "#3D6838", // Primary color for theme customization }, }; // Launch the EntityLocker SDK EntitylockerSDK.open(options); } ``` -------------------------------- ### Example GSTIN for Tracking Returns Source: https://developer.sandbox.co.in/reference/track-gst-returns-api This is an example of a GSTIN that can be used when tracking GST returns. ```json { "gstin": "33ABCCD7894A1Z5" } ``` -------------------------------- ### Initialize DigiLocker SDK Source: https://developer.sandbox.co.in/api-reference/kyc/digilocker-sdk/getting-started/platforms/web Configure and launch the DigiLocker SDK when the user initiates document retrieval. Ensure to replace placeholder values for API key, session ID, and brand details. ```javascript function launch() { // Set your API key DigilockerSDK.setAPIKey("YOUR_API_KEY"); // Configure the SDK options const options = { session_id: "a7fac865-61a9-4589-b80c....", // Replace with your session ID from Step 1 brand: { name: "MoneyApp", // Your business or app name logo_url: "https://example.com/your_logo", // Publicly accessible URL of your logo }, theme: { mode: "light", // Options: "light" or "dark" seed: "#3D6838", // Primary color for theme customization }, }; // Launch the Digilocker SDK DigilockerSDK.open(options); } ``` -------------------------------- ### 422 Unprocessable Entity Examples Source: https://developer.sandbox.co.in/api-reference/tds/analytics/tds-analytics/endpoints/submit_job Examples of 422 Unprocessable Entity responses for various invalid input scenarios. ```json { "code": 422, "timestamp": 1763633700000, "transaction_id": "e9bf56c1-086e-41d4-9b1c-feebe35207e0", "message": "Invalid TAN: DABC2345DD" } ``` ```json { "code": 422, "timestamp": 1763633700000, "transaction_id": "90c354b0-0cad-403b-b840-892384d0e14d", "message": "Invalid quarter: Q5" } ``` ```json { "code": 422, "timestamp": 1763633700000, "transaction_id": "35a11c62-3dc7-48db-a930-2788c7a098ef", "message": "Invalid form type: 25Q" } ``` ```json { "code": 422, "timestamp": 1763633700000, "transaction_id": "f07c5a4b-1c16-429f-8941-9981eed6fd3e", "message": "Invalid financial year: 2022" } ``` ```json { "code": 422, "timestamp": 1763633700000, "transaction_id": "1062275f-0c31-4b20-adbe-3d2f896c77f6", "message": "Invalid entity: wrong.entity" } ``` -------------------------------- ### Generate OTP Request Example Source: https://developer.sandbox.co.in/api-reference/tds/compliance/download-csi/endpoints/generate_otp Use this example to generate an OTP for downloading CSI files. Ensure you provide a valid TAN, mobile number, date range, consent, and a reason for the request. ```yaml openapi: 3.1.0 info: title: compliance version: 1.0.0 description: >- Tax Deducted at Source (TDS) is an indirect method of collecting Income Tax. TDS is based on the principle of “Pay as you earn” which is beneficial for both the Government and the taxpayer. It is where a person making a payment of specified nature is liable to deduct tax at a prescribed rate. This ensures continuous revenue for the Government by way of Tax Deducted at the Source. The Payer making a payment is also responsible to deposit TDS with the Income Tax Department within a specified date and file a TDS Return. Once filed, the deposited amount will be shown in the Payee's Form 26AS which they can then use to claim tax credits when filing ITR. However, staying TDS compliant can be a hassle for businesses, as they are required to : 1. Deduct TDS from payments that are liable for TDS Deduction at an appropriate rate. 2. Deposit TDS to Government before the due date. 3. File TDS Returns on a Quarterly basis. 4. Issue a TDS Certificate by the deductor to the deductee. Organizations deducting TDS have to remain compliant with each of the steps. Failure to do so results in TDS Penalties by Authorities. Sandbox provides TDS Compliance APIs to help you automate end-to-end TDS compliance. servers: - url: https://test-api.sandbox.co.in - url: https://api.sandbox.co.in security: [] paths: /tds/compliance/csi/otp: post: tags: - Download CSI summary: Generate OTP parameters: - name: authorization in: header required: true description: JWT access token deprecated: false schema: type: string - name: x-api-key in: header required: true description: API key for identification deprecated: false schema: type: string - name: x-api-version in: header required: false deprecated: false schema: type: string requestBody: content: application/json: schema: type: object properties: '@entity': type: string enum: - in.co.sandbox.tds.compliance.deductors.otp.request tan: description: >- TAN of deductor/collector. Regular Expression: [A-Z]{4}[0-9]{5}[A-Z]{1} pattern: '[A-Z]{4}[0-9]{5}[A-Z]{1}' type: string mobile_number: description: 'Mobile Number to send the OTP. Pattern: [1-9]{1}[0-9]{9}' pattern: '[1-9]{1}[0-9]{9}' type: string from: description: >- Date from which challan details are to be fetched. Value in EPOCH timestamp type: integer to: description: >- Date till which challan details are to be fetched. Value in EPOCH timestamp type: integer consent: description: >- Consent of the end-user to get their information. Possible values: Y or y type: string reason: description: 'Indicate the purpose. Min length: 20 characters' type: string required: - '@entity' - tan - mobile_number - from - to - consent - reason examples: 200 - Success: value: '@entity': in.co.sandbox.tds.compliance.deductors.otp.request tan: AHMA09719B mobile_number: '1234567890' from: 1722450600000 to: 1730313000000 consent: 'Y' reason: TDS Return 200 Invalid TAN: value: '@entity': in.co.sandbox.tds.compliance.deductors.otp.request tan: AABC23456D mobile_number: '1234567890' from: 1722450600000 to: 1730313000000 consent: 'Y' reason: TDS Return 200 OTP already generated: value: ``` -------------------------------- ### 200 - Session Succeeded Example Source: https://developer.sandbox.co.in/api-reference/kyc/entitylocker/endpoints/session_status This example illustrates the response when an Entity Locker session has successfully completed and documents have been consented. ```json { "code": 200, "timestamp": 1765781194203, "data": { "id": "eed074e1-3bf0-4733-bc5a-4718fced542e", "created_at": 1765781019627, "updated_at": 1765781050695, "@entity": "in.co.sandbox.kyc.entitylocker.session", "status": "succeeded", "documents_consented": [ "company_master_details", "gstn_details", "udhyam_certificate" ] }, "transaction_id": "ee4a3ef4-b0a0-4649-972f-4676d8858e08" } ``` -------------------------------- ### Verify OTP Request Examples Source: https://developer.sandbox.co.in/api-reference/tds/compliance/download-csi/endpoints/verify_otp Provides examples of valid request payloads for the OTP verification endpoint. Use these to test different scenarios. ```json { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS005981930273", "otp": "834201" } ``` ```json { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS101212121212121", "otp": "121212" } ``` ```json { "@entity": "in.co.sandbox.tds.compliance.deductors.csi.request", "reference_id": "FOS101212121212121", "otp": "121212" } ``` -------------------------------- ### Example cURL Request with Headers Source: https://developer.sandbox.co.in/guides/developer-resources/requests_and_responses This cURL command demonstrates how to make a POST request to the Sandbox API, including all necessary headers for authentication and content type, along with a JSON payload. ```bash curl -X POST 'https://api.sandbox.co.in/gst/compliance/public/gstin/search' \ -H 'x-api-key: key_live_SIethxxxxxxxx' \ -H 'authorization: eyJhbGcxxxxx.eyJhdJxxxx.Si29xxxxx' \ -H 'x-api-version: 1.0' \ -H 'Content-Type: application/json' \ -d '{ "gstin": "05ABNTY3290P8ZB" }' ``` -------------------------------- ### OpenAPI Example: Create Session 200 OK Response Source: https://developer.sandbox.co.in/api-reference/kyc/entitylocker-sdk/endpoints/create_session This OpenAPI example demonstrates a successful response (200 OK) when creating a session via the EntityLocker SDK. It includes transaction details, entity information, and status. ```yaml openapi: 3.0.0 info: title: EntityLocker SDK API version: 1.0.0 paths: /sessions: post: summary: Create a new session responses: '200': description: Session created successfully content: application/json: schema: type: object properties: timestamp: type: integer format: int64 transaction_id: type: string format: uuid data: type: object properties: '@entity': type: string id: type: string format: uuid status: type: string created_at: type: integer format: int64 code: type: integer examples: 200 - OK: summary: 200 - OK value: timestamp: 1750331120324 transaction_id: 5ccad959-0bf4-4472-a3dd-d57e2b61b5a9 data: '@entity': in.co.sandbox.kyc.entitylocker.sdk.session id: 0454f149-26d0-41ef-9f14-c54f4b5f7b70 status: created created_at: 1750331120324 code: 200 headers: {} deprecated: false security: [] ``` -------------------------------- ### User Profile API Response Example Source: https://developer.sandbox.co.in/recipes/kyc/entitylocker/entitylocker_api_recipe This is an example of a successful response when fetching a user's profile. It includes personal details and e-Aadhaar status. ```json { "code": 200, "timestamp": 1765889000461, "data": { "id": "96b14651-a333-547d-8de9-fee0be4f941e", "@entity": "in.co.sandbox.kyc.entitylocker.user.profile", "name": "Henil Rupesh Shah", "date_of_birth": "28/01/2002", "mobile": "9512120133", "gender": "male", "eaadhaar": true }, "transaction_id": "7603165e-e591-4342-bb19-1d9f4caabb0f" } ``` -------------------------------- ### Company Master Data Request Examples Source: https://developer.sandbox.co.in/api-reference/kyc/mca/company_master_data Demonstrates various request payloads for fetching company master data using CIN or LLPIN. Ensure to include 'id', 'consent', and 'reason' in your request. ```json { "@entity": "in.co.sandbox.kyc.mca.master_data.request", "id": "ABC-1234", "consent": "y", "reason": "For Company KYC" } ``` ```json { "@entity": "in.co.sandbox.kyc.mca.master_data.request", "id": "ABC-4567", "consent": "y", "reason": "For Company KYC" } ``` ```json { "@entity": "in.co.sandbox.kyc.mca.master_data.request", "id": "XXX-4567", "consent": "y", "reason": "For Company KYC" } ``` ```json { "@entity": "in.co.sandbox.kyc.mca.master_data.request", "id": "U12345AB1234ABC123456", "consent": "y", "reason": "For Company KYC" } ```