Submitting Applications

There are two ways to submit an application through the API, depending on whether your data uses the platform’s standard field names or a custom schema:

Path	When to use it
Form path	Your data already uses the exact field keys from the cohort’s generated application form
Schema path	Your data uses your own field names — you’ve registered a custom schema

Both paths use the same endpoint. The presence or absence of schema_id in the request body determines which path is used.

Required scope

Your API key needs applications:write to submit.

The form path (no schema)

Use this when your data maps directly to the keys the platform generated for the cohort’s form. You can retrieve those field keys by looking at your cohort’s form in the portal, or by asking your platform admin.

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

{
  "cohort_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "founder_name": "Amara Obi",
  "contact_email": "amara@example.com",
  "answers": [
    { "key": "problem_statement",   "value": "Smallholder farmers in West Africa lose 30–40% of harvest to post-harvest spoilage due to lack of cold-chain infrastructure." },
    { "key": "proposed_solution",   "value": "A solar-powered, mobile cold-room unit that can be deployed at farm-gate level, leased on a pay-per-use model." },
    { "key": "target_customer",     "value": "Smallholder maize and tomato farmers in Oyo and Kaduna states, Nigeria." },
    { "key": "current_traction",    "value": "Piloting with 12 farming cooperatives. 847 farmers onboarded. ₦2.3M in lease revenue in the first 3 months." },
    { "key": "business_sector",     "value": "AgriTech" },
    { "key": "country_of_operation","value": "Nigeria" }
  ]
}

founder_name and contact_email are always top-level fields, not inside answers.

answers is an array of { key, value } objects — one per field. Both key and value are strings. For multi-select fields, join the selected values with a comma: "value": "fintech, payments, b2b".

Response (202 Accepted):

{
  "submission_id": "667a1b2c3d4e5f6a7b8c9d0e",
  "status": "pending",
  "message": "Submission received and queued for processing.",
  "env": "live"
}

202 means the submission was accepted and queued. It doesn’t mean processing is done — the AI review happens asynchronously. See Checking submission status below.

The schema path (with a custom schema)

Use this when you’ve registered a custom schema (see Custom Schemas). Include schema_id in the request body and use the field keys from your schema’s registration response.

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

{
  "cohort_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "schema_id": "a1b2c3d4e5f6a7b8",
  "founder_name": "Amara Obi",
  "contact_email": "amara@example.com",
  "answers": [
    { "key": "what_problem_are_you_solving", "value": "Smallholder farmers..." },
    { "key": "describe_your_solution",       "value": "A solar-powered..." },
    { "key": "who_is_your_target_customer",  "value": "Smallholder maize..." },
    { "key": "what_traction_do_you_have",    "value": "Piloting with 12..." },
    { "key": "industry_or_sector",           "value": "AgriTech" },
    { "key": "country_of_operation",         "value": "Nigeria" }
  ]
}

The field keys here come from the schema registration response — not from the original labels you sent.

Strict validation on the schema path

The schema path enforces strict validation:

Unknown keys — if your answers array contains a key that wasn’t in the registered schema, the entire submission is rejected:

{
  "error": "Submission contains keys not in schema",
  "unknown_keys": ["legacy_field_name", "extra_column"]
}

Missing required fields — if a field was inferred as required and it’s absent (or blank) in your submission, the submission is rejected:

{
  "error": "Missing required fields",
  "missing_keys": ["what_problem_are_you_solving"]
}

These errors return 422 Unprocessable Entity. Fix the submission and resend — it hasn’t been stored.

Validation that applies to both paths

Regardless of which path you use, the following checks always run:

Cohort must be open — the cohort’s status must be "open". If it’s draft, closed, or completed, you’ll get 403.

Cohort must match the key’s restriction — if your API key has a cohort restriction, the cohort_id in your request must match. Mismatches return 403.

Valid email — contact_email must be a valid email address.

Checking submission status

The 202 response you get after submitting means the application has been accepted. Processing happens asynchronously — you need to poll to find out when it’s done.

Scope required: applications:read

GET /v1/api/applications/667a1b2c3d4e5f6a7b8c9d0e
Authorization: Bearer inc_live_xxxxxxxxxxxx

Response:

{
  "id": "667a1b2c3d4e5f6a7b8c9d0e",
  "cohort_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "founder_name": "Amara Obi",
  "contact_email": "amara@example.com",
  "status": "complete",
  "review_status": null,
  "submitted_at": "2026-08-08T10:15:00",
  "is_preview": false
}

status moves from pending → processing → complete (or failed if something went wrong). Once complete, the full report is visible to your team in the portal.

Retrieving scores and insights

Once a submission reaches complete, you can retrieve its AI report via the API.

Scope required: insights:read

GET /v1/api/applications/667a1b2c3d4e5f6a7b8c9d0e/insights
Authorization: Bearer inc_live_xxxxxxxxxxxx

Response:

{
  "id": "668b2c3d4e5f6a7b8c9d0e1f",
  "submission_id": "667a1b2c3d4e5f6a7b8c9d0e",
  "business_summary": "ColdChain Go provides pay-per-use solar cold rooms for smallholder farmers at farm-gate level, addressing post-harvest losses in West Africa.",
  "clarity_score": 84,
  "founder_fit_score": 79,
  "idea_strength_score": 4.1,
  "industry_field": "AgriTech",
  "fit_reasoning": "Strong founder-market fit — the team has direct experience in agricultural logistics...",
  "fit_dimensions": [
    { "dimension": "Founder-Market Fit", "score": 87, "weight": 35 },
    { "dimension": "Market Opportunity",  "score": 76, "weight": 30 },
    { "dimension": "Social Impact",       "score": 82, "weight": 35 }
  ],
  "guard_rail_flags": [],
  "generated_at": "2026-08-08T10:17:43"
}

If the report isn’t ready yet (the submission is still processing), you’ll get 404. Poll the status endpoint first and wait for status: "complete" before fetching insights.

Common errors and how to fix them

Error	Status	Fix
`"cohort_id is required"`	400	Add `cohort_id` to your request body
`"Cohort not found"`	404	Check the cohort ID — use `/v1/api/programs` to list valid cohort IDs
`"This cohort is not currently accepting applications"`	403	The cohort is not `open`. Check the cohort status in the portal.
`"This API key is not authorized for this cohort"`	403	Your key has a cohort restriction that doesn’t match this `cohort_id`
`"Schema not found"`	404	The `schema_id` doesn’t exist or belongs to a different incubator
`"Schema does not belong to this cohort"`	400	The schema was registered against a different cohort
`"Submission contains keys not in schema"`	422	Remove the listed unknown keys from your `answers` array
`"Missing required fields"`	422	Add the listed missing keys to your `answers` array