Commercial Credit Report - Fetch Report PDF

Endpoint Overview

POST /api/v1/credit-report-commercial/fetch-report-pdf

Description

The Commercial Credit Report - Fetch Report PDF API enables businesses to programmatically retrieve comprehensive credit reports for commercial entities in PDF or HTML format. By providing a company's PAN and business name along with user consent, this endpoint fetches a fully rendered credit report from bureau data and returns it as a hosted, time-limited secure link.

This API is essential for any platform performing due diligence, vendor assessments, or commercial lending decisions — eliminating the need for manual bureau interactions while delivering structured credit scores and detailed report documents in a single API call.

Key Benefits

Instant Access: Retrieve fully rendered commercial credit reports in seconds without navigating bureau portals manually.

Dual Delivery: Receive both a structured credit score object and a hosted report link in a single response.

Flexible Output: Supports html report type as well as mock mode for sandbox testing without consuming live bureau credits.

Secure & Auditable: Each report is tied to a unique client_id for traceability, and the report link is time-scoped using AWS Signature V4 for secure access.

Use Cases

BFSI & Lending

Procurement & Vendor Management

FinTech & SaaS Platforms

Automate creditworthiness evaluation for SME loan applications by fetching bureau reports during onboarding.

Enable real-time commercial underwriting decisions by integrating bureau scores directly into loan origination systems.

Generate audit-ready credit report archives for regulatory compliance in NBFC and banking workflows.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

⚠️ Never use your production JWT token in sandbox environments, and vice versa. Tokens are environment-scoped and non-interchangeable.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token in the format `Bearer <JWT_TOKEN>`. Use the token corresponding to your target environment (sandbox or production).
`Content-Type`	Yes	Must be set to `application/json`.

Request Body

Parameter	Type	Required	Description
`business_name`	String	Yes	The registered legal name of the business entity whose credit report is being requested. Example: `"ABC PRIVATE LIMITED"`.
`pan`	String	Yes	The Permanent Account Number (PAN) of the business entity. Must follow the standard PAN format. Example: `"ABCCP1234L"`.
`report_type`	String	Yes	Specifies the type of report to fetch. Accepted values: `"html"` (live bureau report rendered as HTML) or `"mock"` (simulated report for production env mock response for testing).
`raw`	String	No	Optional parameter. When set to `"true"`, the response includes both the JSON data and the HTML report content together. Omit this field to receive only the default report link.
`consent`	String	Yes	Explicit user/business consent for fetching the credit report. Must be set to `"Y"` to indicate consent has been obtained.

Example Request

{
    "business_name": "ABC PRIVATE LIMITED",
    "pan": "ABCCP1234L",
    "report_type": "html",
    "consent": "Y"
}

💡 To also receive the raw HTML report body in the response alongside the JSON, include "raw": "true" in the request body.

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	Top-level container for all report data returned by the API.
`data.client_id`	String	A unique identifier assigned to this specific report fetch request. Format: `credit_report_commercial_pdf_<unique_id>`. Useful for logging, support, and audit trails.
`data.pan`	String	The PAN of the business entity for which the report was fetched, as provided in the request.
`data.business_name`	String	The business name as provided in the request.
`data.credit_score`	Array	An array of credit score objects returned by the bureau. Each object represents a score model applied to the entity or its associated individuals.
`data.credit_score[].score_name`	String	The name of the credit scoring model used. Example: `"ERS 4.0 (retail)"`.
`data.credit_score[].score_entity`	String	The name of the entity or individual to whom this score applies.
`data.credit_score[].relationship`	String	Describes the relationship of the scored entity to the business. Example: `"Individual Relation Others"`.
`data.credit_score[].credit_score`	String	The numeric credit score value assigned by the bureau under the specified scoring model.
`data.credit_report`	Object	Contains the raw structured credit report data as returned by the bureau. This field may be empty (`{}`) when `raw` is not set to `"true"`.
`data.credit_report_link`	String	A time-limited pre-signed AWS S3 URL pointing to the rendered credit report file (HTML format). The URL expires after a short period (typically 600 seconds).
`status_code`	Integer	HTTP-equivalent status code for the API operation. `200` indicates a successful response.
`success`	Boolean	`true` if the request was processed successfully; `false` on failure.
`message`	String	Human-readable description of the response outcome. Example: `"Success"`.
`message_code`	String	Machine-readable code corresponding to the outcome. Example: `"success"`.

Example Successful Response

