API Documentation

Authentication

Secure every request with Bearer tokens

Generate API keys in Settings → API Access. Each school receives a live key and secret. Include both credentials on every request.

GET https://api.fundani.africa/v1/courses
Authorization: Bearer sk_live_your_api_key
X-Fundani-Secret: sh_live_your_secret_key

Invalid or missing credentials return 401 Unauthorized.

Filtering

Universal query parameters

Most endpoints accept rich filters to mirror dashboard search. Combine parameters freely to build advanced queries.

Parameter	Type	Description	Example
`from`	date	Start date for results	`2025-01-01`
`to`	date	End date for results	`2025-03-31`
`courseId`	string	Filter results by a specific course	`course_abc123`
`status`	string	Filter by lifecycle status (PENDING, ACCEPTED, REJECTED, ENROLLED)	`status=ACCEPTED`
`province`	string	Filter by student province	`Gauteng`
`sort`	string	Field and direction to sort by (e.g. createdAt:desc)	`createdAt:desc`
`page`	number	Page number for pagination	`1`
`limit`	number	Results per page (max 100)	`20`

Applications

Track every applicant, understand momentum, and segment by course or region.

GET/api/v1/applications

List all applications with optional filters for status and geography.

Supported filters

courseId
status
province
from
to
sort
page
limit

Example request

GET /api/v1/applications?status=PENDING&from=2025-01-01&to=2025-03-01&province=Western%20Cape
Authorization: Bearer sk_test_123

Example response

