Partner Integration API

Submit your organization's training data into the National Digital Literacy Portal (DL4ALL) programmatically.

This guide is a step-by-step walkthrough for integrating your systems with the API.


1. Overview

The Partner Integration API lets an approved organization push training records into DL4ALL from its own systems. Every submission is logged, then approved by an administrator, before it is pushed to the national dashboards — the same pipeline as a record created on the portal.

  • Format: REST, JSON only. Every request and response is JSON.
  • Transport: HTTPS only. Plain HTTP is not supported.
  • Base URL:
    https://api.newdl4all.nitda.gov.ng/api/v1
    
  • Authentication: an organization API key sent in the x-api-key header (see Authentication).

2. Getting started

2.1 Onboarding

  1. Your organization must be registered and approved on the DL4ALL portal.
  2. Sign in to the portal as your organization and open Dashboard → API Settings.
  3. Click Generate API Token. You'll get a key that looks like:
    dl4all_live_3f9a1c4e8b7d6520fce1ab93d4756082b1c0e9f2a3d4b5c6...
    
  4. Copy and store it securely. Treat it like a password (see Authentication).

From the same screen you can regenerate the key (the old one stops working immediately) or revoke it, and you can view your API Logs and usage stats.

2.2 Your first submission in 5 minutes

Once you have a key, this single curl creates a training. Replace YOUR_API_KEY and run it:

curl -X POST https://api.newdl4all.nitda.gov.ng/api/v1/partner/trainings \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "PARTNER-2026-0001",
    "trainingTitle": "Basic Digital Literacy",
    "trainingDescription": "Intro to computers and the internet",
    "ndlfCompetence": ["Digital Literacy"],
    "trainingMethod": ["Physical"],
    "maleParticipants": "120",
    "femaleParticipants": "100",
    "state": "Kaduna",
    "lga": "Kaduna North",
    "trainingStartdate": "2026-01-15",
    "trainingEnddate": "2026-01-20"
  }'

A 201 response with "success": true means it worked. You'll see the new record (with its DL4ALL trainingId) on your portal dashboard, awaiting admin approval before it appears on the national dashboard.


3. Authentication

Every request must include your organization API key in the x-api-key header:

x-api-key: dl4all_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rules:

  • The key is per‑organization. Every submission made with it is attributed to your organization.
  • Keep it secret. Never commit it to source control, embed it in mobile/browser apps, or expose it client‑side. Use it only from your server.
  • If a key is compromised, regenerate it from API Settings — the old key stops working instantly.
  • A missing key returns 401 ("API key is required"). An invalid or revoked key returns 401 ("Invalid API key").

4. Endpoints

Method & pathPurposeRate limit
POST /partner/trainingsSubmit a single training60 requests / minute
POST /partner/trainings/bulkSubmit many trainings in one call10 requests / minute

Both require the x-api-key header. Full URLs:

POST https://api.newdl4all.nitda.gov.ng/api/v1/partner/trainings
POST https://api.newdl4all.nitda.gov.ng/api/v1/partner/trainings/bulk

The bulk body wraps an array under trainings:

{ "trainings": [ { /* training 1 */ }, { /* training 2 */ } ] }

Each item in trainings uses the exact same schema as a single submission.


5. Request schema

Each training object has the fields below. Only these fields are accepted — sending any field not listed here causes a 422 validation error (the API rejects unknown fields).

Required fields

FieldTypeNotes
trainingTitlestringNon‑empty.
trainingDescriptionstringNon‑empty.
ndlfCompetencestring[]Non‑empty array, e.g. ["Digital Literacy"].
trainingMethodstring[]Non‑empty array, e.g. ["Physical"].
maleParticipantsstringA number sent as a string, e.g. "120".
femaleParticipantsstringA number sent as a string, e.g. "100".
statestringOne of the canonical values in Appendix A. See Data conventions.
lgastringThe Local Government Area for the chosen state.

Optional fields