{
    "data": {
        "client_id": "credit_report_commercial_pdf_cvyjdevFbVdFoclGqaaY",
        "pan": "ABCCP1234L",
        "business_name": "ABC PRIVATE LIMITED",
        "credit_score": [
            {
                "score_name": "ERS 4.0 (retail)",
                "score_entity": "DUMMY COMPANY NAME",
                "relationship": "Individual Relation Others",
                "credit_score": "852"
            }
        ],
        "credit_report": {},
        "credit_report_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/ritik123/credit_report_commercial/credit_report_commercial_pdf_cvyjdevFbVdFoclGqaaY/commercial_report_1777120420221221.html?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20260425%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20260425T123341Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=7611497397439d1d3e6354ee6b68df05c8be7ec31bc4ff4270e9089b55230265"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Unauthorized (401)

Invalid Input (400)

Consent Not Given (403)

{
    "status_code": 401,
    "success": false,
    "message": "Authentication credentials were not provided or are invalid.",
    "message_code": "unauthorized"
}

Returned when the Authorization header is missing, malformed, or the JWT token is invalid or expired. Ensure you are using the correct Bearer token for the target environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Environment Isolation: Always use separate JWT tokens for sandbox and production environments. Never share or cross-use tokens across environments to prevent accidental live bureau queries.

Token Rotation: Implement token refresh logic in your integration. JWT tokens have expiry; ensure your application handles 401 responses gracefully by re-authenticating before retrying the request.

Report Link Expiry Handling: The credit_report_link in the response is a pre-signed S3 URL with a short expiry (typically 600 seconds). Download or cache the report within this window; do not store the raw link for long-term access.

PAN & Business Name Validation: Validate PAN format (5 alphabets + 4 digits + 1 alphabet) and sanitize business_name on the client side before sending the request to minimize unnecessary API calls and error responses.

Consent Logging: Maintain an immutable audit log of user/business consent (timestamp, IP address, consent mechanism) before invoking this API. This is essential for regulatory compliance and dispute resolution.

User Experience Guidelines

Use Mock Mode for Development: Set report_type to "mock" during development and QA to avoid consuming live bureau credits and to ensure deterministic test results.

Display Credit Score Prominently: The credit_score array is returned inline in the response — surface the bureau score to end users immediately, before they click through to the full report link, to provide a fast and informative experience.

Report Access Timeout: Inform users that the report link is time-limited. Provide a "Download Report" action in your UI immediately upon receiving the response, and consider server-side caching of the report if your UX requires deferred access.

Handle Multiple Score Entries: The credit_score field is an array and may contain more than one score entry (e.g., for different bureau models or associated individuals). Ensure your UI handles and renders all entries rather than assuming a single score.

Graceful Error Messaging: Map message_code values to user-friendly messages in your frontend. Avoid exposing raw API error strings directly to end users.

Code Samples

cURL

Python

Node.js

Related APIs

Commercial Credit Report - Fetch Report (JSON): Retrieves the commercial credit report data in structured JSON format instead of a rendered HTML/PDF file — useful for parsing bureau data programmatically.

Individual Credit Report - Fetch Report PDF: Fetches a bureau credit report PDF/HTML for an individual (retail) consumer using their PAN and personal details, following the same consent-driven flow.

PAN Verification: Validates a PAN against government records to confirm business or individual identity before initiating a credit report fetch.

GST Verification: Retrieves GST registration and filing status for a business entity, often used alongside commercial credit reports for comprehensive financial due diligence.

Compliance and Legal Considerations

Consent is Mandatory: This API accesses regulated bureau data. You must obtain and record explicit consent from the business entity (or its authorized representative) before invoking this endpoint. Storing proof of consent is strongly recommended for audits.

Purpose Limitation: Credit report data fetched via this API must be used solely for the declared purpose (e.g., credit assessment, onboarding). Repurposing or redistributing bureau data without authorization may violate bureau licensing agreements and applicable data protection regulations.

Data Retention: Adhere to your bureau agreement and applicable data privacy laws (e.g., IT Act, DPDP Act in India) regarding how long fetched credit report data may be retained and how it must be secured at rest and in transit.

Authorized Users Only: Access to this endpoint should be restricted to authorized personnel and systems within your organization. Implement role-based access controls to prevent unauthorized bureau queries.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://kyc-api.surepass.app/api/v1/credit-report-commercial/fetch-report-pdf' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "business_name": "ABC PRIVATE LIMITED", "pan": "ABCCP1234L", "report_type": "html", "consent": "Y" }'

{ "data": { "client_id": "credit_report_commercial_pdf_cvyjdevFbVdFoclGqaaY", "pan": "ABCCP1234L", "business_name": "ABC PRIVATE LIMITED", "credit_score": [ { "score_name": "ERS 4.0 (retail)", "score_entity": "DUMMY COMPANY NAME", "relationship": "Individual Relation Others", "credit_score": "852" } ], "credit_report": {}, "credit_report_link": "https://aadhaar-kyc-docs.s3.amazonaws.com/credit_report_commercial/credit_report_commercial_pdf_cvyjdevFbVdFoclGqaaY/commercial_report_1777120420221221.html?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=7611497397439d1d3e6354ee6b68df05c8be7ec31bc4ff4270e9089b55230265" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Credit Report Commercial PDF

Commercial Credit Report - Fetch Report PDF#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses