Skip to main content
GET
/
partner
/
incorporation
/
{incorporationId}
/
issues
List incorporation issues
curl --request GET \
  --url https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues \
  --header 'x-api-key: <api-key>'
{
  "issues": [
    {
      "id": "issue_123",
      "message": "The passport scan for Jane Founder is unreadable. Please upload a clearer scan.",
      "scope": {
        "type": "PARTICIPANT_DOCUMENT",
        "stageId": "kyc",
        "participantId": "participant_123",
        "documentKind": "PASSPORT_SCAN",
        "fileId": 456
      },
      "createdAt": "2026-04-25T20:58:00.000Z",
      "updatedAt": "2026-04-25T20:59:00.000Z",
      "resolvedAt": "2026-04-25T21:15:00.000Z"
    }
  ],
  "count": 1
}
Lists partner-visible issues for an incorporation. Issues are created and resolved by Commenda. Partners use this endpoint to understand what needs attention, then update intake data, participants, or documents through the normal incorporation endpoints. There is no public issue mutation endpoint in this phase. By default this endpoint returns active issues only. Use status=RESOLVED for resolved issues or status=ALL for the full issue history.

​
Correction cycle semantics

Each issue row represents one remediation episode. If Commenda needs the same kind of correction again after a prior issue was resolved, Commenda creates a new issue instead of reopening the old issue. This keeps webhook delivery and partner reconciliation simple:
  • issue.id is stable for one correction episode.
  • INCORPORATION_ISSUE_CREATED is emitted when that episode starts.
  • INCORPORATION_ISSUE_RESOLVED is emitted once when that episode is resolved.
Active issues make incorporationStatus return BLOCKED. Read Get incorporation status to see which issues are currently blocking the incorporation and, when Commenda has assigned a stage, which stage they block.

​
Issue codes

Current issue codes:
CodeMeaning
MISSING_INFORMATIONRequired information is missing.
INVALID_INFORMATIONSubmitted information is present but invalid or inconsistent.
DOCUMENT_REQUIREDA required participant document has not been provided.
DOCUMENT_INVALIDA participant document file could not be accepted.
COMPANY_NAME_REJECTEDA proposed company name was rejected or cannot be used.
OTHERGeneral issue not covered by a more specific code.
Commenda may add additional issue codes in future API updates. Avoid hard-coding business logic that assumes this list is permanently exhaustive.

​
Issue scopes

scope tells you where the issue applies.
Scope typeMeaning
INCORPORATIONThe issue applies to the overall incorporation.
INTAKE_FIELDThe issue applies to an intake field validation path, such as companyNames.companyNameOptions.
PARTICIPANTThe issue applies to a registered participant.
PARTICIPANT_DOCUMENTThe issue applies to a participant document kind or linked file.
FILEThe issue applies to an uploaded customer file used for the incorporation.
Scopes may also include stageId. When present, it matches a stage returned by the status workflow and is used to attach the issue to that stage in the status response. Example response: 
{
  "issues": [
    {
      "id": "issue_123",
      "code": "DOCUMENT_INVALID",
      "message": "The passport scan for Jane Founder is unreadable. Please upload a clearer scan.",
      "status": "ACTIVE",
      "scope": {
        "type": "PARTICIPANT_DOCUMENT",
        "stageId": "kyc",
        "participantId": "participant_123",
        "documentKind": "PASSPORT_SCAN",
        "fileId": 456
      },
      "createdAt": "2026-04-25T20:58:00.000Z",
      "updatedAt": "2026-04-25T20:59:00.000Z"
    }
  ],
  "count": 1
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
incorporationId
string
required

Incorporation identifier returned by create or list endpoints.

Query Parameters

​
status
enum<string>

Filter issues by status. Defaults to ACTIVE.

Available options:
ACTIVE,
RESOLVED,
ALL

Response

Issues retrieved successfully

​
issues
object[]
required
​
count
integer
required
Example:

1