Custom Schemas

If your external system collects application data with its own field names — from a custom web form, a CRM, a Google Form, or an existing database — you need to register a schema before submitting. A schema tells the platform what your fields are so it can route them correctly through the AI review engine.

If you’re submitting applications that were collected using the platform’s own public form (with the exact same field names), you can skip schemas entirely and go straight to Submitting Applications.

What a schema is

A schema is a registered mapping of your field names to the platform’s review engine. When you register a schema, the platform:

Reads your list of field names (column headers from your system)
Uses its analysis engine to infer what each field most likely captures — the problem statement, the solution, the founder’s contact details, the sector, and so on
Returns a schema_id you include with every subsequent submission

Submissions with a schema_id are validated strictly against that schema — unknown fields are rejected, and missing required fields are rejected too.

Required scope

Your API key needs the schema:manage scope to register a schema, and schema:read to retrieve existing schema definitions.

Registering a schema

Send a POST request to /v1/api/schema with your cohort ID and the list of fields your system uses:

POST /v1/api/schema
Authorization: Bearer inc_live_xxxxxxxxxxxx
Content-Type: application/json

{
  "cohort_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "fields": [
    { "label": "Full name" },
    { "label": "Email address" },
    { "label": "Startup name" },
    { "label": "What problem are you solving?" },
    { "label": "Describe your solution" },
    { "label": "Who is your target customer?" },
    { "label": "What traction do you have so far?" },
    { "label": "Industry or sector" },
    { "label": "Country of operation" },
    { "label": "Team size" }
  ]
}

Each field object needs at minimum a label — the human-readable name of the field as it appears in your system. Optionally, you can also provide a key (a machine-readable identifier); if you don’t, the platform derives one from the label.

Response (201 Created):

{
  "schema_id": "a1b2c3d4e5f6a7b8",
  "fields": [
    {
      "key": "full_name",
      "label": "Full name",
      "field_type": "text",
      "sources": ["base"],
      "clarity_role": null,
      "required": true
    },
    {
      "key": "email_address",
      "label": "Email address",
      "field_type": "text",
      "sources": ["base"],
      "clarity_role": null,
      "required": true
    },
    {
      "key": "what_problem_are_you_solving",
      "label": "What problem are you solving?",
      "field_type": "textarea",
      "sources": ["clarity"],
      "clarity_role": "problem",
      "required": true
    },
    {
      "key": "describe_your_solution",
      "label": "Describe your solution",
      "field_type": "textarea",
      "sources": ["clarity"],
      "clarity_role": "solution",
      "required": false
    }
    // ... one entry per field
  ],
  "message": "Schema registered. Use schema_id in your application submissions. Submit answers using the field keys above."
}

Save the schema_id — you’ll include it in every submission that uses this schema.

Also note the key values in the response. These are what you use in submissions, not the original labels. The key is derived from the label but lowercased and normalised — always read them from the response rather than guessing.

How the platform infers field roles

The platform reads your field labels and infers two things for each field:

clarity_role — which part of the business this field captures. Fields with a role feed directly into the AI review engine’s understanding of the idea. The possible roles are:

Role	What it means
`problem`	The problem the founder is solving
`solution`	Their proposed solution or approach
`customer`	Who the target customer is
`market`	The market opportunity
`traction`	Evidence of progress — users, revenue, pilots
`team`	Information about the founding team
`business_model`	How the business makes or plans to make money

Fields that don’t map to any of these (e.g. country of operation, team size) have clarity_role: null — they’re still captured but don’t feed into the idea analysis directly.

sources — how the field is used in scoring:

Source	What it means
`base`	Core identity fields (name, email)
`clarity`	Feeds into the idea brief and clarity analysis
`eligibility`	Used for guard rail checks against your eligibility rules
`programme_fit`	Used in the fit scoring

Schema immutability

Once registered, a schema is fixed. You cannot edit or update it.

Same columns = same schema. The platform identifies schemas by a hash of your field names. If you register the same set of field labels again (even in a different order, or with different capitalisation), you’ll get back the same schema_id with no new AI call — the schema already exists.

Different columns = new schema. If your data structure changes — you add a field, remove one, or rename one — you need to register a new schema. Both schemas can coexist in the same cohort; submissions simply reference different schema_id values.

Retrieving existing schemas

List schemas for a cohort

GET /v1/api/schema?cohort_id=665f1a2b3c4d5e6f7a8b9c0d
Authorization: Bearer inc_live_xxxxxxxxxxxx

Response:

{
  "schemas": [
    {
      "schema_id": "a1b2c3d4e5f6a7b8",
      "cohort_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "field_count": 10,
      "created_at": "2026-08-01T09:30:00"
    }
  ]
}

Get a single schema

GET /v1/api/schema/a1b2c3d4e5f6a7b8
Authorization: Bearer inc_live_xxxxxxxxxxxx

Returns the full schema definition including all field keys, labels, types, and roles — useful if you need to check what keys to use in submissions.

Schemas and fit criteria

When a schema is registered for a cohort, the platform automatically inherits the fit criteria from that cohort’s application form. This means even API-submitted applications are scored against the same programme-fit dimensions as form submissions — the scoring is consistent across all channels.

You don’t need to do anything to enable this. It happens automatically at schema registration time.