API Documentation

Overview

Base URL: /api/v1

Version: v1
Format: JSON request and response bodies
Protocol: HTTPS only in production
Authentication: Bearer API key on every request
Credits: each successful transcript store deducts 1 credit from the target campus balance

The store endpoint accepts structured transcript data directly. There is no PDF upload, OCR, or background job queue — storage is synchronous and the response includes the new transcript ID immediately.

Authentication

Include your organization API key on every request:

Authorization: Bearer incr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Optional header for integration tracking:

Content-Type: application/json
Accept: application/json
X-Source: YourSystemName

API keys are scoped to your organization. Each key can access campuses according to its configuration (default campus and/or campus mappings). Keys can be revoked at any time from the INCRIPT org portal.

Getting an API key

Organization administrators (org_admin or org_admin_full) can create keys in INCRIPT:

Log in to INCRIPT
Open API Keys in the sidebar (above Settings)
Click Generate New API Key
Copy the key when shown — it is displayed once only and cannot be retrieved later
Optionally configure a default campus or campus mappings for third-party identifier strings

Logged-in org admins can manage keys at /org/api-keys.

Treat API keys like passwords. Store them in a secrets manager. Never embed keys in client-side JavaScript or public repositories.

Campus routing (`campus_ref`)

INCRIPT tracks credits per campus. Most requests must resolve to a specific campus. Send campus_ref in the JSON body (POST) or as a query parameter (GET).

Resolution order:

Campus mapping — if your system uses its own campus identifier, map it in INCRIPT → API Keys → Campus Mappings
Direct INCRIPT campus ID — send the numeric campus_id from GET /campuses as campus_ref (recommended for most integrations)
Default campus — if the API key has a default campus configured and no campus_ref is sent

GET /campuses does not require campus_ref — it lists all campuses for your organization.

Response format

Successful responses:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": "Human-readable error message",
  "credits_remaining": 0
}

Extra fields (such as credits_remaining) may appear on certain error responses.

HTTP status codes

Code	Meaning
`200`	Success
`400`	Validation error, missing field, or unresolved `campus_ref`
`401`	Missing, invalid, revoked, or expired API key
`402`	Insufficient credits on the target campus
`404`	Transcript not found (status endpoint)
`405`	Wrong HTTP method
`500`	Unexpected server error

Endpoints

GET /campuses

List all active campuses for your organization with current credit balances. Use this during integration setup to discover campus_id values.

Authentication: required. campus_ref: not required.

Example request

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "/api/v1/campuses"

Example response

{
  "success": true,
  "data": {
    "campuses": [
      {
        "campus_id": 12,
        "campus_name": "Main Campus",
        "campus_code": "MAIN",
        "campus_type": "Main Campus",
        "credits_remaining": 250
      }
    ],
    "note": "Use campus_id as campus_ref when storing transcripts..."
  }
}

GET /credits/balance?campus_ref={campus_id}

Check credit balance for a campus before storing transcripts.

campus_ref: required (query string or JSON body).

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "/api/v1/credits/balance?campus_ref=12"

{
  "success": true,
  "data": {
    "org_id": 5,
    "campus_id": 12,
    "credits_remaining": 250,
    "is_sufficient": true,
    "warning": null
  }
}

When balance is low (6–5 credits), warning contains a low-balance message.

POST /transcripts/store

Store a transcript from structured data. Deducts 1 credit on success.

Required fields

Field	Type	Description
`campus_ref`	string	INCRIPT campus ID or mapped external reference
`student_name`	string	Full name of the student
`program_name`	string	Program or credential name
`courses`	array	Non-empty array of course objects (each needs `course_name`)

Optional fields

Field	Type	Description
`issue_type`	string	Default: `completion`
`issue_date`	date	ISO date (YYYY-MM-DD). Default: today
`certified_by`	string	Certifying official name
`student_id`	string	Institution student ID
`date_of_birth`	date	Student date of birth
`address`	string	Street address
`city`	string	City
`postal_code`	string	Postal / ZIP code
`program_start`	date	Program start date
`program_end`	date	Program end date
`program_hours`	number	Total program hours
`final_marks_or_gpa`	string	Final GPA or marks
`program_credentials`	string	Credential awarded
`folder_id`	string	Optional folder label for stored files
`external_ref`	string	Your system's transcript reference (returned in response)
`uploaded_by_name`	string	Person who triggered the upload (for audit logs)
`uploaded_by_email`	string	Email of the person who triggered the upload

Course object

Field	Required	Description
`course_name`	Yes	Course title
`course_code`	No	Course code
`term`	No	Term or semester
`course_start`	No	Start date
`course_end`	No	End date
`grade_or_marks`	No	Grade or mark

Example request

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "/api/v1/transcripts/store" \
  -d '{
    "campus_ref": "12",
    "student_name": "Jane Doe",
    "student_id": "STU-10042",
    "program_name": "Business Administration",
    "issue_date": "2026-06-01",
    "final_marks_or_gpa": "3.85",
    "external_ref": "pathwayz-transcript-88421",
    "uploaded_by_name": "Sarah Chen",
    "uploaded_by_email": "sarah@college.ca",
    "courses": [
      {
        "term": "Fall 2025",
        "course_code": "ACCT101",
        "course_name": "Financial Accounting",
        "grade_or_marks": "A"
      },
      {
        "term": "Winter 2026",
        "course_code": "MKTG200",
        "course_name": "Marketing Principles",
        "grade_or_marks": "A-"
      }
    ]
  }'

Example success response

{
  "success": true,
  "data": {
    "transcript_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "student_record_id": null,
    "credits_used": 1,
    "credits_remaining": 249,
    "external_ref": "pathwayz-transcript-88421",
    "stored_at": "2026-06-21T12:00:00+00:00"
  }
}

Insufficient credits (402)

{
  "success": false,
  "error": "Insufficient credits. Campus has 0 credits remaining...",
  "credits_remaining": 0,
  "credits_required": 1
}

GET /transcripts/{transcript_id}?campus_ref={campus_id}

Verify a transcript was stored and check its current state. The transcript must belong to your organization and the resolved campus.

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "/api/v1/transcripts/a1b2c3d4-e5f6-7890-abcd-ef1234567890?campus_ref=12"

{
  "success": true,
  "data": {
    "transcript_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "state": "stored",
    "student_name": "Jane Doe",
    "student_id": "STU-10042",
    "program_name": "Business Administration",
    "stored_at": "2026-06-21 12:00:00"
  }
}

Recommended integration workflow

Org admin generates an API key in INCRIPT and shares it securely with your integration team
Call GET /campuses to list campuses and cache each campus_id
Before each upload, optionally call GET /credits/balance?campus_ref=... to warn users if credits are low
Call POST /transcripts/store with structured transcript data and your external_ref for idempotency tracking on your side
Store the returned transcript_id — use it with GET /transcripts/{id} to confirm status
Purchase additional credits in INCRIPT when balances run low (credits are managed in the INCRIPT portal, not via API)

Questions or integration support: support@incript.ca

INCRIPT REST API