> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List incorporation issues

> List partner-visible issues for an incorporation. Active issues are returned by default. Issues are read-only over the Partner API; fix the underlying intake, participant, or document data to resolve them.

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](/engine/incorporation/partner-incorporation-status-GET) 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:

| Code                    | Meaning                                                       |
| ----------------------- | ------------------------------------------------------------- |
| `MISSING_INFORMATION`   | Required information is missing.                              |
| `INVALID_INFORMATION`   | Submitted information is present but invalid or inconsistent. |
| `DOCUMENT_REQUIRED`     | A required participant document has not been provided.        |
| `DOCUMENT_INVALID`      | A participant document file could not be accepted.            |
| `COMPANY_NAME_REJECTED` | A proposed company name was rejected or cannot be used.       |
| `OTHER`                 | General 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 type             | Meaning                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `INCORPORATION`        | The issue applies to the overall incorporation.                                                  |
| `INTAKE_FIELD`         | The issue applies to an intake field validation path, such as `companyNames.companyNameOptions`. |
| `PARTICIPANT`          | The issue applies to a registered participant.                                                   |
| `PARTICIPANT_DOCUMENT` | The issue applies to a participant document kind or linked file.                                 |
| `FILE`                 | The 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:

```json theme={null}
{
  "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
}
```


## OpenAPI

````yaml GET /partner/incorporation/{incorporationId}/issues
openapi: 3.0.1
info:
  title: Commenda Public APIs
  description: >-
    APIs for Commenda entity management, partner incorporation, indirect tax,
    compliance, and corporate operations.
  license:
    name: NONE
    url: NONE
  version: 1.0.0
servers:
  - url: https://api.prod.commenda.io/api/v1
    description: Commenda platform APIs, including Partner Incorporation and Commenda OS.
  - url: https://transaction-tax.api.in.commenda.io/api/v1
    description: Global Indirect Tax API.
security:
  - bearerAuth: []
paths:
  /partner/incorporation/{incorporationId}/issues:
    get:
      summary: List incorporation issues
      description: >-
        List partner-visible issues for an incorporation. Active issues are
        returned by default. Issues are read-only over the Partner API; fix the
        underlying intake, participant, or document data to resolve them.
      operationId: listPartnerIncorporationIssues
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PartnerIncorporationIssueStatusFilter'
          description: Filter issues by status. Defaults to `ACTIVE`.
      responses:
        '200':
          description: Issues retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerIncorporationIssuesResponse'
        '400':
          description: Unsupported status filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    PartnerIncorporationIssueStatusFilter:
      type: string
      enum:
        - ACTIVE
        - RESOLVED
        - ALL
    PartnerIncorporationIssuesResponse:
      type: object
      required:
        - issues
        - count
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationIssue'
        count:
          type: integer
          example: 1
    AffiliatePublicError:
      type: object
      required:
        - statusCode
        - message
        - error
      properties:
        statusCode:
          type: integer
          example: 403
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Company does not belong to this affiliate firm
        error:
          type: string
          example: Forbidden
    PartnerIncorporationIssue:
      type: object
      required:
        - id
        - code
        - message
        - status
        - scope
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Stable identifier for one remediation episode.
          example: issue_123
        code:
          $ref: '#/components/schemas/PartnerIncorporationIssueCode'
        message:
          type: string
          example: >-
            The passport scan for Jane Founder is unreadable. Please upload a
            clearer scan.
        status:
          $ref: '#/components/schemas/PartnerIncorporationIssueStatus'
        scope:
          $ref: '#/components/schemas/PartnerIncorporationIssueScope'
        createdAt:
          type: string
          format: date-time
          example: '2026-04-25T20:58:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-04-25T20:59:00.000Z'
        resolvedAt:
          type: string
          format: date-time
          description: Present when `status` is `RESOLVED`.
          example: '2026-04-25T21:15:00.000Z'
    PartnerIncorporationIssueCode:
      type: string
      description: >-
        Current partner-visible issue code. Commenda may add additional issue
        codes in future API updates.
      enum:
        - MISSING_INFORMATION
        - INVALID_INFORMATION
        - DOCUMENT_REQUIRED
        - DOCUMENT_INVALID
        - COMPANY_NAME_REJECTED
        - OTHER
    PartnerIncorporationIssueStatus:
      type: string
      enum:
        - ACTIVE
        - RESOLVED
    PartnerIncorporationIssueScope:
      type: object
      description: >-
        Location the issue applies to. The `type` field determines which
        additional fields are present.
      required:
        - type
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            - INCORPORATION
            - INTAKE_FIELD
            - PARTICIPANT
            - PARTICIPANT_DOCUMENT
            - FILE
        path:
          type: string
          description: Intake field path for `INTAKE_FIELD` scopes.
          example: companyNames.companyNameOptions
        stageId:
          type: string
          description: Optional status workflow stage id this issue blocks.
          example: kyc
        participantId:
          type: string
          description: Incorporation participant id for participant-scoped issues.
          example: participant_123
        resource:
          type: object
          description: Reusable Commenda OS resource for participant-scoped issues.
          properties:
            resourceType:
              type: string
              enum:
                - KEY_PERSON
                - BUSINESS_ENTITY
            resourceId:
              type: integer
              example: 12
        documentKind:
          type: string
          description: Participant document kind for participant-document issues.
          example: PASSPORT_SCAN
        fileId:
          type: integer
          description: Commenda file id for file or participant-document issues.
          example: 456
      example:
        type: PARTICIPANT_DOCUMENT
        stageId: kyc
        participantId: participant_123
        documentKind: PASSPORT_SCAN
        fileId: 456
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````