Asanya Referral Engine API Documentation

1. Overview & 3-Step Lifecycle

Asanya connects to your business via high-performance REST API handshakes. When your partners (Relationship Officers) invite employers, the entire lifecycle is tracked through three distinct milestones:

Step 1

Digital Name Tag

Partner shares link ?ref=ASN-XXXXXX. Your platform captures and tags the employer.

Step 2

Milestone 1: KYC Handshake

When the employer finishes CAC/TIN verification, you trigger POST /activation.

Step 3

Milestone 2: Employee Activity

When the employer onboards staff for verification, you fire activity pings to boost partner score.

2. Authentication & Headers

Authenticate all HTTP requests by including your secret API key as a Bearer token in the Authorization header. You can locate your secret key in Dashboard $\rightarrow$ API & Webhooks.

HTTP Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer asn_sec_live_9a8b7c6d5e4f3a2b1c0d

3. Capturing & Persisting Referral Links

When an employer arrives on Surevetted with ?ref=ASN-R05SFG, store the referral code in an HTTP-only Cookie for 30 days. When the user registers, attach this code to their account.

A. Surevetted Middleware (Capture to Cookie)

app/Http/Middleware/CaptureAsanyaReferral.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cookie;

class CaptureAsanyaReferral
{
    public function handle(Request $request, Closure $next)
    {
        if ($request->filled('ref')) {
            $code = strtoupper(trim($request->query('ref')));
            // Persist referral attribution in cookie for 30 days
            Cookie::queue('asanya_ref_code', $code, 60 * 24 * 30);
        }

        return $next($request);
    }
}

B. Surevetted Registration Controller (Save to DB)

app/Http/Controllers/Auth/RegisterController.php

$referralCode = $request->input('ref') ?? Cookie::get('asanya_ref_code');

$employer = Employer::create([
    'company_name'  => $request->company_name,
    'email'         => $request->email,
    'rc_number'     => $request->rc_number,
    'referral_code' => $referralCode, // Stores 'ASN-R05SFG'
]);

4. Validate Referral Code

Optional Form Validation

Verify if a partner referral code exists and is currently in active standing before submitting registration forms.

POST /api/v1/referrals/validate

Request Body (JSON)

Field	Type	Status	Description
referral_code	string	Required	The 6-character partner code prefixed with `ASN-` (e.g. `ASN-R05SFG`).

Sample Request Payload

{
  "referral_code": "ASN-R05SFG"
}

200 OK — Verified

{
  "valid": true,
  "code": "ASN-R05SFG",
  "cro_name": "Scott Crayton",
  "cro_email": "scottcrayton5545@gmail.com",
  "tenant_name": "Surevetted",
  "message": "Referral code verified successfully."
}

5. Record Referred User Signup

Signup Attributed

Register a newly created employer account under the referring partner in Asanya's audit ledger.

POST /api/v1/referrals/signup

Sample Signup Request Payload

{
  "referral_code": "ASN-R05SFG",
  "entity_name": "Dangote Sugar Refinery Plc",
  "entity_email": "hr@dangotesugar.com",
  "entity_type": "employer",
  "rc_number": "RC-1092841",
  "sector": "Fast-Moving Consumer Goods (FMCG)"
}

⭐ Key Milestone 1

6. Employer KYC Verification Handshake

POST /api/v1/referrals/activation

Trigger this endpoint when the employer successfully uploads their CAC registration, TIN, and identity documents on Surevetted and is marked as verified.

POST /api/v1/referrals/activation

Field	Type	Status	Description
referral_code	string	Required	The partner code attached to the employer (e.g. `ASN-R05SFG`).
entity_name	string	Required	Official corporate business name of the verified employer.
entity_email	email	Required	Official contact email address of the employer.
rc_number	string	Optional	Official CAC Registration RC or BN number.
event_type	string	Required	Set strictly to `"kyc_completed"`.

Milestone 1 Payload

{
  "referral_code": "ASN-R05SFG",
  "entity_name": "Dangote Sugar Refinery Plc",
  "entity_email": "hr@dangotesugar.com",
  "rc_number": "RC-1092841",
  "entity_type": "employer",
  "event_type": "kyc_completed"
}

