API Documentation

Integrate government-grade identity verification into your application with our RESTful API. Get started in minutes with our comprehensive guides and code examples.

API v2.0RESTJSON

Getting Started Authentication API Endpoints Verification Documents Webhooks Error Handling Rate Limits SDKs & Libraries

Getting Started

Base URL

https://api.fidel80.com/v2

Quick Start

Follow these steps to make your first API call:

Create a free account to get your API keys

Get your API credentials

Navigate to Settings → API Keys in your dashboard

Make your first request

Use the examples below to verify your first identity

Test Mode

Use test mode to develop and test your integration without consuming live verifications.

Test API Key prefix: test_

Authentication

Fidel80 uses API keys to authenticate requests. Include your API key in the Authorization header:

HTTP

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure

Never expose your API keys in client-side code, public repositories, or logs.

Key Types

Test Keys

For development and testing. No charges apply.

test_sk_...

Live Keys

For production use. Charges apply per verification.

live_sk_...

API Endpoints

POST/verifications

Create a new identity verification request. This initiates the verification process by validating the provided information against national databases.

Request Body

Parameter	Type	Required	Description
`first_name`	string	Yes	First name as it appears on ID
`last_name`	string	Yes	Last name as it appears on ID
`date_of_birth`	string	Yes	Date in YYYY-MM-DD format
`id_number`	string	Yes	National ID or passport number
`country`	string	Yes	ISO 3166-1 alpha-2 country code
`document_type`	string	No	national_id, passport, drivers_license
`metadata`	object	No	Custom key-value pairs for reference

bash

curl -X POST https://api.fidel80.com/v2/verifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-05-15",
    "id_number": "123456789",
    "country": "US",
    "document_type": "national_id",
    "metadata": {
      "user_id": "user_12345",
      "application_id": "app_67890"
    }
  }'

Response

json

{
  "id": "ver_1234567890abcdef",
  "object": "verification",
  "status": "verified",
  "result": "match",
  "confidence": 0.98,
  "created_at": "2025-10-22T14:30:00Z",
  "data": {
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-05-15",
    "id_number": "***6789",
    "country": "US",
    "document_type": "national_id"
  },
  "verification_details": {
    "name_match": true,
    "dob_match": true,
    "id_valid": true,
    "database_verified": true
  },
  "metadata": {
    "user_id": "user_12345",
    "application_id": "app_67890"
  }
}

GET/verifications/:id

Retrieve the details of a specific verification by its ID.

bash

curl https://api.fidel80.com/v2/verifications/ver_1234567890abcdef \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/verifications

List all verifications with optional filtering and pagination.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination
`status`	string	Filter by status: verified, pending, failed
`created_after`	timestamp	Filter by creation date

bash

curl "https://api.fidel80.com/v2/verifications?limit=20&status=verified" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/documents

Upload identity documents (ID cards, passports, etc.) for enhanced verification with facial matching capabilities.

Request (Multipart Form Data)

bash

curl -X POST https://api.fidel80.com/v2/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.jpg" \
  -F "type=id_front" \
  -F "verification_id=ver_1234567890abcdef"

Document Types

id_front

Front of ID card

id_back

Back of ID card

passport

Passport photo page

selfie

Live selfie for facial match

Webhooks

Webhooks allow you to receive real-time notifications when verification events occur. Configure webhook endpoints in your dashboard.

Event Types

verification.completed

Triggered when a verification is completed

verification.failed

Triggered when a verification fails

document.processed

Triggered when a document upload is processed

Webhook Payload

json

{
  "id": "evt_1234567890abcdef",
  "type": "verification.completed",
  "created": 1729605600,
  "data": {
    "object": {
      "id": "ver_1234567890abcdef",
      "status": "verified",
      "result": "match",
      "confidence": 0.98
    }
  }
}

Webhook Security

Verify webhook signatures to ensure requests are from Fidel80:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook endpoint
app.post('/webhooks/fidel80', (req, res) => {
  const signature = req.headers['x-fidel80-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  res.status(200).send('OK');
});

Error Handling

Fidel80 uses conventional HTTP response codes to indicate the success or failure of requests.

HTTP Status Codes

200Success - Request completed successfully

400Bad Request - Invalid parameters

401Unauthorized - Invalid API key

403Forbidden - Insufficient permissions

404Not Found - Resource doesn't exist

429Too Many Requests - Rate limit exceeded

500Server Error - Something went wrong

Error Response Format

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "Missing required parameter: first_name",
    "param": "first_name"
  }
}

Error Types

Type	Description
`api_error`	Internal server error
`authentication_error`	Authentication failed
`invalid_request_error`	Invalid parameters provided
`rate_limit_error`	Too many requests
`verification_error`	Verification could not be completed

Rate Limits

API requests are rate-limited to ensure fair usage and system stability. Rate limits vary by plan and endpoint.

Starter Plan

100 requests/minute

10,000 requests/day

Professional Plan

500 requests/minute

100,000 requests/day

Enterprise Plan

Custom limits

Negotiated SLA

Rate Limit Headers

Every API response includes headers with rate limit information:

HTTP

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1729605600

Handling Rate Limits

javascript

async function verifyWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fidel80.verifications.create(data);
      return response;
    } catch (error) {
      if (error.type === 'rate_limit_error') {
        const retryAfter = error.headers['retry-after'] || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

SDKs & Libraries

Official SDKs are available for popular programming languages to simplify integration.

Node.js

bash

npm install fidel80

View on GitHub →

Python

bash

pip install fidel80

View on GitHub →

Ruby

bash

gem install fidel80

View on GitHub →

PHP

bash

composer require fidel80/fidel80-php

View on GitHub →

Java

xml

<dependency>
  <groupId>com.fidel80</groupId>
  <artifactId>fidel80-java</artifactId>
  <version>2.0.0</version>
</dependency>

View on GitHub →

Go

bash

go get github.com/fidel80/fidel80-go

View on GitHub →

Need help?

Our developer support team is here to help you integrate Fidel80.