FieldTypeNotes
externalReferencestringYour unique ID for the training. Idempotency key — see §7. Strongly recommended.
proficiencyLevelstring[]e.g. ["Beginner","Intermediate"].
targetGroupstring[]e.g. ["Students","Professionals"].
deliveryLanguagestring[]e.g. ["English","Hausa"].
trainerNamestring
partneringOrganizationstring
platformUsedstringe.g. "Zoom".
trainingHoursinteger ≥ 0
numSessionsinteger ≥ 0
areaTypestring[]e.g. ["Urban","Rural"].
venueTypestringe.g. "Online".
certificateIssuedboolean
assessmentAdministeredboolean
averageScoreinteger ≥ 0
completionRateinteger ≥ 0Percentage, e.g. 90.
postTrainingSupportstring[]
ageRangestring[]e.g. ["18-35","36-50"].
physicalDisabilityinteger ≥ 0Participant count.
visualImpairmentinteger ≥ 0
hearingImpairmentinteger ≥ 0
intellectualDisabilityinteger ≥ 0
psychosocialConditioninteger ≥ 0
totalDisabilityinteger ≥ 0
accessibilityProvidedstring[]e.g. ["Ramp","Sign language interpreter"].
assistiveTechnologystring
estimatedTotalCostinteger ≥ 0In Naira.
estimatedParticipantCostinteger ≥ 0In Naira.
wardstring
gpsstring"lat,lng", e.g. "10.5105,7.4165".
trainingStartdatestring (date)ISO 8601 YYYY-MM-DD — see Data conventions.
trainingEnddatestring (date)ISO 8601 YYYY-MM-DD.
noOfDaysinteger ≥ 0
verificationContactstringPhone, e.g. "08012345678".

No file uploads. Evidence fields (attendance sheets, photos, summary reports, certificates) are not accepted by the API — it is JSON‑only. Upload those on the portal if needed.


6. Data conventions

To keep the national dashboards consistent across every partner, follow these conventions exactly.

States — use these exact values

Send state as one of the 37 exact strings listed in Appendix A (the 36 states + the Federal Capital Territory). The Federal Capital Territory must be sent as "FCT" — not "Federal Capital Territory" or "Abuja".

Mismatched spellings fragment the dashboards even though the request may still succeed, so please match the appendix exactly. Each state also has a short alias (listed in the appendix) that the portal uses internally.

LGAs

Send lga as the official Local Government Area name for the chosen state, using standard spelling (e.g. for "state": "Kaduna", "lga": "Kaduna North").

Dates

trainingStartdate and trainingEnddate must be ISO 8601 date strings, YYYY-MM-DD:

"trainingStartdate": "2026-01-15"

A malformed date is rejected with a 422. Omit the field entirely if you don't have the value — do not send an empty string or a placeholder.

Numbers as strings

maleParticipants and femaleParticipants are strings ("120"), not JSON numbers. All other counts (disability figures, hours, costs, etc.) are JSON integers.


7. Idempotency (externalReference)

externalReference is your own unique identifier for a training (e.g. "PARTNER-2026-0001"). It is optional, but strongly recommended — it's the only protection against accidentally creating duplicates if a request is retried.

  • If you submit a training whose externalReference you've already used (for your organization), the API returns 409 Conflict ("Training already submitted") and does not create a second record.
  • Always set it, and keep it stable per training, so safe retries don't create duplicates.

8. Responses & errors

All responses are JSON with a top‑level success boolean.

201 — Single submission success

{
  "success": true,
  "message": "Training submitted successfully and awaiting approval",
  "data": {
    "id": "…",
    "trainingId": "DL4ALL-…",
    "externalReference": "PARTNER-2026-0001",
    "trainingTitle": "Basic Digital Literacy",
    "approvalStatus": "PENDING",
    "submissionChannel": "API",
    "…": "…"
  }
}

approvalStatus starts as PENDING — the training is reviewed and approved by an administrator before it appears on the national dashboards.

201 — Bulk submission result

Bulk processes each item independently and reports per‑item outcomes — the overall call still returns success even if some items failed:

{
  "success": true,
  "data": {
    "totalReceived": 2,
    "successful": 1,
    "failed": 1,
    "results": [
      { "externalReference": "PARTNER-2026-0001", "status": "SUCCESS", "trainingId": "DL4ALL-…" },
      { "externalReference": "PARTNER-2026-0002", "status": "FAILED", "message": "Training already submitted" }
    ]
  }
}

Always inspect results to see which items succeeded.

Error responses

Every error uses this shape:

{
  "success": false,
  "error": {
    "code": 0,
    "message": "Human-readable reason",
    "details": "… (extra info / validation list, when available)"
  }
}
StatusMeaningHow to fix
401 UnauthorizedMissing key ("API key is required") or invalid/revoked key ("Invalid API key").Send a valid x-api-key. Regenerate the key in API Settings if needed.
409 ConflictDuplicate externalReference — "Training already submitted".The training already exists; don't resubmit. Use a new externalReference for a genuinely new training.
422 Unprocessable EntityValidation failed — missing required field, wrong type, malformed date, or an unknown field.Read error.details for the specific field(s) and correct the payload.
429 Too Many RequestsRate limit exceeded (60/min single, 10/min bulk).Slow down and retry after a short delay — see §9.

