Frequently Asked Questions
Find answers to common questions about our platform
To create and manage API Keys:
1. Navigate to your dashboard after logging in
2. Go to the "API Key Management" section in the sidebar
3. Click "Create New Key" to create a new key
4. Copy and securely store your API key - it will only be shown once
5. You can view, regenerate, or revoke existing keys from the same section
Important: Keep your API keys secure and never share them publicly or in client-side code.
Go to API Keys1. Navigate to your dashboard after logging in
2. Go to the "API Key Management" section in the sidebar
3. Click "Create New Key" to create a new key
4. Copy and securely store your API key - it will only be shown once
5. You can view, regenerate, or revoke existing keys from the same section
Important: Keep your API keys secure and never share them publicly or in client-side code.
To get started with integrating OneVerify API into your services, please refer to our full API documentation:
https://documenter.getpostman.com/view/43842592/2sB2cVfhHc
The documentation includes all the required headers and parameters you need to pass for each endpoint.
https://documenter.getpostman.com/view/43842592/2sB2cVfhHc
The documentation includes all the required headers and parameters you need to pass for each endpoint.
All API requests (except registration and login) require authentication via these headers:
Example API request:
X-API-KEY: Your unique API key (Required)
X-USER-ID: The user ID associated with the API key (Required)
Authorization: Bearer [token received after login] (Required)
Example API request:
curl -X GET "https://api.oneverify.com/api/v1/endpoint" \
-H "X-API-KEY: your-api-key" \
-H "X-USER-ID: your-user-id" \
-H "Authorization: Bearer your-access-token" \
-H "Content-Type: application/json"
The base URL and all necessary credentials have been sent to your registered email address. Please check your inbox (and spam folder) for the onboarding email containing:
• Base URL for API requests
• Your login credentials
• Additional setup information
If you haven't received this email, please contact support.
• Base URL for API requests
• Your login credentials
• Additional setup information
If you haven't received this email, please contact support.
The credentials sent in your onboarding email are for dashboard access. Once you log into the dashboard, you can:
• Create and manage API keys
• Access your User ID
• Use these credentials to authenticate API requests
If you haven't received your onboarding email with credentials, please contact support.
• Create and manage API keys
• Access your User ID
• Use these credentials to authenticate API requests
If you haven't received your onboarding email with credentials, please contact support.
Access tokens include an
Handling token expiration:
1. Reactive approach: Monitor for 401 (Unauthorized) status codes and automatically trigger a new login request
2. Proactive approach: Use the
When you receive a 401 error, call the login endpoint again to obtain a fresh access token.
expires_at field indicating their validity period. Typically, tokens expire after about one hour of inactivity.
Handling token expiration:
1. Reactive approach: Monitor for 401 (Unauthorized) status codes and automatically trigger a new login request
2. Proactive approach: Use the
expires_at information to refresh tokens before they expire
When you receive a 401 error, call the login endpoint again to obtain a fresh access token.
The authentication token includes an
To handle this efficiently:
• Implement a mechanism that catches a 401 (Unauthorized) status code and automatically triggers a new login request to obtain a fresh access token
• Alternatively, you can use the
This way, you don't need to manually log in every time you make a verification request.
expires_at field, which indicates its validity period. Typically, it expires after about one hour of inactivity.
To handle this efficiently:
• Implement a mechanism that catches a 401 (Unauthorized) status code and automatically triggers a new login request to obtain a fresh access token
• Alternatively, you can use the
expires_at information to refresh the token proactively before it expires
This way, you don't need to manually log in every time you make a verification request.
NIN-related endpoints require a
To get valid request reasons:
• Call the endpoint:
• This returns a list of valid reason codes
• Use one of these codes in your NIN verification requests
Example NIN request body:
requestReason parameter to comply with regulatory requirements.
To get valid request reasons:
• Call the endpoint:
GET /api/v1/ninAuth/getRequestReasons
• This returns a list of valid reason codes
• Use one of these codes in your NIN verification requests
Example NIN request body:
{
"nin": "12345678901",
"requestReason": "EMPLOYMENT_VERIFICATION"
}
We don't currently have an SDK available for facial verification image capture. However, we may develop one in the future.
Recommended alternative:
You can build the interface to capture the images at your end. The endpoint requires:
• 1 selfie image
• 4 liveness images
Important: Keep the sizes of the images as small as possible (in KB) to avoid payload size issues.
Recommended alternative:
You can build the interface to capture the images at your end. The endpoint requires:
• 1 selfie image
• 4 liveness images
Important: Keep the sizes of the images as small as possible (in KB) to avoid payload size issues.
Yes - in the sandbox (test) environment, the system is not performing a real biometric comparison.
It's designed to always return a successful verification response for the test NIN
In other words, the sandbox just simulates a successful verification - it doesn't actually check that the face matches the NIN. This allows you to test your integration without needing real biometric data.
It's designed to always return a successful verification response for the test NIN
12345678901, regardless of what face image you provide.
In other words, the sandbox just simulates a successful verification - it doesn't actually check that the face matches the NIN. This allows you to test your integration without needing real biometric data.
For optimal results with the "Verify NIN with Facial" endpoint, you should send:
• 1 selfie image
• 4 liveness images
Important: Keep the sizes of the images as small as possible (in KB) to avoid "413 Payload Too Large" errors.
• 1 selfie image
• 4 liveness images
Important: Keep the sizes of the images as small as possible (in KB) to avoid "413 Payload Too Large" errors.
This error typically occurs when you're sending images that are too large or too many images.
Recommendations:
• Send exactly 1 selfie image and 4 liveness images (not more)
• Keep the sizes of all images as small as possible (in KB)
• Compress images before sending them
• Consider reducing image resolution while maintaining quality sufficient for verification
If you continue to experience issues, check the actual file sizes of your images.
Recommendations:
• Send exactly 1 selfie image and 4 liveness images (not more)
• Keep the sizes of all images as small as possible (in KB)
• Compress images before sending them
• Consider reducing image resolution while maintaining quality sufficient for verification
If you continue to experience issues, check the actual file sizes of your images.
If you're receiving a "connect ECONNREFUSED" error, this could indicate:
• The API server is temporarily unavailable
• The API gateway might be down
• There might be a network connectivity issue
First steps:
1. Verify you're using the correct base URL from your onboarding email
2. Check your network connection
3. Try again after a few minutes
If the issue persists, please contact support for server status updates.
• The API server is temporarily unavailable
• The API gateway might be down
• There might be a network connectivity issue
First steps:
1. Verify you're using the correct base URL from your onboarding email
2. Check your network connection
3. Try again after a few minutes
If the issue persists, please contact support for server status updates.
Yes, we have an endpoint that allows you to query NIN details using a phone number. The endpoint is:
For NIN-related endpoints specifically, you can use:
•
•
The data response format is the same as other verification methods.
GET {baseUrl}/verify/verifyPhoneNumber?phone=07012345678&searchtype=advance
For NIN-related endpoints specifically, you can use:
•
/ninAuth/getNINDetails
•
/ninAuth/getNINDetailsWithPhone
The data response format is the same as other verification methods.
The endpoint for phone number verification is:
For NIN-related phone verification, use:
•
•
Replace
GET {baseUrl}/verify/verifyPhoneNumber?phone=07012345678&searchtype=advance
For NIN-related phone verification, use:
•
/ninAuth/getNINDetails
•
/ninAuth/getNINDetailsWithPhone
Replace
{baseUrl} with your production base URL found in your onboarding email.If you're getting a validation failed error when trying to change your password, try the following:
• Use a different password
• Ensure you're using a very strong password that meets all standard requirements
Password requirements typically include:
• Minimum length (usually 8-12 characters)
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character
If the issue persists, contact support.
• Use a different password
• Ensure you're using a very strong password that meets all standard requirements
Password requirements typically include:
• Minimum length (usually 8-12 characters)
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character
If the issue persists, contact support.
No, API keys are not automatically sent. You need to create your API keys yourself from the client portal.
To create API keys:
1. Log into the dashboard using your credentials
2. Navigate to the "API Key Management" section
3. Click "Create New Key"
4. Copy and securely store your API key
Your API key will only be shown once, so make sure to save it securely.
Go to API KeysTo create API keys:
1. Log into the dashboard using your credentials
2. Navigate to the "API Key Management" section
3. Click "Create New Key"
4. Copy and securely store your API key
Your API key will only be shown once, so make sure to save it securely.
The production URL has been sent to your registered email address in your onboarding email.
Please check your email (and spam folder) for the complete production URL and other credentials. If you cannot find it, please contact support.
Note: Do not use
Please check your email (and spam folder) for the complete production URL and other credentials. If you cannot find it, please contact support.
Note: Do not use
https://web.fontanella.app/api/v1/ - use the URL provided in your onboarding email instead.Please contact support for information about your current access level and instructions on how to access Level 1.
Access levels determine which endpoints and features you can use. Support will provide you with specific instructions based on your account configuration.
Access levels determine which endpoints and features you can use. Support will provide you with specific instructions based on your account configuration.
Yes, we do charge for failed verifications including those that return 400 error codes.
Reason: We are charged by our upstream provider for failed verifications, so we pass these costs along.
To minimize unnecessary charges:
• Validate input data before making API calls
• Test thoroughly in the sandbox environment first
• Implement proper error handling
• Review API documentation to ensure correct request formatting
Reason: We are charged by our upstream provider for failed verifications, so we pass these costs along.
To minimize unnecessary charges:
• Validate input data before making API calls
• Test thoroughly in the sandbox environment first
• Implement proper error handling
• Review API documentation to ensure correct request formatting
Our API uses standard HTTP status codes:
Success Codes:
•
•
Error Codes:
•
•
•
•
•
•
•
Error responses include a descriptive message to help troubleshoot the issue.
Success Codes:
•
200: Request successful
•
201: Resource created successfully
Error Codes:
•
400: Bad Request - Check your request parameters
•
401: Unauthorized - Invalid or expired token
•
403: Forbidden - Insufficient permissions
•
404: Not Found - Endpoint or resource doesn't exist
•
413: Payload Too Large - Reduce image sizes or count
•
429: Too Many Requests - Rate limit exceeded
•
500: Internal Server Error - Contact support
Error responses include a descriptive message to help troubleshoot the issue.