{
  "data": [
    {
      "id": "app_123",
      "studentName": "Thando M.",
      "courseId": "course_45",
      "status": "PENDING",
      "province": "Western Cape",
      "submittedAt": "2025-02-01T09:12:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "total": 22
  }
}

GET/api/v1/applications/summary

Summarises total applications grouped by status for quick reporting.

Example response

{
  "pending": 22,
  "accepted": 45,
  "rejected": 8,
  "withdrawn": 2
}

GET/api/v1/applications/trends

Returns application counts grouped by week or month.

Supported filters

groupBy=month | week

Example response

[
  { "period": "2025-01", "count": 15 },
  { "period": "2025-02", "count": 32 },
  { "period": "2025-03", "count": 41 }
]

GET/api/v1/applications/top-courses

Returns the top 10 courses by application count.

Example response

[
  { "courseName": "Diploma in IT", "applications": 120 },
  { "courseName": "Business Management", "applications": 95 }
]

GET/api/v1/applications/geo-distribution

Breakdown of applications per province or region.

Example response

{
  "Gauteng": 125,
  "Western Cape": 78,
  "KwaZulu-Natal": 52
}

Enrollments

Measure conversion and retention from initial application to enrolled learners.

GET/api/v1/enrollments

List enrolments with course, status, and date filters.

Supported filters

courseId
status
from
to

Example response

[
  {
    "id": "enr_120",
    "studentName": "Lerato D.",
    "courseName": "Software Development",
    "status": "ENROLLED",
    "enrolledAt": "2025-02-20T14:00:00Z"
  }
]

GET/api/v1/enrollments/progression

Returns conversion from applications to enrolments.

Example response

{
  "applications": 420,
  "enrollments": 260,
  "conversionRate": 61.9
}

GET/api/v1/enrollments/retention

Monthly enrolment retention statistics.

Example response

[
  { "month": "2025-01", "retentionRate": 75 },
  { "month": "2025-02", "retentionRate": 68 }
]

Ads & Campaigns

Monitor paid campaign performance and credit usage programmatically.

GET/api/v1/ads/performance

Returns impressions, clicks, and conversions for all campaigns.

Example response

[
  {
    "adId": "ad_01",
    "title": "Apply Now - IT Courses",
    "impressions": 4800,
    "clicks": 600,
    "applications": 120
  }
]

GET/api/v1/ads/conversion-rate

Click-through and conversion rates per campaign.

Example response

[
  { "adId": "ad_01", "ctr": 12.5, "conversionRate": 20.0 }
]

GET/api/v1/ads/summary

Summarises ad credits and aggregate performance.

Example response

{
  "creditsUsed": 650,
  "creditsRemaining": 350,
  "totalImpressions": 12000,
  "totalClicks": 1800
}

Students

Build richer reporting on who is applying, which subjects they passed, and what they want to study.

GET/api/v1/students/demographics

Breakdown of applicants by age, gender, and province.

Example response

{
  "ageGroups": { "18-24": 62, "25-34": 28, "35+": 10 },
  "gender": { "female": 58, "male": 42 },
  "province": { "Gauteng": 50, "Western Cape": 30, "Other": 20 }
}

GET/api/v1/students/subjects

Top matric subjects among applicants.

Example response

[
  { "subject": "Mathematics", "count": 120 },
  { "subject": "Accounting", "count": 95 }
]

GET/api/v1/students/interests

Top study interests or faculties.

Example response

[
  { "interest": "Engineering", "applications": 80 },
  { "interest": "Health Sciences", "applications": 55 }
]

Financials

Stay on top of billing, ad credit usage, and payment history.

GET/api/v1/payments

Lists school payments with optional filters for status and type.

Supported filters

status
type
from
to

Example response

[
  {
    "id": "pay_123",
    "amount": 250,
    "type": "ad_credit",
    "status": "SUCCESS",
    "createdAt": "2025-02-03T12:00:00Z"
  }
]

GET/api/v1/ad-credits/usage

History of ad credit usage and remaining balance.

Example response

[
  { "date": "2025-02-01", "used": 60, "remaining": 940 },
  { "date": "2025-02-10", "used": 120, "remaining": 820 }
]

Audit Logs

Maintain compliance with immutable staff activity logs.

GET/api/v1/audit-logs

Returns a list of staff actions with optional filters.

Supported filters

eventType
from
to
userId

Example response

[
  {
    "user": "admin@college.ac.za",
    "action": "COURSE_CREATED",
    "timestamp": "2025-02-01T09:00:00Z"
  }
]

Metadata

Fetch lightweight metadata for dropdowns and internal references.

GET/api/v1/metadata/courses

Lightweight list of course IDs and names for dropdown population.

Example response

[
  { "id": "course_1", "name": "Diploma in Marketing" },
  { "id": "course_2", "name": "Advanced Software Engineering" }
]

GET/api/v1/metadata/faculties

Returns faculties/departments available to the school.

Example response

[
  { "id": "fac_1", "name": "Engineering" },
  { "id": "fac_2", "name": "Business & Management" }
]

Webhooks

Receive events in real time

Configure webhooks in the dashboard to receive enrolment and perfect match events. Retries use exponential backoff for up to 24 hours.

Event	Description
`student.accepted_enrollment`	Triggered when a student accepts an enrolment offer.
`application.match_found`	Triggered when a new application matches 100% of the course requirements.

student.accepted_enrollment

{
  "event": "student.accepted_enrollment",
  "data": {
    "studentId": "stu_56",
    "courseId": "course_3",
    "acceptedAt": "2025-02-20T15:30:00Z"
  }
}

application.match_found

{
  "event": "application.match_found",
  "data": {
    "studentId": "stu_88",
    "courseId": "course_10",
    "score": 100,
    "submittedAt": "2025-02-25T11:45:00Z"
  }
}

System

Inspect your API usage and the platform health status.

GET/api/v1/system/usage

Returns monthly API usage, remaining credits, and reset date.

Example response

{
  "requestsThisMonth": 1250,
  "remainingRequests": 750,
  "limit": 2000,
  "resetsOn": "2025-12-01T00:00:00Z"
}

GET/api/v1/system/status

Returns system health and remaining burst capacity.

Example response

{
  "status": "ok",
  "uptime": "99.98%",
  "rateLimit": {
    "limit": 60,
    "remaining": 59,
    "resetIn": 42
  }
}

Rate limiting

Understand quotas and burst protection

The Fundani API enforces both monthly and per-minute limits. Inspect headers on every response to track your remaining allowance.

Monthly limit

2,000 requests per billing cycle (resets on subscription renewal).

Per-minute limit

60 requests per minute for burst protection. Exceeding the limit returns 429.

Rate limit headers

X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1450
X-RateLimit-Reset: 1730419200

When limits are exceeded the API returns a 429 status with a descriptive error payload.

{
  "error": "Rate limit exceeded. Try again later."
}

Common response codes

200

Request succeeded and data returned.

201

Resource created successfully.

400

Validation error – check payload and retry.

401

Authentication failed – confirm API and secret keys.

429

Rate limit exceeded – wait before retrying.

500

Unexpected error – contact support if it persists.

Versioning

Stable versioned endpoints

All endpoints are prefixed with /api/v1/. Future breaking changes will ship under /api/v2/ to preserve backwards compatibility.

Support

Need help with your integration?

The Fundani team assists with onboarding, webhook testing, and sandbox verification so you can ship confidently.

Talk to support Request sandbox keys

Parameter

Type

Description

Example

from

date

Start date for results

2025-01-01

to

date

End date for results

2025-03-31

courseId

string

Filter results by a specific course

course_abc123

status

string

Filter by lifecycle status (PENDING, ACCEPTED, REJECTED, ENROLLED)

status=ACCEPTED

province

string

Filter by student province

Gauteng

sort

string

Field and direction to sort by (e.g. createdAt:desc)

createdAt:desc

page

number

Page number for pagination

1

limit

number

Results per page (max 100)

20

{ "data": [ { "id": "app_123", "studentName": "Thando M.", "courseId": "course_45", "status": "PENDING", "province": "Western Cape", "submittedAt": "2025-02-01T09:12:00Z" } ], "meta": { "page": 1, "total": 22 } }

Event

Description

student.accepted_enrollment

Triggered when a student accepts an enrolment offer.

application.match_found

Triggered when a new application matches 100% of the course requirements.

Build deeper integrations with our secure API

Secure every request with Bearer tokens

Universal query parameters

Applications

Enrollments

Ads & Campaigns

Students

Financials

Audit Logs

Metadata

Receive events in real time

System

Understand quotas and burst protection

Stable versioned endpoints

Need help with your integration?

Build deeper integrations with our secure API

Secure every request with Bearer tokens

Universal query parameters

Applications

Enrollments

Ads & Campaigns

Students

Financials

Audit Logs

Metadata

Receive events in real time

System

Understand quotas and burst protection

Stable versioned endpoints

Need help with your integration?