Example 422 (validation)

Request missing state and with a bad date:

{
  "success": false,
  "error": {
    "code": 422,
    "message": "Validation error",
    "details": [
      { "field": "state", "message": "state should not be empty" },
      { "field": "trainingStartdate", "message": "trainingStartdate must be a valid ISO 8601 date string" }
    ]
  }
}

9. Rate limiting

EndpointLimit
POST /partner/trainings60 requests / minute
POST /partner/trainings/bulk10 requests / minute

Exceeding a limit returns 429 Too Many Requests. To stay within limits:

  • Pace your requests (e.g. for large backfills, prefer bulk over many single calls).
  • On a 429, retry with exponential backoff (wait, then double the wait on each retry) rather than immediately retrying in a tight loop.
  • Because externalReference makes retries idempotent, a backoff retry is safe — it won't create duplicates.

10. Full worked examples

Single — success

curl -X POST https://api.newdl4all.nitda.gov.ng/api/v1/partner/trainings \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "PARTNER-2026-0042",
    "trainingTitle": "Advanced Spreadsheets",
    "trainingDescription": "Data analysis with spreadsheets",
    "ndlfCompetence": ["Digital Literacy", "Data Skills"],
    "proficiencyLevel": ["Intermediate"],
    "trainingMethod": ["Physical"],
    "deliveryLanguage": ["English", "Hausa"],
    "maleParticipants": "80",
    "femaleParticipants": "95",
    "trainingHours": 18,
    "numSessions": 6,
    "certificateIssued": true,
    "completionRate": 92,
    "state": "FCT",
    "lga": "Abuja Municipal",
    "trainingStartdate": "2026-02-03",
    "trainingEnddate": "2026-02-08",
    "noOfDays": 5,
    "verificationContact": "08012345678"
  }'

Bulk — two items

curl -X POST https://api.newdl4all.nitda.gov.ng/api/v1/partner/trainings/bulk \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trainings": [
      {
        "externalReference": "PARTNER-2026-0050",
        "trainingTitle": "Intro to the Internet",
        "trainingDescription": "Browsing, email and online safety",
        "ndlfCompetence": ["Digital Literacy"],
        "trainingMethod": ["Physical"],
        "maleParticipants": "60",
        "femaleParticipants": "70",
        "state": "Lagos",
        "lga": "Ikeja"
      },
      {
        "externalReference": "PARTNER-2026-0051",
        "trainingTitle": "Mobile Money Basics",
        "trainingDescription": "Using mobile financial services safely",
        "ndlfCompetence": ["Digital Literacy"],
        "trainingMethod": ["Virtual"],
        "maleParticipants": "40",
        "femaleParticipants": "55",
        "state": "Kano",
        "lga": "Nassarawa"
      }
    ]
  }'

Failing example — missing required field (422)

curl -X POST https://api.newdl4all.nitda.gov.ng/api/v1/partner/trainings \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trainingTitle": "Incomplete Submission",
    "trainingDescription": "Missing required fields",
    "ndlfCompetence": ["Digital Literacy"],
    "trainingMethod": ["Physical"],
    "maleParticipants": "10",
    "femaleParticipants": "10",
    "state": "Kano"
  }'

Returns 422 because lga is required:

{
  "success": false,
  "error": {
    "code": 422,
    "message": "Validation error",
    "details": [
      { "field": "lga", "message": "lga should not be empty" }
    ]
  }
}

11. Changelog

DateChange
2026-06-30Initial release of the Partner Integration API: single + bulk training submission, API‑key auth, idempotency via externalReference, rate limiting.

Appendix A — States & aliases

Send state using exactly the value in the State column (37 states; the Federal Capital Territory is FCT). The Alias is the short identifier the portal uses internally for each state — provided for reference.

StateAlias
Abiaabia
Adamawaadamawa
Akwa Ibomakwa_ibom
Anambraanambra
Bauchibauchi
Bayelsabayelsa
Benuebenue
Bornoborno
Cross Rivercross_river
Deltadelta
Ebonyiebonyi
Edoedo
Ekitiekiti
Enuguenugu
Gombegombe
Imoimo
Jigawajigawa
Kadunakaduna
Kanokano
Katsinakatsina
Kebbikebbi
Kogikogi
Kwarakwara
Lagoslagos
Nasarawanasarawa
Nigerniger
Ogunogun
Ondoondo
Osunosun
Oyooyo
Plateauplateau
Riversrivers
Sokotosokoto
Tarabataraba
Yobeyobe
Zamfarazamfara
FCTabuja

Questions or a key issue? Contact the DL4ALL team through the portal.