KIDUART school ERP
Developer reference

The KIDUART REST API, without the guesswork

Versioned endpoints under a stable base path, scoped API keys instead of a shared staff login, signature-verified provider webhooks and a predictable error contract. This page is the overview your IT team needs before asking for access; the full endpoint reference is issued with your key.

Request API access Browse integrations
curl -X GET \
  'https://api.kiduart.com/api/v1/students?classId=8A' \
  -H 'x-api-key: kd_live_•••••••••' \
  -H 'Content-Type: application/json'

{
  "success": true,
  "data": [ { "id": "stu_...", "class": "8", "section": "A" } ],
  "meta": { "page": 1, "limit": 50, "total": 42 }
}

Scoped API keys

Keys are issued per integration with named scopes, can be limited by IP, and can be rotated or revoked without touching a single staff account.

Tenant boundary first

Every request is resolved inside your school before any query runs, so a key cannot reach another school's records even by accident.

Rate limited and logged

Calls are rate limited under fair use and recorded, so unusual traffic is visible and a stuck job is diagnosable rather than mysterious.

Authentication

Two ways in, and they are not interchangeable

Machine-to-machine integrations use an API key issued to your school. Anything acting on behalf of a signed-in person uses that person's session token, so their role decides what they can see. Do not build a server integration on a staff login it breaks the moment that person leaves.

API key server to server

Issued per integration with named scopes. Send it as a header on every request, keep it on your server, and rotate it when the person who owns the integration changes.

x-api-key: kd_live_•••••••••
Content-Type: application/json

Bearer token on behalf of a user

Used by the web and mobile apps after sign-in. Access tokens are short-lived and refreshed, and every call is still filtered by that user's role and school.

Authorization: Bearer <access_token>
Content-Type: application/json

All traffic is HTTPS only. Keys are shown once when issued and stored hashed on our side, so if it is lost we reissue rather than retrieve which is exactly what you want from anything that can read student data.

Endpoint groups

What your developer can reach, by scope

Representative endpoints for the integrations schools ask for most. Paths, payloads and the full field list arrive with your key as a reference document, so your developer builds against the current contract rather than a marketing page that drifted.

Read and maintain the student record your website, admission funnel or reporting warehouse needs to stay in step with the office.

  • GET/api/v1/students

    List students with class, section and status filters.

    Scope required: students:read

  • GET/api/v1/students/{id}

    Fetch one student with the fields your key is allowed to see.

    Scope required: students:read

  • POST/api/v1/students

    Create a student record from an external admission form.

    Scope required: students:write

  • PATCH/api/v1/students/{id}

    Update contact or guardian details without touching academic history.

    Scope required: students:write

Pagination and filtering

List endpoints are paged. Pass page and limit, read the totals from meta, and filter with the query parameters documented for that resource. Large exports are queued rather than streamed, so a full-year report never times out mid-request.

Rate limits

Requests are rate limited per key under a fair-use policy, with stricter limits on authentication routes. A limited response returns 429 with headers telling you when to retry. If a genuine workload needs more headroom, tell us the pattern and we will size it with you rather than making you discover the ceiling in production.

Webhooks

Provider callbacks we verify and act on

Incoming webhooks are how a payment gets confirmed and a message gets marked delivered. Each one is signature-verified against the provider's secret before anything is written, and a repeated callback updates the existing record instead of duplicating it.

  • Razorpay

    payment.captured, payment.failed, refund.processed, order.paid, dispute.created

  • Stripe

    payment_intent.succeeded, charge.failed, charge.refunded

  • Twilio and MSG91

    SMS delivery and failure callbacks

  • SendGrid and Mailgun

    delivered, bounced, complaint

  • WhatsApp Business

    message status callbacks and inbound message events

Not available yet: subscribing your own endpoint to KIDUART events. Outbound webhooks are on the roadmap. Until they ship, poll the relevant endpoint on a schedule that suits your workload.

Errors

One error shape, every endpoint

Failures come back in the same envelope as successes, so your client handles one shape rather than guessing per route.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "admissionNumber is already in use",
    "field": "admissionNumber"
  }
}
400
The request body or query failed validation. The response names the field.
401
Missing, expired or revoked credentials.
403
Authenticated, but the key's scope does not cover this action.
404
The record does not exist, or does not belong to your school.
409
The action conflicts with the current state, such as a duplicate receipt.
429
Rate limit hit. Back off and retry using the returned headers.
500
Something failed on our side. It is logged with a reference you can quote to support.

Getting access

Developer questions, answered

How do we get an API key?

Ask your onboarding contact or write to support with the use case and what the integration needs to read or write. Keys are issued per integration with only the scopes that use case requires, so a reporting job never gets write access.

Can one key reach another school's data?

No. A key is issued against your school and every query is resolved inside that boundary. Multi-campus groups get keys scoped to the campuses they are meant to cover.

Is there a public sandbox?

There is no open sandbox you can self-register for. During onboarding you test against your own instance with non-production data before go-live, which is closer to your real configuration than a shared demo environment would be.

Can our systems subscribe to KIDUART events?

Not yet. We handle incoming webhooks from payment and messaging providers today; outbound webhooks your systems can subscribe to are on the roadmap. Until then, poll the relevant endpoint on a schedule.

What happens if a key leaks?

Revoke it and issue a new one. Because keys are managed objects with their own scopes and can be limited by IP, a leaked key is a contained incident rather than a shared staff password loose in the wild.

Building something specific? support@kiduart.com tell us the use case and the scopes you think you need.
Live demo

Bring your developer to the demo

Walk through the scopes your integration needs, what your key will be allowed to touch, and how it gets rotated when your team changes.

Request a Demo Contact Sales

  • 30-minute walkthrough

    Booked around your school hours

  • Run on your own data

    Your fee heads, classes and staff roles

  • No card, no lock-in

    Nothing is charged to see the product