Offer Validation and IPE on your website

Set up API access

1. Sign in to your SMARTDATAS account and fund your wallet.
2. Open Developer API Keys, name your website, and generate a key. Copy the full key when it appears; it is shown once.
3. Store the key in your website's server environment as SMARTDATAS_API_KEY.
4. Send Authorization: Bearer YOUR_API_KEY with every API request. X-API-Key is also supported.

Keep the key on your server. Requests made with it access your account and spend your wallet balance. Your browser should call your own server, which calls SMARTDATAS.

Check your key and account balance before submitting:

curl https://smartdatas.com.ng/api/v1/me.php \
  -H "Authorization: Bearer $SMARTDATAS_API_KEY"

Submit a request

Base URL: https://smartdatas.com.ng. Send a JSON body with Content-Type: application/json. Both services support single and bulk submissions.

curl -X POST https://smartdatas.com.ng/api/v1/validation.php \
  -H "Authorization: Bearer $SMARTDATAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nin":"12345678901","validation_type":"full","slip_type":"standard"}'

curl -X POST https://smartdatas.com.ng/api/v1/ipe.php \
  -H "Authorization: Bearer $SMARTDATAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tracking_id":"ABC1234567890"}'

The identifiers above are examples. Supply the customer's real identifier for an actual request.

A successful single submission returns HTTP 201 and data.state = "pending". It debits your wallet at your account's service price and queues the request for manual processing. The result becomes available later.

{
  "status": "success",
  "data": {
    "reference": "YOUR_REFERENCE",
    "state": "pending",
    "amount": "YOUR_ACCOUNT_PRICE",
    "currency": "NGN",
    "wallet_balance": "YOUR_REMAINING_BALANCE"
  }
}

This shortened response illustrates the fields to save. Actual amounts are decimal strings; the response also includes a message and the submitted identifier.

Bulk submissions

For Validation, send up to 100 NINs in {"nins":["12345678901","12345678902"]}. For IPE, send up to 200 tracking IDs or NINs in {"entries":["ABC1234567890","ABC1234567891"]}; each entry must contain 6–20 alphanumeric characters.

Bulk requests return HTTP 200 with data.summary and data.items. Check each item's state and reference: a successful HTTP response can contain skipped or failed items. Processing stops if the wallet lacks funds; summary.not_reached counts entries that were not attempted.

Check status and retrieve results

Save data.reference after submitting. Poll the same endpoint using ?reference= and your API key. Checking a result does not create another submission.

curl "https://smartdatas.com.ng/api/v1/validation.php?reference=YOUR_REFERENCE" \
  -H "Authorization: Bearer $SMARTDATAS_API_KEY"

curl "https://smartdatas.com.ng/api/v1/ipe.php?reference=YOUR_REFERENCE" \
  -H "Authorization: Bearer $SMARTDATAS_API_KEY"

Check at a reasonable interval, such as once per minute. data.result may be null until a result is attached. IPE clearance details, including a resolved NIN or new tracking ID, are returned in the result text or document when available.

Each key can access only its owner's submissions. To list history, use GET on the endpoint without a reference. Optional filters: status=pending|processing|done|failed, limit=1..100 (default 50), and offset.

PHP example for your website's server

This example submits one IPE request using PHP cURL. Run it from an authenticated action on your server. Replace the tracking ID with your customer's input and store the returned reference against that customer's order.

<?php
$apiKey = getenv('SMARTDATAS_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('SMARTDATAS_API_KEY is not configured.');
}

$request = curl_init('https://smartdatas.com.ng/api/v1/ipe.php');
curl_setopt_array($request, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'tracking_id' => 'ABC1234567890',
    ], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($request);
$httpCode = curl_getinfo($request, CURLINFO_HTTP_CODE);
$transportError = curl_error($request);
curl_close($request);

if ($body === false) {
    // Check submission history before retrying a timed-out POST.
    throw new RuntimeException('SMARTDATAS request failed: ' . $transportError);
}
$response = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($httpCode !== 201 || ($response['status'] ?? '') !== 'success') {
    throw new RuntimeException($response['message'] ?? 'Submission was not accepted.');
}
$reference = $response['data']['reference'];
// Persist $reference with your order, then poll GET /api/v1/ipe.php?reference=...

For Validation, change the URL to /api/v1/validation.php and the JSON body to [ 'nin' => '12345678901' ]. Authenticate and validate customer requests on your own server before charging your SMARTDATAS wallet.

Handle API errors

Error responses use {"status":"error","message":"..."}. Check the HTTP code and the response body. The envelope's status reports the API request outcome; data.state reports the processing outcome.

After a timeout or unclear POST response, check submission history before retrying. A request may have reached SMARTDATAS and been billed even if your website did not receive its response.

You can revoke a key immediately from Developer API Keys. Generate a replacement and update your website's server configuration when rotating keys.