Ingest UBOs, Directors & Signatories

This guide walks you through ingesting Members - the individuals and entities associated with corporate clients as Ultimate Beneficial Owners (UBOs), Directors, Officers, or Signatories. Full API endpoint details are available in the API Reference (requires API credentials).

Before ingesting members, make sure the related corporate clients have already been ingested. See the Ingesting Clients guide.

Overview

Members represent the people and entities behind a corporate client. Each member has:

A role type defining their relationship to the corporate (e.g., OWNER, DIRECTOR, BENEFICIAL_OWNER)
Screening statuses for Sanctions, PEP, and Adverse Media checks
An approval status reflecting their overall verification state

Members support upsert behavior: if a member with the same referenceId already exists, it will be updated.

Available Role Types

Role	Description
`OWNER`	Owner of the corporate entity
`DIRECTOR`	Director / board member
`OFFICER`	Corporate officer
`AUTHORIZED_REPRESENTATIVE`	Authorized to act on behalf of the entity
`BENEFICIAL_OWNER`	Ultimate beneficial owner (UBO)
`SHAREHOLDER`	Shareholder of the entity
`SIGNATORY`	Authorized signatory
`TRUSTEE`	Trustee (for trusts)
`PROTECTOR`	Trust protector
`SETTLOR`	Trust settlor
`OTHER`	Other relationship

Step 1: Create Individual Members

Endpoint: POST /v1/members/individuals Use this endpoint to add natural persons (e.g., UBOs, directors) to a corporate client.

POST /v1/members/individuals?upsert=true
Content-Type: application/json

{
  "referenceId": "MEM-IND-001",
  "firstName": "Jane",
  "lastName": "Smith",
  "middleName": "Marie",
  "email": "jane.smith@example.com",
  "phoneNumber": "+1-555-123-4567",
  "dateOfBirth": "1980-03-20T00:00:00Z",
  "citizenship": "USA",
  "personalIdNumber": "987-65-4321",
  "residentialAddressLine1": "456 Oak Avenue",
  "residentialAddressCity": "San Francisco",
  "residentialAddressPostalCode": "94102",
  "residentialAddressCountry": "USA",
  "ownershipPercentage": 35,
  "roleType": "BENEFICIAL_OWNER",
  "title": "Co-Founder",
  "status": "APPROVED",
  "statusDate": "2024-01-10T00:00:00Z",
  "sanctionsStatus": "CLEAR",
  "sanctionsStatusDate": "2024-01-10T00:00:00Z",
  "pepStatus": "CLEAR",
  "pepStatusDate": "2024-01-10T00:00:00Z",
  "adverseMediaStatus": "CLEAR",
  "adverseMediaStatusDate": "2024-01-10T00:00:00Z",
  "corporates": ["corporate-client-uuid"]
}

const member = await corsa.members.createIndividualMember(
  {
    referenceId: "MEM-IND-001",
    firstName: "Jane",
    lastName: "Smith",
    middleName: "Marie",
    email: "jane.smith@example.com",
    phoneNumber: "+1-555-123-4567",
    dateOfBirth: "1980-03-20T00:00:00Z",
    citizenship: "USA",
    personalIdNumber: "987-65-4321",
    residentialAddressLine1: "456 Oak Avenue",
    residentialAddressCity: "San Francisco",
    residentialAddressPostalCode: "94102",
    residentialAddressCountry: "USA",
    ownershipPercentage: 35,
    roleType: "BENEFICIAL_OWNER",
    title: "Co-Founder",
    status: "APPROVED",
    statusDate: "2024-01-10T00:00:00Z",
    sanctionsStatus: "CLEAR",
    sanctionsStatusDate: "2024-01-10T00:00:00Z",
    pepStatus: "CLEAR",
    pepStatusDate: "2024-01-10T00:00:00Z",
    adverseMediaStatus: "CLEAR",
    adverseMediaStatusDate: "2024-01-10T00:00:00Z",
    corporates: ["corporate-client-uuid"],
  },
  true // upsert
);

from corsa_sdk.api.members.create_individual_member import _get_kwargs
from corsa_sdk.models.create_individual_member_dto import CreateIndividualMemberDto

resp = http.request(**_get_kwargs(
    body=CreateIndividualMemberDto(
        reference_id="MEM-IND-001",
        first_name="Jane",
        last_name="Smith",
        middle_name="Marie",
        email="jane.smith@example.com",
        phone_number="+1-555-123-4567",
        date_of_birth="1980-03-20T00:00:00Z",
        citizenship="USA",
        personal_id_number="987-65-4321",
        residential_address_line1="456 Oak Avenue",
        residential_address_city="San Francisco",
        residential_address_postal_code="94102",
        residential_address_country="USA",
        ownership_percentage=35,
        role_type="BENEFICIAL_OWNER",
        title="Co-Founder",
        status="APPROVED",
        status_date="2024-01-10T00:00:00Z",
        sanctions_status="CLEAR",
        sanctions_status_date="2024-01-10T00:00:00Z",
        pep_status="CLEAR",
        pep_status_date="2024-01-10T00:00:00Z",
        adverse_media_status="CLEAR",
        adverse_media_status_date="2024-01-10T00:00:00Z",
        corporates=["corporate-client-uuid"],
    ),
    upsert=True,
))
member = resp.json()

