DataFabric API Documentation

Build powerful applications with our comprehensive data services API. Access maps, routing, KYC verification, and user data through a simple REST API.

Base URL

https://datafabric.hiroshiaki.com/api/v1

Fast & Reliable

99.9% uptime SLA with sub-100ms response times

Secure by Default

API key authentication with rate limiting and encryption

Developer Friendly

RESTful API with SDKs for PHP, JavaScript, and Python

Quick Start

Get up and running with DataFabric API in 3 simple steps.

1

Get Your API Key

Sign up for free and generate your API key instantly.

2

Make Your First API Call

Copy and run this example to get directions between two locations:

curl -H "X-Api-Key: your_api_key" \
  "https://datafabric.hiroshiaki.com/api/v1/routes/directions?origin=37.7749,-122.4194&destination=34.0522,-118.2437"
3

Integrate & Scale

Use our official SDKs for PHP, JavaScript, and Python to integrate quickly into your application.

Tip: Use test keys (dfb_test_*) for development and switch to live keys (dfb_live_*) for production.

Authentication

All API requests require authentication using an API key sent in the request header.

API Key Header

Include your API key in the X-Api-Key header with every request:

X-Api-Key: dfb_test_abc123xyz456

Test Keys

Prefix: dfb_test_*

Use for development and testing. No charges apply.

Live Keys

Prefix: dfb_live_*

Use for production. Charges apply based on usage.

Security Warning: Never expose your API keys in client-side code, public repositories, or browser applications. Always keep them server-side.

Routes & Directions API

Calculate optimal routes and turn-by-turn directions

Get optimized routes and turn-by-turn directions between locations.

GET /api/v1/routes/directions

