API Integration Overview

The Narrative Intelligence API lets you connect your own systems — a website, a CRM, an event registration tool, or a custom pipeline — directly to the platform. Submissions that come in through the API go through the exact same AI review pipeline as applications from the public form. Your team sees them in the same submissions list, with the same scores and reports.

This section is for teams that want to integrate programmatically. If you just need to import a spreadsheet, see Importing via CSV.

What you can do with the API

Submit applications from an external system, one at a time or in bulk
Register a custom schema so the platform understands your data’s structure
Discover your cohorts — retrieve cohort IDs and programme details
Read submissions — retrieve application status and scores
Read insights — retrieve full AI reports for submitted applications

Base URL

All API requests go to:

https://api.thenarrativeintelligencecompany.ai

All endpoints are under the /v1/api/ path prefix.

Authentication

Every API request must include your API key as a Bearer token in the Authorization header:

Authorization: Bearer inc_live_xxxxxxxxxxxx

Requests without a valid key return 401 Unauthorized. Requests with a key that lacks the required permission for that endpoint return 403 Forbidden.

See API Keys for how to create and manage keys.

Response format

All responses are JSON. Successful responses return the relevant data directly:

{ "submission_id": "abc123", "status": "pending" }

Errors always follow this shape:

{ "error": "Human-readable description of what went wrong" }

HTTP status codes

Code	What it means
`200`	Success
`201`	Created (new resource)
`202`	Accepted — request is valid and queued for processing (used for submissions)
`400`	Bad request — missing or invalid field in your request body
`401`	Missing or invalid API key
`403`	Key is valid but doesn’t have permission for this action, or the key is restricted to a different cohort
`404`	Resource not found
`422`	Validation failed — submission contains unknown keys or is missing required fields
`429`	Rate limit exceeded — slow down and retry

Rate limits

Requests are rate-limited per IP and per account. If you exceed the limit, you’ll receive a 429 response with a Retry-After header telling you how many seconds to wait before retrying.

Getting started

The typical integration path:

Create an API key — API Keys →
Discover your cohort ID — Discovering Cohorts →
Register your schema (if your fields don’t match the standard form) — Custom Schemas →
Start submitting applications — Submitting Applications →
Test with a test key before going live — Test Mode →