Usage Summary

Endpoint Overview

POST /api/v1/utils/usage/usage-summary

Description

This endpoint generates a comprehensive usage summary report for your Surepass API activities within a specified date range. The report provides detailed analytics on your API consumption patterns, helping you track usage, manage costs, and optimize your integration. The summary can be automatically delivered to a specified email address, making it easy to share with team members or stakeholders.

Key Benefits

Track API usage patterns across a customizable date range

Receive detailed usage reports directly to your email

Monitor consumption to optimize costs and resource allocation

Identify usage trends to inform business decisions

Use Cases

Financial Services

Technology

Enterprise

Generate monthly usage reports for compliance and audit purposes

Track API consumption across different departments for internal cost allocation

Monitor verification volume trends to forecast future needs

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 token
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
start_date	String	Yes	Start date for the usage report in YYYY-MM-DD format
end_date	String	Yes	End date for the usage report in YYYY-MM-DD format
recipient_email	String	Yes	Email address where the usage summary will be sent

Example Request

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

Process Response

Response Parameters

Parameter	Type	Description
status	String	Status of the request (success/failure)
message	String	Descriptive message about the result of the operation
data	Object	Contains additional information about the report generation

Example Successful Response

{
  "status": "success",
  "message": "Usage summary report has been generated and sent to sample@example.com",
  "data": {
    "report_id": "usr_20230615_123456",
    "period": "2019-01-01 to 2020-03-06",
    "recipient": "sample@example.com",
    "generated_at": "2023-06-15T14:30:45Z"
  }
}

Possible Error Responses

Invalid Date Format

Invalid Email

Date Range Too Large

{
  "status": "error",
  "message": "Invalid date format. Please use YYYY-MM-DD format.",
  "error_code": "INVALID_DATE_FORMAT"
}

This error 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 according to your security policies

Use HTTPS for all API communications to ensure data encryption in transit

User Experience Guidelines

Schedule regular usage reports to maintain visibility into API consumption

Consider implementing a dashboard to visualize usage data from these reports

Set up alerts for unusual usage patterns to detect potential issues early

Use different recipient emails for different departments or business units to organize reporting

Code Samples

cURL

Python

Node.js

Related APIs

Usage Details API: Provides granular transaction-level usage data

Billing Summary API: Generates billing summaries based on usage data

Account Statistics API: Offers statistical insights on account usage patterns

Compliance and Legal Considerations

Usage data may contain information that falls under data protection regulations such as GDPR or CCPA. Ensure that access to usage reports is restricted to authorized personnel and that data retention policies are followed. The email recipient should have appropriate authorization to receive potentially sensitive usage information.

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-summary' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "start_date": "2019-01-01", "end_date": "2020-03-06", "recipient_email": "sample@example.com" }'

Usage Summary

Usage Summary#

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

Usage Summary

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples