List incorporation issues

curl --request GET \
  --url https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

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>'

import requests

url = "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.commenda.io/api/v1/partner/incorporation/{incorporationId}/issues")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Company does not belong to this affiliate firm",
  "error": "Forbidden"
}

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:

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:

{
  "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

Show child attributes

count

integer

required

Example:

1

Submit an incorporation Incorporation webhooks

Overview

Customer setup

Partner Incorporation API

Commenda OS Partner API

Webhooks

Correction cycle semantics

Issue codes

Issue scopes

Authorizations

Path Parameters

Query Parameters

Response

​Correction cycle semantics

​Issue codes

​Issue scopes

Authorizations

Path Parameters

Query Parameters

Response

Correction cycle semantics

Issue codes

Issue scopes