200 OK — Qualified Activation Logged

{
  "success": true,
  "attribution_id": 42,
  "entity_name": "Dangote Sugar Refinery Plc",
  "status": "qualified_activation",
  "qualified_at": "2026-09-01T02:30:00+01:00",
  "message": "Qualified activation successfully logged and timestamped."
}

⭐ Key Milestone 2

7. Employee Listing & Activity Scoring

Live Partner Scoring

Trigger this endpoint when the employer adds employees or requests credential checks on Surevetted. This dynamically increases the partner's activity stream, leaderboard score, and reward eligibility.

POST /api/v1/referrals/activation

Milestone 2 Payload

{
  "referral_code": "ASN-R05SFG",
  "entity_name": "Dangote Sugar Refinery Plc",
  "entity_email": "hr@dangotesugar.com",
  "rc_number": "RC-1092841",
  "event_type": "employee_listing",
  "employees_count": 25,
  "description": "Onboarded 25 corporate staff for educational background verification"
}

8. Recommended Async Queued Worker

To maintain instantaneous response times for Surevetted's employers, dispatch all Asanya API notifications via a Laravel Queued Job.

app/Jobs/NotifyAsanyaMilestone.php

namespace App\Jobs;

use App\Models\Employer;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class NotifyAsanyaMilestone implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        public Employer $employer,
        public string $eventType,
        public array $extraData = []
    ) {}

    public function handle(): void
    {
        if (empty($this->employer->referral_code)) {
            return;
        }

        $payload = array_merge([
            'referral_code' => $this->employer->referral_code,
            'entity_name'   => $this->employer->company_name,
            'entity_email'  => $this->employer->email,
            'rc_number'     => $this->employer->rc_number,
            'entity_type'   => 'employer',
            'event_type'    => $this->eventType,
        ], $this->extraData);

        try {
            $response = Http::timeout(10)
                ->withToken(config('services.asanya.secret_key'))
                ->post(config('services.asanya.base_url') . '/api/v1/referrals/activation', $payload);

            if ($response->successful()) {
                Log::info("Asanya Milestone [{$this->eventType}] logged for: {$this->employer->company_name}");
            }
        } catch (\Exception $e) {
            Log::error("Asanya Webhook Error: " . $e->getMessage());
        }
    }
}

Triggering Anywhere in Surevetted Controllers:

NotifyAsanyaMilestone::dispatch($employer, 'kyc_completed');
NotifyAsanyaMilestone::dispatch($employer, 'employee_listing', ['employees_count' => 25]);

9. Reverse Webhook Security

When Asanya pushes real-time partner event notifications to your platform, every request is signed using an HMAC-SHA256 signature in the X-Asanya-Signature header.

Signature Verification Middleware

$signature = $request->header('X-Asanya-Signature');
$expected = hash_hmac('sha256', $request->getContent(), config('services.asanya.webhook_secret'));

if (!hash_equals($expected, $signature)) {
    abort(403, 'Invalid HMAC Signature.');
}

10. HTTP Response Status Reference

Code	Status	Description
200 OK	Success	Milestone, KYC completion, or activity event logged and timestamped successfully.
201 Created	Created	New prospect referral attribution created.
400 Bad Request	Invalid Partner State	Referral code is inactive or business tenant account is pending verification.
401 Unauthorized	Auth Failed	Missing or invalid Bearer secret API token in Authorization header.
404 Not Found	Not Found	Referral code does not exist in the Asanya registry.
422 Unprocessable	Validation Error	Required JSON payload field missing (e.g. `referral_code` or `event_type`).

Developer Integration Documentation

1. Overview & 3-Step Lifecycle

Digital Name Tag

Milestone 1: KYC Handshake

Milestone 2: Employee Activity

2. Authentication & Headers

3. Capturing & Persisting Referral Links

A. Surevetted Middleware (Capture to Cookie)

B. Surevetted Registration Controller (Save to DB)

4. Validate Referral Code

Request Body (JSON)

5. Record Referred User Signup

6. Employer KYC Verification Handshake

7. Employee Listing & Activity Scoring

8. Recommended Async Queued Worker

9. Reverse Webhook Security

10. HTTP Response Status Reference