Usage Report

Endpoint Overview

POST /api/v1/utils/usage/usage-report

Description

This API endpoint generates and delivers a comprehensive usage report for various identity verification services. It allows you to request detailed analytics about your API consumption across different verification categories for a specified date range. The report is automatically generated and sent to the email address provided in the request.

Key Benefits

Track and analyze your API usage across multiple verification services

Receive detailed reports directly to your email for easy sharing and record-keeping

Filter reports by specific verification types to focus on relevant data

Customize date ranges to analyze usage patterns over specific time periods

Use Cases

Financial Services

Technology Platforms

Government & Public Sector

Monitor KYC verification volumes for regulatory compliance reporting

Track usage patterns to optimize API consumption and reduce costs

Generate monthly usage reports for departmental billing allocation

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

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT format
Content-Type	Yes	Application/json

Request Body

Parameter	Type	Required	Description
start_date	String	Yes	Start date for the report in YYYY-MM-DD format
end_date	String	Yes	End date for the report in YYYY-MM-DD format
type	String	Yes	Type of verification service for the report (see supported types below)
recipient_email	String	Yes	Email address where the report will be sent

Supported Report Types

pan - PAN card verification

voter_id - Voter ID verification

aadhaar_validation - Aadhaar validation

gstin - GSTIN verification

license - License verification

voter_ocr - Voter ID OCR

bank_validation - Bank account validation

Example Request

{
  "start_date": "2020-01-01",
  "end_date": "2020-03-06",
  "type": "pan",
  "recipient_email": "sample@example.com"
}

Process Response

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates if the request was successful
message	String	Description of the result or error
status_code	Integer	HTTP status code of the response

Example Successful Response

{
  "success": true,
  "message": "Report generation initiated. You will receive the report on the provided email address shortly.",
  "status_code": 200
}

Possible Error Responses

Invalid Date Format

Invalid Report Type

Invalid Email

Authentication Error

{
  "success": false,
  "message": "Invalid date format. Please use YYYY-MM-DD format.",
  "status_code": 400
}

Occurs when the date format provided doesn't match the required YYYY-MM-DD format.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Rotate JWT tokens periodically to minimize security risks

Validate email addresses before sending to prevent potential data leakage

User Experience Guidelines

Implement date range validation to ensure end_date is after start_date

Provide clear feedback to users when a report request is successfully submitted

Consider implementing a notification system to alert users when reports are ready

Limit date ranges to reasonable periods (e.g., 90 days) to ensure timely report generation

Code Samples

cURL

Python

Node.js

Related APIs

Verification Status API: Check the status of individual verification requests

Account Balance API: View current account balance and usage limits

Verification History API: Retrieve historical verification data for specific IDs

Compliance and Legal Considerations

Usage reports may contain sensitive information about verification activities. Ensure that recipient email addresses are secure and belong to authorized personnel. Reports should be handled in accordance with data protection regulations such as GDPR or local data privacy laws. Retention of these reports should follow your organization's data retention policies.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/utils/usage/usage-report' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "start_date": "2020-01-01", "end_date": "2020-03-06", "type": "pan", "recipient_email": "sample@example.com" }'

Usage Report

Usage Report#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Supported Report Types#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Usage Report

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Supported Report Types

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples