Standalone Verification Guide

Validate user contact details (SMS, Email, WhatsApp) or Identity (ID Card + Selfie) without requiring a full user account or login session.

Prerequisites

To use the backend endpoints described in this guide, you must first register your application and authenticate:

Create an App: Sign up at Eaglebirth.com and create a new app if it was not yet.
Get Credentials: Navigate to Dashboard > App to find your App Credentials (External ID, Client ID, Client Secret).
Authenticate: You must authenticate your app to get an Access Token. All API requests below require this token in the header.

How to Authenticate

Follow our App Authentication documentation to learn how to exchange your Client ID and Secret for a Bearer Token.

View Authentication Docs

1. Request Verification Code

This is a server-to-server call. Before redirecting the user, your backend must request an initialization code from the Eaglebirth API using your Access Token.

const fetch = require('node-fetch');

const response = await fetch('https://eaglebirth.com/api/app/generate_code_for_external_auth_verification/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN' // Obtained via App Authentication
  },
  body: JSON.stringify({
    external_id: "YOUR_APP_EXTERNAL_ID",
    verification_type: "sms", 
    user_id: "+1234567890", 
    callback_uri: "https://your-app.com/callback"
  })
});

const data = await response.json();
console.log(data); // { res: "success", code: "INIT_CODE_123" }

Payload Parameters

Parameter	Required	Type	Description
verification_type	Yes	string	Mode of verification: 'sms', 'email', 'whatsapp', 'email_to_sms', 'whatsapp_return', or 'id'. For ID verification, we verify the ID card + selfie and ensure the first_name and last_name provided match those on the ID.
user_id	Optional	string	The Email or Phone Number to verify. Required unless type is 'id'.
first_name	Optional	string	Required only if verification_type is 'id'.
last_name	Optional	string	Required only if verification_type is 'id'.
callback_uri	Yes	URL	Where the user returns after verification.

2. Redirect the User

Once you receive the code from Step 1, redirect the user's browser to the verification page. You must include a state parameter to prevent CSRF attacks.

Verification UI URL

https://auth.eaglebirth.com/verification

javascript

// Client-side Javascript

// 1. Generate a random state string for security
const state = generateRandomString(32);
sessionStorage.setItem('verification_state', state);

// 2. The code received from your backend (Step 1)
const initCode = "INIT_CODE_123"; 

// 3. Construct URL
const baseUrl = "https://auth.eaglebirth.com/verification";
const params = new URLSearchParams({
  external_id: "YOUR_APP_EXTERNAL_ID",
  code: initCode,
  state: state // IMPORTANT: Passed through for security
});

// 4. Redirect
window.location.href = `${baseUrl}?${params.toString()}`;

3. Verification Process

The user will land on the Eaglebirth verification UI. Depending on the verification_type chosen:

SMS / Email / WhatsApp (Standard): The user enters the OTP sent to their device.
WhatsApp Return: We display a code to the user, and they must send that code to our WhatsApp number via a generated link.
ID Verification: The user uploads their Government ID and takes a live selfie for biometric comparison.

Note: The state parameter is preserved throughout this process but is never stored by the Eaglebirth backend. It acts as a secure passthrough.

4. Handling the Callback

Upon successful verification, the user is redirected to your callback_uri with a new authorization code and your original state.

text

https://your-app.com/callback?code=RESULT_CODE_XYZ&state=YOUR_ORIGINAL_STATE

Security Check: Before proceeding, you must verify that the state returned in the URL matches the one you stored in the user's session in Step 2. If they do not match, reject the request.

5. Validate Result

Finally, your backend uses the code received in the callback to fetch the verification results. This also requires your Access Token.

const response = await fetch('https://eaglebirth.com/api/app/check_code_for_external_auth_verification/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    code: "RESULT_CODE_XYZ" // From URL query param
  })
});

const result = await response.json();
console.log(result);