Skip to main content
POST
/
partner
/
commenda-os
/
customers
/
{customerId}
/
persons
Create a person
curl --request POST \
  --url https://api.prod.commenda.io/api/v1/partner/commenda-os/customers/{customerId}/persons \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "firstName": "Jane",
  "lastName": "Founder",
  "email": "jane@acme.com",
  "dateOfBirth": "1990-04-18",
  "countryOfCitizenship": "SG",
  "residentialAddress": {
    "addressLine1": "1 Raffles Place",
    "city": "Singapore",
    "postalCode": "048616",
    "country": "SG"
  }
}
'
{
  "person": {
    "id": 12,
    "firstName": "Jane",
    "lastName": "Founder",
    "dateOfBirth": "1990-04-18",
    "email": "jane@acme.com",
    "kycIds": [
      {
        "type": "US_SSN",
        "name": "Social Security Number",
        "value": "<string>",
        "documentId": "<string>",
        "doesNotHaveKYCId": true,
        "decryptedValue": "<string>"
      }
    ],
    "residentialAddress": {
      "addressLine1": "1 Raffles Place",
      "city": "Singapore",
      "country": "SG",
      "addressLine2": "Suite 21045",
      "addressLine3": "<string>",
      "postalCode": "048616",
      "state": "<string>"
    },
    "stakeholderId": "stk_123",
    "phoneNumber": "+14155550123",
    "businessEntitiesInfo": [
      {
        "businessEntityId": 44,
        "businessEntityName": "Acme Holdings LLC",
        "sharePercentage": 75,
        "governanceRelationships": {
          "DIRECTOR": {
            "startDate": "2020-01-15",
            "endDate": null,
            "isResidentDirector": true
          },
          "BENEFICIAL_OWNER": {
            "isBeneficialOwner": true
          }
        },
        "jobTitle": [
          "<string>"
        ],
        "startDateOfEmployment": "2025-01-01",
        "isResidentDirector": true
      }
    ],
    "gender": "<string>",
    "nationalities": [
      "<string>"
    ],
    "onboardingInfo": {},
    "employmentStartDate": "2025-01-01",
    "directorIdentificationNumber": "00012345"
  }
}
Create a reusable Commenda OS person for one of your customers. Use this endpoint when an incorporation participant does not already exist in Commenda OS. After creation, pass the returned person.id as the participant resource id: 
{
  "participantType": "INDIVIDUAL",
  "resource": {
    "resourceType": "KEY_PERSON",
    "resourceId": 12
  },
  "roles": [{ "role": "DIRECTOR" }]
}
Use incorporation participant and document endpoints for incorporation-specific roles and documents. This endpoint only creates the reusable person record.

​
Person addresses

Some incorporation requirements validate fields on the referenced person resource. For Singapore individual directors and shareholders, participants.{participantId}.resource.residentialAddress is satisfied by setting residentialAddress on the person: 
{
  "firstName": "Jane",
  "lastName": "Tan",
  "email": "jane@example.com",
  "dateOfBirth": "1990-04-18",
  "countryOfCitizenship": "SG",
  "residentialAddress": {
    "addressLine1": "1 Raffles Place",
    "city": "Singapore",
    "postalCode": "048616",
    "country": "SG"
  }
}
This stores the address on the person. Person read responses return it as the top-level residentialAddress field. It does not create a Commenda OS Location; Location resources are business-entity addresses, such as a partner-provided registered office address.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
customerId
integer
required

Commenda customer identifier.

Body

application/json

Create a reusable Commenda OS person for one of your customers. The customerId is taken from the URL path.

​
firstName
string
required
Example:

"Jane"

​
lastName
string
Example:

"Founder"

​
email
string<email>
Example:

"jane@acme.com"

​
phoneNumber
string
Example:

"+14155550123"

​
residentialAddress
object

Person residential address. Use this for participant resource requirements such as participants.{participantId}.resource.residentialAddress.

​
employmentStartDate
string<date>
Example:

"2025-01-01"

​
dateOfBirth
string<date>
Example:

"1990-04-18"

​
countryOfCitizenship
string
Example:

"SG"

​
ssn
string

SSN or ITIN, when applicable.

Example:

"123-45-6789"

​
hasNoSSN
boolean
Example:

false

​
directorIdentificationNumber
string

Director Identification Number (DIN) assigned to Indian directors.

Example:

"00012345"

Response

Person created successfully

​
person
object
required