API Integration Guide

Overview

This guide provides comprehensive instructions for integrating with the Cr3dentials Partner API. Use this documentation to implement verification sessions and manage the verification process programmatically.

Getting Started

Prerequisites

Before you begin, ensure you have:

  • An active partner account with API access

  • A valid API key from the Partner Portal

  • Development environment for API testing

Authentication

All API endpoints require authentication using your API key. Some endpoints also require CSRF token validation for additional security.

Required Headers

x-api-key: YOUR_API_KEY_HERE
x-csrf-token: CSRF_TOKEN (required for specific endpoints)

Base URL

https://api.cr3dentials.xyz/partner

API Endpoints Reference

1. Get Verification Types

Retrieves all available verification types for your integration.

GET /types

Example Request:

curl -X GET "https://api.cr3dentials.xyz/partner/types" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Income Verification",
      "description": "Verify income sources and amounts"
    },
    {
      "id": 2,
      "name": "Identity Verification", 
      "description": "Verify personal identity details"
    }
  ]
}

2. Get Verification Sources

Retrieves available data sources for a specific verification type.

GET /sources/type/:verificationTypeId

Parameters:

  • verificationTypeId (path): ID of the verification type

Example Request:

curl -X GET "https://api.cr3dentials.xyz/partner/sources/type/1" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Bank Statement",
      "description": "Bank account transaction history",
      "sourceName": "chase-bank"
    },
    {
      "id": 2,
      "name": "Pay Stub",
      "description": "Employment pay statements",
      "sourceName": "paystub-verification"
    }
  ]
}

3. Create Verification Session

Creates a new verification session for a user.

POST /session

Request Body:

{
  "params": {
    "verificationTypeId": 1,
    "allowedSources": [1, 2],
    "expiryDate": "2024-12-31",
    "applicantId": "user_12345",
    "applicantData": {
      "email": "[email protected]",
      "type": "email"
    },
    "instructions": "Please complete your income verification",
    "applicantFirstName": "John",
    "applicantLastName": "Doe"
  }
}

Request Parameters:

Parameter
Type
Required
Description

verificationTypeId

number

Yes

ID of the verification type

allowedSources

number[]

Yes

Array of allowed data source IDs

expiryDate

string

Yes

Expiration date (YYYY-MM-DD format)

applicantId

string

No

Your internal user ID for the applicant( applicant was selected by searching our user database)

applicantData

object

No

Applicant contact information

applicantData.email

string

No

Applicant's email address

applicantData.type

string

No

Contact type: "email", "phone", or "wallet"

instructions

string

No

Custom instructions for the applicant

applicantFirstName

string

No

Applicant's first name

applicantLastName

string

No

Applicant's last name

Example Request:

curl -X POST "https://api.cr3dentials.xyz/partner/session" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "verificationTypeId": 1,
      "allowedSources": [1],
      "expiryDate": "2024-12-31",
      "applicantId": "user_12345",
      "applicantData": {
        "email": "[email protected]",
        "type": "email"
      },
      "instructions": "Please verify your income for loan application",
      "applicantFirstName": "John",
      "applicantLastName": "Doe"
    }
  }'

Response:

{
  "success": true,
  "message": "Verification session created successfully",
  "data": {
    "id": 123,
    "status": "PENDING",
    "verificationLink": "https://app.cr3dentials.xyz/verify?token=abc123",
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}

4. Verify Verification Link

Validates a verification link token and returns session information.

GET /verification/verify?token=TOKEN_HERE&sessionId={SessionId}

Query Parameters:

  • token (required): Verification link token

Example Request:

curl -X GET "https://api.cr3dentials.xyz/partner/verification/verify?token=abc123&sessionId=1" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Response:

{
  "success": true,
  "message": "Verification link verified successfully",
  "data": {
    "session": {
      "id": 123,
      "status": "PENDING",
      "applicantId": "user_12345"
    },
    "csrfToken": "csrf_token_here"
  }
}

5. Select Data Sources

Selects data sources for a verification session.

POST /step/select-data-source

Request Body:

{
  "dataSourceIds": [1, 2],
  "sessionId": 123
}

Example Request:

curl -X POST "https://api.cr3dentials.xyz/partner/step/select-data-source" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "x-csrf-token: CSRF_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "dataSourceIds": [1],
    "sessionId": 123
  }'

6. Get Session Steps

Retrieves all verification steps for a session.

GET /steps/session/:sessionId

Example Request:

curl -X GET "https://api.cr3dentials.xyz/partner/steps/session/123" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Response:

{
  "status": "success",
  "data": {
    "steps": [
      {
        "id": 456,
        "status": "PENDING",
        "type": "BANK_VERIFICATION",
        "sessionId": 123
      }
    ]
  }
}

7. Get Step Details

Retrieves details of a specific verification step.

GET /steps/:stepId

Example Request:

curl -X GET "https://api.cr3dentials.xyz/partner/steps/456" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Response:

{
  "id": 456,
  "status": "VERIFIED",
  "type": "BANK_VERIFICATION",
  "sessionId": 123,
  "verificationData": {
    "source": "chase-bank",
    "verifiedAt": "2024-01-15T14:30:00Z"
  }
}

8. Get Reviewer Sessions

Retrieves sessions for review (if you have reviewer permissions).

GET /reviewer/sessions?status=PENDING

Query Parameters:

  • status (optional): Filter by session status

Example Request:

curl -X GET "https://api.cr3dentials.xyz/partner/reviewer/sessions?status=REVIEWING" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Response:

{
  "success": true,
  "sessions": [
    {
      "id": 123,
      "status": "REVIEWING",
      "applicantFirstName": "John",
      "applicantLastName": "Doe",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Integration Workflow

Basic Integration Flow

  1. Get Available Verification Types

    GET /types

  2. Get Data Sources for Verification Type

    GET /sources/type/{verificationTypeId}

  3. Create a Verification Session

    POST /session

  4. Redirect User to Verification Link

    • The email has been sent with verification link.Open it by using deeplink or copy the link and paste to our mobile app

    • User completes verification process

  5. Monitor Session Status

    GET /steps/session/{sessionId}

Complete Integration Example

class Cr3dentialsAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.cr3dentials.xyz/partner';
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const config = {
      headers: {
        'x-api-key': this.apiKey,
        'Content-Type': 'application/json',
        ...options.headers
      },
      ...options
    };

    const response = await fetch(url, config);
    
    if (!response.ok) {
      throw new Error(`API request failed: ${response.status} ${response.statusText}`);
    }
    
    return response.json();
  }

  // Get all verification types
  async getVerificationTypes() {
    return this.request('/types');
  }

  // Get data sources for a verification type
  async getDataSources(verificationTypeId) {
    return this.request(`/sources/type/${verificationTypeId}`);
  }

  // Create a verification session
  async createSession(params) {
    return this.request('/session', {
      method: 'POST',
      body: JSON.stringify({ params })
    });
  }

  // Get session steps
  async getSessionSteps(sessionId) {
    return this.request(`/steps/session/${sessionId}`);
  }

  // Get step details
  async getStepDetails(stepId) {
    return this.request(`/steps/${stepId}`);
  }
}

// Usage example
async function createIncomeVerification(applicantData) {
  const api = new Cr3dentialsAPI('YOUR_API_KEY');
  
  try {
    // 1. Get verification types
    const types = await api.getVerificationTypes();
    const incomeType = types.data.find(type => 
      type.name === 'Income Verification'
    );
    
    // 2. Get available data sources
    const sources = await api.getDataSources(incomeType.id);
    
    // 3. Create verification session
    const session = await api.createSession({
      verificationTypeId: incomeType.id,
      allowedSources: sources.data.map(source => source.id),
      expiryDate: '2024-12-31',
      applicantId: applicantData.userId,
      applicantData: {
        email: applicantData.email,
        type: 'email'
      },
      instructions: 'Please complete your income verification for loan processing',
      applicantFirstName: applicantData.firstName,
      applicantLastName: applicantData.lastName
    });
    
    console.log('Verification session created:', session.data);
    
    // 4. Redirect user to verification link
    window.location.href = session.data.verificationLink;
    
  } catch (error) {
    console.error('Verification creation failed:', error);
  }
}

// Monitor session progress
async function monitorSession(sessionId) {
  const api = new Cr3dentialsAPI('YOUR_API_KEY');
  
  try {
    const steps = await api.getSessionSteps(sessionId);
    
    for (const step of steps.data.steps) {
      const stepDetails = await api.getStepDetails(step.id);
      console.log(`Step ${step.id}: ${stepDetails.status}`);
    }
    
  } catch (error) {
    console.error('Failed to monitor session:', error);
  }
}

Status References

Session Statuses

Status
Description

PENDING

Session created, waiting for user action

PROCESSING

User is actively completing verification

COMPLETED

Verification successfully completed

REVIEWING

Manual review in progress

FAILED

Verification failed

EXPIRED

Session expired without completion

REJECTED

Manual review rejected

Step Statuses

Status
Description

PENDING

Step waiting to be started

INITIATED

Step has been started

IN_PROGRESS

Step is actively being processed

VERIFIED

Step completed successfully

FAILED

Step failed verification

EXPIRED

Step expired

COMPLETED

Step fully completed

Error Handling

Standard Error Response

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Common Error Codes

Code
Description
Solution

400

Bad Request

Check request format and required fields

401

Unauthorized

Verify API key is correct and active

403

Forbidden

Check API key permissions

404

Not Found

Verify endpoint URL and resource ID

429

Rate Limited

Reduce request frequency

500

Server Error

Contact support if persistent

Error Handling Best Practices

async function handleApiCall(apiCall) {
  try {
    const result = await apiCall();
    return { success: true, data: result };
  } catch (error) {
    console.error('API Error:', error);
    
    // Handle specific error codes
    if (error.status === 401) {
      // Handle authentication error
      return { success: false, error: 'Invalid API key' };
    } else if (error.status === 429) {
      // Handle rate limiting
      return { success: false, error: 'Rate limit exceeded. Please retry later.' };
    } else if (error.status >= 500) {
      // Handle server errors
      return { success: false, error: 'Server error. Please contact support.' };
    }
    
    return { success: false, error: error.message };
  }
}

Security Best Practices

API Key Security

✅ Do:

  • Store API keys in environment variables

  • Use different keys for development and production

  • Rotate keys regularly

  • Monitor API key usage

❌ Don't:

  • Commit API keys to version control

  • Share keys via email or chat

  • Use production keys in development

  • Leave unused keys active

Rate Limiting

The API implements rate limiting per API key:

  • Default: 100 requests per minute

  • Configurable limits available for enterprise plans

  • Rate limit headers included in responses

Data Handling

  • All data transmitted is encrypted in transit (HTTPS)

  • Sensitive verification data is encrypted at rest

  • API responses do not include raw user credentials

  • Verification results are provided in processed format only

Testing Your Integration

1. Test Environment Setup

# Set your development API key
export API_KEY="your_dev_api_key_here"

# Test basic connectivity
curl -X GET "https://api.cr3dentials.xyz/partner/types" \
  -H "x-api-key: $API_KEY"

2. Integration Testing Checklist

  • [ ] API key authentication working

  • [ ] Can retrieve verification types

  • [ ] Can get data sources for verification types

  • [ ] Can create verification sessions successfully

  • [ ] Verification link redirects work correctly

  • [ ] Can monitor session and step status

  • [ ] Error handling implemented for all scenarios

  • [ ] Rate limiting respected

  • [ ] Proper logging implemented

3. Test Data

Use these test values for development:

{
  "testApplicant": {
    "applicantId": "test_user_123",
    "applicantData": {
      "email": "[email protected]",
      "type": "email"
    },
    "applicantFirstName": "Test",
    "applicantLastName": "User",
    "expiryDate": "2024-12-31",
    "instructions": "This is a test verification"
  }
}
PreviousPartner Portal GuideNextWebhooks

Last updated