Query Parameters
Parameter Type Required Description
origin string ✓ Starting location (lat,lng)
destination string ✓ Ending location (lat,lng)
mode string driving | walking | cycling (default: driving) 
{
  "status": "success",
  "data": {
    "distance": "382.5 km",
    "duration": "3h 45m",
    "steps": [...]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Rate Limit: Depends on your plan (10-120 req/min)

Cost: $0.005 per request on metered plans

Maps & Tiles API

Render map tiles and generate static map images

Render map tiles and generate static map images.

GET /api/v1/maps/tiles/{z}/{x}/{y}

Returns a map tile image for the specified zoom level and coordinates.

GET /api/v1/maps/static

Generate a static map image with markers and overlays.

Query Parameters: center, zoom, width, height, markers

KYC Verification API

Identity verification with AI-powered document OCR

Comprehensive Know Your Customer verification with AI-powered document OCR, identity checks, risk scoring, and compliance screening.

✨ AI-Powered OCR

Upload document images and automatically extract structured data using AI vision models

🔍 Comprehensive Checks

Document validation, age verification, watchlist screening, and PEP checks

⚡ Real-time Processing

Instant verification results with webhook notifications for async processing

🔒 Secure & Compliant

GDPR compliant, encrypted storage, HMAC-SHA256 hashing for sensitive data

Create KYC Check

POST /api/v1/kyc/checks
Request Body
{
  "user_reference": "user_12345",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "document_type": "passport",
  "document_number": "AB123456",
  "country": "US",
  "email": "john@example.com",
  "phone": "+1234567890",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "webhook_url": "https://your-app.com/webhooks/kyc",
  "metadata": {
    "order_id": "ORD-123"
  }
}
Field Type Required Description
first_name string ✓ First name
last_name string ✓ Last name
date_of_birth string ✓ YYYY-MM-DD format, must be 18+
document_type string ✓ passport | drivers_license | national_id | residence_permit
document_number string ✓ Document number (hashed in storage)
Response (201 Created)
{
  "status": "success",
  "check_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": "approved",
  "kyc_status": "completed",
  "risk_score": "low",
  "verification_details": {
    "checks": {
      "document_valid": true,
      "age_verified": true,
      "identity_verified": true,
      "watchlist_clear": true,
      "pep_check": false
    }
  },
  "expires_at": "2025-12-27T10:30:00Z",
  "request_id": "req_xyz789"
}
NEW

Upload Document Images with AI OCR

Upload ID card, passport, or driver's license images and automatically extract structured data using AI-powered OCR.

POST /api/v1/kyc/checks/{check_id}/documents
Form Data
Content-Type: multipart/form-data

image: [file] (JPEG, PNG, WebP, max 10MB)
image_type: "front" | "back" | "selfie" | "proof_of_address"
auto_extract: true (enable AI OCR)
cURL Example
curl -X POST "https://datafabric.hiroshiaki.com/api/v1/kyc/checks/{check_id}/documents" \
  -H "X-Api-Key: your_api_key" \
  -F "image=@/path/to/ic_front.jpg" \
  -F "image_type=front" \
  -F "auto_extract=true"
AI-Extracted Data
{
  "status": "success",
  "document": {
    "id": 1,
    "image_type": "front",
    "has_ocr_data": true,
    "ocr_data": {
      "document_type": "national_id",
      "full_name": "Ahmad Ibrahim bin Abdullah",
      "first_name": "Ahmad",
      "last_name": "Ibrahim",
      "id_number": "950320-10-5678",
      "date_of_birth": "1995-03-20",
      "gender": "male",
      "nationality": "Malaysian",
      "address": "Jalan Bukit Bintang, KL 50200",
      "confidence": 95,
      "provider": "openrouter_ai"
    }
  }
}

Supported Documents: Malaysian IC (MyKad), Passports, Driver's Licenses, National IDs, Residence Permits

AI Models: Google Gemini 2.0 Flash, GPT-4o Vision, Claude 3 Opus

Get Check Status

GET /api/v1/kyc/checks/{check_id}

Retrieve the status, results, and verification details of a KYC check.

List All Checks

GET /api/v1/kyc/checks?status=completed&result=approved&per_page=20

Filter by status, result, user_reference. Paginated responses.

Get All Documents

GET /api/v1/kyc/checks/{check_id}/documents

Retrieve all uploaded documents and OCR data for a check.

Check Statuses
  • pending - Queued
  • in_progress - Processing
  • completed - Finished
  • failed - Error (can reprocess)
Check Results
  • ✓ approved - Verified
  • ✗ rejected - Failed
  • ! review_required - Manual review
Risk Scores
  • low - All checks passed
  • medium - Minor issues
  • high - Significant risks
💡 Best Practices
  • • Store check_id for future reference
  • • Use webhooks instead of polling for status updates
  • • Upload high-quality images (min 1000px width) for better OCR accuracy
  • • Manually review review_required cases
  • • Test thoroughly with dfb_test_ keys before production

Rate Limit: 120 requests/minute

Cost: $1.50 per verification check

Check Expiry: 30 days

OCR Processing: 2-5 seconds

User Data API

Access and manage user information securely

Access and manage user information securely.

GET /api/v1/users/{id}

Retrieve user profile information.

PATCH /api/v1/users/{id}

Update user profile information.

Cost: $0.002 per request

Secrets Manager

Secure multi-tenant secrets management with envelope encryption

Store and access environment variables and secrets with enterprise-grade security. Multi-tenant, cloud-agnostic secrets manager with API-first access and envelope encryption.

🔐 Envelope Encryption

Three-tier encryption (Root Key → Tenant KEK → Data DEK) using AES-256-GCM

🔑 Service Tokens

Scoped API tokens for runtime access with fine-grained permissions

🏢 Multi-Tenant

Isolated secrets per organization, project, and environment (dev, staging, prod)

🔄 Secret Rotation

Version-controlled secret updates with automatic rollback support

Authentication Types

Portal Authentication

For managing secrets (create, update, delete)

Authorization: Bearer {jwt_token}
Service Token Authentication

For runtime access to secrets

Authorization: Bearer dfsk_xxx...

1. Create Project

POST /api/v1/projects 
curl -X POST "https://datafabric.hiroshiaki.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 1,
    "name": "My App",
    "slug": "my-app"
  }'

Automatically creates dev, staging, and prod environments.

2. Create Secret

POST /api/v1/projects/{projectId}/envs/{envName}/secrets
Request Body
{
  "name": "DB_PASSWORD",
  "value": "your_secret_password",
  "description": "Production database password"
}
Response (201 Created)
{
  "id": "sec_abc123",
  "name": "DB_PASSWORD",
  "description": "Production database password",
  "environment": "prod",
  "project_id": "proj_1",
  "current_version": 1,
  "created_at": "2024-01-01T00:00:00Z"
}

3. Create Service Token

POST /api/v1/projects/{projectId}/envs/{envName}/tokens 
curl -X POST "https://datafabric.hiroshiaki.com/api/v1/projects/proj_1/envs/prod/tokens" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Server",
    "scopes": ["secrets.read"]
  }'

⚠️ Important: Save the returned token immediately - it's only shown once and cannot be retrieved later!

4. Access Secrets at Runtime

GET /api/v1/runtime/projects/{projectId}/envs/{envName}/secrets
Get All Secrets
curl "https://datafabric.hiroshiaki.com/api/v1/runtime/projects/proj_1/envs/prod/secrets" \
  -H "Authorization: Bearer dfsk_your_token"
Response
{
  "secrets": {
    "DB_PASSWORD": "your_secret_password",
    "API_KEY": "sk_live_abc123",
    "STRIPE_SECRET": "sk_test_xyz789"
  }
}

Additional Operations

List All Secrets
GET /api/v1/projects/{projectId}/envs/{envName}/secrets
Get Secret Details
GET /api/v1/projects/{projectId}/envs/{envName}/secrets/{name}
Rotate Secret
POST /api/v1/projects/{projectId}/envs/{envName}/secrets/{name}/rotate

Creates a new version while keeping old version accessible

Delete Secret
DELETE /api/v1/projects/{projectId}/envs/{envName}/secrets/{name}

Usage Examples

PHP/Laravel
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('DATAFABRIC_SECRET_TOKEN'))
    ->get('https://datafabric.hiroshiaki.com/api/v1/runtime/projects/proj_1/envs/prod/secrets');

$secrets = $response->json('secrets', []);
foreach ($secrets as $key => $value) {
    config(["secrets.{$key}" => $value]);
}
JavaScript/Node.js
const response = await fetch(
  'https://datafabric.hiroshiaki.com/api/v1/runtime/projects/proj_1/envs/prod/secrets',
  { headers: { 'Authorization': `Bearer ${process.env.DATAFABRIC_SECRET_TOKEN}` }}
);
const { secrets } = await response.json();
Object.assign(process.env, secrets);
💡 Best Practices
  • • Load secrets once at application startup to minimize API calls
  • • Use service tokens with minimal scopes (secrets.read only)
  • • Never commit service tokens to version control - use environment variables
  • • Store DATAFABRIC_SECRETS_ROOT_KEY securely - losing it makes all secrets unrecoverable
  • • Implement secret rotation for sensitive credentials every 90 days
  • • Use separate projects/environments for development, staging, and production
Security Features
  • ✓ AES-256-GCM encryption
  • ✓ HMAC-SHA256 hashing
  • ✓ Envelope encryption architecture
  • ✓ Rate limiting (600 req/min)
  • ✓ Complete audit logging
  • ✓ TLS/HTTPS only
Supported Environments
  • • dev - Development
  • • staging - Staging/QA
  • • prod - Production
  • • Custom environments supported

Cost: $0.001 per secret access

Rate Limits

Plan Requests/Minute Monthly Limit
Free 10 1,000
Basic 60 50,000
Pro 120 500,000
Enterprise Custom Unlimited

429 Too Many Requests: When rate limit is exceeded, the API returns a 429 status with a Retry-After header.

Official SDKs

Integrate DataFabric API with our official SDKs for PHP, JavaScript, and Python.

PHP SDK

composer require hiroshiaki/datafabric-sdk-php
📦 View on Packagist →

Requires PHP 8.0+ and Guzzle

JavaScript SDK

npm install @datafabric/sdk-js

Node.js 18+ or browser with fetch API

TypeScript definitions included

Python SDK

pip install datafabric-sdk

Python 3.7+ with requests library

Type hints included

Quick Start Example (PHP)
use DataFabric\SDK\KycClient;

$client = new KycClient('your_api_key');

$response = $client->createCheck([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'date_of_birth' => '1990-05-15',
    'document_type' => 'passport',
    'document_number' => 'AB123456'
]);

if ($response->isApproved()) {
    echo "✅ KYC Approved!";
}

Need help? Check out the complete documentation in the /sdk/ directory or run the examples in /examples/

Webhooks

Real-time Event Notifications

Subscribe to events and receive instant updates

Receive real-time notifications for KYC check completions and other events.

Event Types
  • kyc.check.completed - KYC check finished processing
  • kyc.check.failed - KYC check processing failed
  • kyc.check.review_required - Manual review needed
{
  "event": "kyc.check.completed",
  "check_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": "approved",
  "risk_score": "low",
  "occurred_at": "2025-11-27T10:30:00Z"
}

Configuration: Set webhook_url when creating KYC checks

HTTP Response Codes

Code Status Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Error Handling

When an error occurs, the API returns a JSON response with error details:

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  },
  "request_id": "req_abc123"
}

Common Error Codes

  • INVALID_API_KEY - API key is invalid or revoked
  • RATE_LIMIT_EXCEEDED - Too many requests
  • VALIDATION_ERROR - Request validation failed
  • RESOURCE_NOT_FOUND - Requested resource doesn't exist
  • INSUFFICIENT_CREDITS - Account has insufficient credits

💡 Best Practices

  • • Always check the HTTP status code first
  • • Log the request_id for debugging and support
  • • Implement exponential backoff for rate limit errors
  • • Display user-friendly error messages to end users
  • • Monitor error rates in production