Developer Documentation

Your guide to integrating with the TRACEIT ecosystem.

Getting Started

Follow these simple steps to make your first API call.

Step 1: Login to your Account

First, login to your account. Access to the API is automatically granted based on your active session.

Step 2: Find a Tool

Explore our Tools Dashboard to find the data solution you need. Each tool is ready to use directly.

Step 3: Make Your First Request

Use your favorite HTTP client or our code examples to make a request. Remember to include your user ID in the `x-user-id` header for server-to-server requests.

curl "https://traceit.com/api/pan-details?pan=ABCDE1234F" \
-H "x-user-id: YOUR_LOGGED_IN_USER_ID"

Authentication

How to securely authenticate your API requests.

TRACEIT authenticates requests based on your active user session. When using our internal tools, this is handled automatically. For server-to-server requests, you must pass your Firebase Auth User ID in the x-user-id HTTP header.

Requests made without a valid user ID or from a banned account will fail with a 401 Unauthorized or 403 Forbidden error.

Billing & Fair Use

Our billing model is simple: you only pay for what you use.

TRACEIT operates on a pay-as-you-go wallet system. Before any API call is processed, we check your wallet balance. If the balance is sufficient to cover the cost of the call, we provisionally deduct the amount.

The "Pay for Success" Guarantee

You are **only** charged for successful API responses that return the data you requested. If an API call fails for any reason (e.g., the external service is down, the requested data is not found, or there's an internal error), the provisionally deducted amount is **instantly refunded** to your wallet. Failed calls are always free.

Error Codes

Understand the common error responses from the TRACEIT gateway.

Status Code	Meaning	Reason
200 OK	Success	The request was successful. The body contains the requested data.
401 Unauthorized	Authentication Error	The `x-user-id` header is missing or the user is not logged in.
402 Payment Required	Insufficient Balance	Your wallet balance is too low to perform the request. No charge was made.
403 Forbidden	Permission Denied	The associated user account is banned.
404 Not Found	Endpoint Not Found	The requested API endpoint does not exist.
500 Internal Server Error	Gateway Error	An unexpected error occurred within the TRACEIT gateway. Your request was not processed and you were not charged.
502 Bad Gateway	Upstream Error	The underlying service provider for the API is unavailable or returned an error. You were not charged.

Security

Our commitment to securing your data and access.

User-Based Authorization

All API access is tied directly to your user account and session. This ensures that all actions are auditable and secure. Do not share your account credentials.

Rate Limiting

To protect the platform from abuse, we enforce rate limits on a per-user basis. If you exceed the rate limit, you will receive a 429 Too Many Requests error.