Key Fields

Field	Required	Description
`firstName`, `lastName`	Yes	Member’s name
`roleType`	Yes	Relationship to the corporate (see role types above)
`title`	Yes	Position or title within the organization
`status`	Yes	Verification status: `APPROVED`, `REJECTED`, or `UNDER_REVIEW`
`statusDate`	Yes	Date of status determination
`sanctionsStatus`	Yes	`CLEAR`, `FLAGGED`, `UNDER_REVIEW`, or `NOT_CHECKED`
`pepStatus`	Yes	PEP screening status (same values as sanctions)
`adverseMediaStatus`	Yes	Adverse media screening status (same values as sanctions)
`corporates`	No	Array of corporate client IDs to associate this member with
`ownershipPercentage`	No	Percentage of ownership (0-100)

You can also include identityDocuments inline when creating a member (see Step 2).

Step 2: Add Identity Documents

Endpoint: POST /v1/members/individuals/{memberId}/documents After creating a member, you can add identity documents to them.

POST /v1/members/individuals/member-uuid/documents
Content-Type: application/json

{
  "documentType": "PASSPORT",
  "documentNumber": "AB1234567",
  "documentIssuingCountry": "USA",
  "documentExpirationDate": "2030-06-15",
  "documentImageUrl": "https://your-storage.com/documents/passport-scan.jpg"
}

const updatedMember = await corsa.members.addIndividualMemberDocument(
  "member-uuid",
  {
    documentType: "PASSPORT",
    documentNumber: "AB1234567",
    documentIssuingCountry: "USA",
    documentExpirationDate: "2030-06-15",
    documentImageUrl: "https://your-storage.com/documents/passport-scan.jpg",
  }
);

from corsa_sdk.api.members.add_individual_member_document import _get_kwargs
from corsa_sdk.models.create_identity_document_dto import CreateIdentityDocumentDto

resp = http.request(**_get_kwargs(
    member_id="member-uuid",
    body=CreateIdentityDocumentDto(
        document_type="PASSPORT",
        document_number="AB1234567",
        document_issuing_country="USA",
        document_expiration_date="2030-06-15",
        document_image_url="https://your-storage.com/documents/passport-scan.jpg",
    ),
))
updated_member = resp.json()

Supported Document Types

Type	Description
`PASSPORT`	International passport
`DRIVERS_LICENSE`	Driver’s license
`NATIONAL_ID`	National ID card
`RESIDENCE_PERMIT`	Residence permit
`BIRTH_CERTIFICATE`	Birth certificate
`OTHER`	Other document type

You can add up to 10 identity documents per member. Documents can also be included inline in the identityDocuments array when creating the member in Step 1.

Step 3: Create Corporate Members

Endpoint: POST /v1/members/corporates For nested corporate ownership structures, you can add corporate entities as members of another corporate client.

POST /v1/members/corporates?upsert=true
Content-Type: application/json

{
  "referenceId": "MEM-CORP-001",
  "legalEntityName": "Acme Holdings Ltd",
  "countryOfIncorporation": "GBR",
  "registrationNumber": "12345678",
  "dateOfIncorporation": "2015-01-01T00:00:00Z",
  "businessAddressLine1": "100 Finance Street",
  "businessAddressCity": "London",
  "businessAddressPostalCode": "EC2R 8AH",
  "businessAddressCountry": "GBR",
  "email": "contact@acmeholdings.com",
  "ownershipPercentage": 51,
  "roleType": "SHAREHOLDER",
  "title": "Parent Company",
  "status": "APPROVED",
  "statusDate": "2024-01-10T00:00:00Z",
  "sanctionsStatus": "CLEAR",
  "sanctionsStatusDate": "2024-01-10T00:00:00Z",
  "pepStatus": "NOT_CHECKED",
  "pepStatusDate": "2024-01-10T00:00:00Z",
  "adverseMediaStatus": "CLEAR",
  "adverseMediaStatusDate": "2024-01-10T00:00:00Z",
  "corporates": ["corporate-client-uuid"]
}

const corpMember = await corsa.members.createCorporateMember(
  {
    referenceId: "MEM-CORP-001",
    legalEntityName: "Acme Holdings Ltd",
    countryOfIncorporation: "GBR",
    registrationNumber: "12345678",
    dateOfIncorporation: "2015-01-01T00:00:00Z",
    businessAddressLine1: "100 Finance Street",
    businessAddressCity: "London",
    businessAddressPostalCode: "EC2R 8AH",
    businessAddressCountry: "GBR",
    email: "contact@acmeholdings.com",
    ownershipPercentage: 51,
    roleType: "SHAREHOLDER",
    title: "Parent Company",
    status: "APPROVED",
    statusDate: "2024-01-10T00:00:00Z",
    sanctionsStatus: "CLEAR",
    sanctionsStatusDate: "2024-01-10T00:00:00Z",
    pepStatus: "NOT_CHECKED",
    pepStatusDate: "2024-01-10T00:00:00Z",
    adverseMediaStatus: "CLEAR",
    adverseMediaStatusDate: "2024-01-10T00:00:00Z",
    corporates: ["corporate-client-uuid"],
  },
  true // upsert
);

