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-keyheader (see Authentication).
2. Getting started
2.1 Onboarding
- Your organization must be registered and approved on the DL4ALL portal.
- Sign in to the portal as your organization and open Dashboard → API Settings.
- Click Generate API Token. You'll get a key that looks like:
dl4all_live_3f9a1c4e8b7d6520fce1ab93d4756082b1c0e9f2a3d4b5c6... - 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 returns401("Invalid API key").
4. Endpoints
| Method & path | Purpose | Rate limit |
|---|---|---|
POST /partner/trainings | Submit a single training | 60 requests / minute |
POST /partner/trainings/bulk | Submit many trainings in one call | 10 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
| Field | Type | Notes |
|---|---|---|
trainingTitle | string | Non‑empty. |
trainingDescription | string | Non‑empty. |
ndlfCompetence | string[] | Non‑empty array, e.g. ["Digital Literacy"]. |
trainingMethod | string[] | Non‑empty array, e.g. ["Physical"]. |
maleParticipants | string | A number sent as a string, e.g. "120". |
femaleParticipants | string | A number sent as a string, e.g. "100". |
state | string | One of the canonical values in Appendix A. See Data conventions. |
lga | string | The Local Government Area for the chosen state. |
Optional fields
| Field | Type | Notes |
|---|---|---|
externalReference | string | Your unique ID for the training. Idempotency key — see §7. Strongly recommended. |
proficiencyLevel | string[] | e.g. ["Beginner","Intermediate"]. |
targetGroup | string[] | e.g. ["Students","Professionals"]. |
deliveryLanguage | string[] | e.g. ["English","Hausa"]. |
trainerName | string | |
partneringOrganization | string | |
platformUsed | string | e.g. "Zoom". |
trainingHours | integer ≥ 0 | |
numSessions | integer ≥ 0 | |
areaType | string[] | e.g. ["Urban","Rural"]. |
venueType | string | e.g. "Online". |
certificateIssued | boolean | |
assessmentAdministered | boolean | |
averageScore | integer ≥ 0 | |
completionRate | integer ≥ 0 | Percentage, e.g. 90. |
postTrainingSupport | string[] | |
ageRange | string[] | e.g. ["18-35","36-50"]. |
physicalDisability | integer ≥ 0 | Participant count. |
visualImpairment | integer ≥ 0 | |
hearingImpairment | integer ≥ 0 | |
intellectualDisability | integer ≥ 0 | |
psychosocialCondition | integer ≥ 0 | |
totalDisability | integer ≥ 0 | |
accessibilityProvided | string[] | e.g. ["Ramp","Sign language interpreter"]. |
assistiveTechnology | string | |
estimatedTotalCost | integer ≥ 0 | In Naira. |
estimatedParticipantCost | integer ≥ 0 | In Naira. |
ward | string | |
gps | string | "lat,lng", e.g. "10.5105,7.4165". |
trainingStartdate | string (date) | ISO 8601 YYYY-MM-DD — see Data conventions. |
trainingEnddate | string (date) | ISO 8601 YYYY-MM-DD. |
noOfDays | integer ≥ 0 | |
verificationContact | string | Phone, 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
externalReferenceyou've already used (for your organization), the API returns409 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)"
}
}
| Status | Meaning | How to fix |
|---|---|---|
| 401 Unauthorized | Missing 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 Conflict | Duplicate externalReference — "Training already submitted". | The training already exists; don't resubmit. Use a new externalReference for a genuinely new training. |
| 422 Unprocessable Entity | Validation 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 Requests | Rate 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
| Endpoint | Limit |
|---|---|
POST /partner/trainings | 60 requests / minute |
POST /partner/trainings/bulk | 10 requests / minute |
Exceeding a limit returns 429 Too Many Requests. To stay within limits:
- Pace your requests (e.g. for large backfills, prefer
bulkover 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
externalReferencemakes 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
| Date | Change |
|---|---|
| 2026-06-30 | Initial 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.
| State | Alias |
|---|---|
| Abia | abia |
| Adamawa | adamawa |
| Akwa Ibom | akwa_ibom |
| Anambra | anambra |
| Bauchi | bauchi |
| Bayelsa | bayelsa |
| Benue | benue |
| Borno | borno |
| Cross River | cross_river |
| Delta | delta |
| Ebonyi | ebonyi |
| Edo | edo |
| Ekiti | ekiti |
| Enugu | enugu |
| Gombe | gombe |
| Imo | imo |
| Jigawa | jigawa |
| Kaduna | kaduna |
| Kano | kano |
| Katsina | katsina |
| Kebbi | kebbi |
| Kogi | kogi |
| Kwara | kwara |
| Lagos | lagos |
| Nasarawa | nasarawa |
| Niger | niger |
| Ogun | ogun |
| Ondo | ondo |
| Osun | osun |
| Oyo | oyo |
| Plateau | plateau |
| Rivers | rivers |
| Sokoto | sokoto |
| Taraba | taraba |
| Yobe | yobe |
| Zamfara | zamfara |
| FCT | abuja |
Questions or a key issue? Contact the DL4ALL team through the portal.