from corsa_sdk.api.members.create_corporate_member import _get_kwargs
from corsa_sdk.models.create_corporate_member_dto import CreateCorporateMemberDto

resp = http.request(**_get_kwargs(
    body=CreateCorporateMemberDto(
        reference_id="MEM-CORP-001",
        legal_entity_name="Acme Holdings Ltd",
        country_of_incorporation="GBR",
        registration_number="12345678",
        date_of_incorporation="2015-01-01T00:00:00Z",
        business_address_line1="100 Finance Street",
        business_address_city="London",
        business_address_postal_code="EC2R 8AH",
        business_address_country="GBR",
        email="contact@acmeholdings.com",
        ownership_percentage=51,
        role_type="SHAREHOLDER",
        title="Parent Company",
        status="APPROVED",
        status_date="2024-01-10T00:00:00Z",
        sanctions_status="CLEAR",
        sanctions_status_date="2024-01-10T00:00:00Z",
        pep_status="NOT_CHECKED",
        pep_status_date="2024-01-10T00:00:00Z",
        adverse_media_status="CLEAR",
        adverse_media_status_date="2024-01-10T00:00:00Z",
        corporates=["corporate-client-uuid"],
    ),
    upsert=True,
))
corp_member = resp.json()

Step 4: Update Members

Use the PUT endpoints to update existing member data as screening results change or information is updated.

Update an Individual Member

Endpoint: PUT /v1/members/individuals/{memberId}

PUT /v1/members/individuals/member-uuid
Content-Type: application/json

{
  "sanctionsStatus": "FLAGGED",
  "sanctionsStatusDate": "2024-06-15T00:00:00Z",
  "status": "UNDER_REVIEW",
  "statusDate": "2024-06-15T00:00:00Z"
}

const updated = await corsa.members.updateIndividualMember(
  "member-uuid",
  {
    sanctionsStatus: "FLAGGED",
    sanctionsStatusDate: "2024-06-15T00:00:00Z",
    status: "UNDER_REVIEW",
    statusDate: "2024-06-15T00:00:00Z",
  }
);

from corsa_sdk.api.members.update_individual_member import _get_kwargs
from corsa_sdk.models.update_individual_member_dto import UpdateIndividualMemberDto

resp = http.request(**_get_kwargs(
    member_id="member-uuid",
    body=UpdateIndividualMemberDto(
        sanctions_status="FLAGGED",
        sanctions_status_date="2024-06-15T00:00:00Z",
        status="UNDER_REVIEW",
        status_date="2024-06-15T00:00:00Z",
    ),
))
updated = resp.json()

Update a Corporate Member

Endpoint: PUT /v1/members/corporates/{memberId}

PUT /v1/members/corporates/member-uuid
Content-Type: application/json

{
  "ownershipPercentage": 60,
  "adverseMediaStatus": "FLAGGED",
  "adverseMediaStatusDate": "2024-06-15T00:00:00Z"
}

const updated = await corsa.members.updateCorporateMember(
  "member-uuid",
  {
    ownershipPercentage: 60,
    adverseMediaStatus: "FLAGGED",
    adverseMediaStatusDate: "2024-06-15T00:00:00Z",
  }
);

from corsa_sdk.api.members.update_corporate_member import _get_kwargs
from corsa_sdk.models.update_corporate_member_dto import UpdateCorporateMemberDto

resp = http.request(**_get_kwargs(
    member_id="member-uuid",
    body=UpdateCorporateMemberDto(
        ownership_percentage=60,
        adverse_media_status="FLAGGED",
        adverse_media_status_date="2024-06-15T00:00:00Z",
    ),
))
updated = resp.json()

All fields are optional on update - only include the fields you want to change.

What’s Next?

Accounts & Wallets

Ingest bank accounts and blockchain wallets for your clients.

Ingest Operations

Ingest deposits, withdrawals, and trades.

​Overview

​Available Role Types

​Step 1: Create Individual Members

​Key Fields

​Step 2: Add Identity Documents

​Supported Document Types

​Step 3: Create Corporate Members

​Step 4: Update Members

​Update an Individual Member

​Update a Corporate Member

​What’s Next?

Accounts & Wallets

Ingest Operations

Overview

Available Role Types

Step 1: Create Individual Members

Key Fields

Step 2: Add Identity Documents

Supported Document Types

Step 3: Create Corporate Members

Step 4: Update Members

Update an Individual Member

Update a Corporate Member

What’s Next?