Natural Persons | Tradevest

Create Natural Person

post

Create new natural person

Authorizations

Body

genderstring · enumRequired

Gender

Possible values:

titlestring · enumOptionalPossible values:

firstNamestring · min: 1 · max: 255Required

All first names of the person according to the identification document

Pattern: ^\S+( \S+)*$

lastNamestring · min: 1 · max: 255Required

Natural person last name

maritalStatusstring · enumOptionalPossible values:

birthDaystring · dateRequired

birthPlacestring · min: 1 · max: 255Required

birthCountrystring · enumRequired

Country code in ISO 3166-1 alpha-2 standard

Possible values:

languagestring · enumOptional

Language code in ISO 639-1 two-letter codes (EU only)

Possible values:

isUsNationalitybooleanRequired

FATCA - Question whether the customer is subject to US tax liability (nationality or other references due to a green card, registration address, etc.).

professionstring · min: 1 · max: 255Optional

professionGroupstring · enumOptionalPossible values:

annualIncomeNetnumberOptional

Annual income net

availableAssetsnumberOptional

Available assets

externalIdstring · min: 1Optional

External Id in partner's system. This value has to be unique

Responses

200

OK

application/json

400

Bad Request

application/json

409

Conflict

application/json

post

POST /entities/natural-persons HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 953

{
  "gender": "MALE",
  "title": "PROFESSOR",
  "firstName": "text",
  "lastName": "text",
  "maritalStatus": "MARRIED",
  "birthDay": "2025-10-14",
  "birthPlace": "text",
  "birthCountry": "AF",
  "nationalities": [
    {
      "countryCode": "AF",
      "nationalIdentifier": "text",
      "nationalIdentifierType": "CONCAT"
    }
  ],
  "language": "da",
  "taxDetails": [
    {
      "taxId": "text",
      "taxResidency": "AF",
      "noTinConfirmation": false
    }
  ],
  "isUsNationality": true,
  "profession": "text",
  "professionGroup": "EMPLOYED",
  "naceSectors": [
    {
      "section": "text",
      "description": "text"
    }
  ],
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "correspondenceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "annualIncomeNet": 1,
  "sourceOfIncome": [
    "INCOME_FROM_EMPLOYMENT"
  ],
  "availableAssets": 1,
  "originOfAssets": [
    "NON_EMPLOYED_LABOR"
  ],
  "contact": {
    "phone": "text",
    "email": "text",
    "fax": "text",
    "website": "text"
  },
  "externalId": "text"
}

{
  "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000"
}

Get Natural Persons

get

Get natural persons

Authorizations

Query parameters

cursorstringOptional

String value used for pagination

limitinteger · min: 1Required

Maximum number of items to return

Default: 20

naturalPersonStatusstring · enumOptional

Natural person status Filter

Possible values:

Responses

200

OK

application/json

400

Bad Request

application/json

get

GET /entities/natural-persons?limit=20 HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": [
    {
      "deathDay": "2025-10-14",
      "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
      "globalId": "text",
      "createdOn": "2025-10-14T10:36:16.109Z",
      "modifiedOn": "2025-10-14T10:36:16.109Z",
      "verifiedOn": "2025-10-14T10:36:16.109Z",
      "isPep": true,
      "isPepRelated": true,
      "isSanction": true,
      "riskLevel": "LOW",
      "naturalPersonStatus": "CREATED",
      "naturalPersonIdentifications": [
        {
          "identificationId": "123e4567-e89b-12d3-a456-426614174000",
          "createdOn": "2025-10-14T10:36:16.109Z",
          "modifiedOn": "2025-10-14T10:36:16.109Z",
          "externalVerifier": "WEB_ID",
          "identificationType": "VIDEO_IDENT",
          "identificationDate": "2025-10-14",
          "identificationDocumentType": "ID",
          "documentNumber": "text",
          "documentCountry": "AF",
          "documentIssuer": "text",
          "documentIssueDate": "2025-10-14",
          "documentExpiryDate": "2025-10-14",
          "documentMotherFullName": "text",
          "documentMotherResidenceCity": "text",
          "documentFatherFullName": "text",
          "documentFatherResidenceCity": "text"
        }
      ],
      "naturalPersonSignedDocuments": [
        {
          "partnerDocumentId": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "documentType": "TERMS_AND_CONDITIONS",
          "version": 1,
          "customerId": "123e4567-e89b-12d3-a456-426614174000",
          "createdOn": "2025-10-14T10:36:16.109Z",
          "modifiedOn": "2025-10-14T10:36:16.109Z"
        }
      ],
      "tradingProfile": {
        "basicProfileAcknowledgement": {
          "acknowledged": true,
          "acknowledgedOn": "2025-10-14T10:36:16.109Z",
          "acknowledgmentVersionCode": "ACKNOWLEDGMENT_BASIC_PROFILE_V1_DE_2025",
          "content": "text"
        },
        "assetTypeProfiles": [
          {
            "assetType": "BOND",
            "hasKnowledge": true,
            "hasExperience": true,
            "tradingExperience": {
              "yearsOfExperience": 1,
              "numberOfTrades": 1,
              "tradeVolume": 1
            },
            "createdOn": "2025-10-14T10:36:16.109Z",
            "modifiedOn": "2025-10-14T10:36:16.109Z"
          }
        ],
        "investmentObjectives": {
          "growthAndSavings": [
            "CAPITAL_GROWTH"
          ],
          "capitalProtectionAndHedging": [
            "WEALTH_PRESERVATION"
          ],
          "incomeAndLiquidity": [
            "INCOME_GENERATION"
          ],
          "retirementAndFuturePlanning": [
            "PENSION_PLANNING"
          ],
          "specificInvestmentTypes": [
            "INVESTMENT_IN_LISTED_EQUITIES"
          ],
          "taxAndEstatePlanning": [
            "TAX_PLANNING"
          ]
        }
      },
      "gender": "MALE",
      "title": "PROFESSOR",
      "firstName": "text",
      "lastName": "text",
      "maritalStatus": "MARRIED",
      "birthDay": "2025-10-14",
      "birthPlace": "text",
      "birthCountry": "AF",
      "nationalities": [
        {
          "countryCode": "AF",
          "nationalIdentifier": "text",
          "nationalIdentifierType": "CONCAT"
        }
      ],
      "language": "da",
      "taxDetails": [
        {
          "taxId": "text",
          "taxResidency": "AF",
          "noTinConfirmation": false
        }
      ],
      "isUsNationality": true,
      "profession": "text",
      "professionGroup": "EMPLOYED",
      "naceSectors": [
        {
          "section": "text",
          "description": "text"
        }
      ],
      "mainAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "correspondenceAddress": {
        "street": "text",
        "streetNumber": "text",
        "city": "text",
        "zip": "text",
        "country": "AF",
        "additionalInfo": "text"
      },
      "annualIncomeNet": 1,
      "sourceOfIncome": [
        "INCOME_FROM_EMPLOYMENT"
      ],
      "availableAssets": 1,
      "originOfAssets": [
        "NON_EMPLOYED_LABOR"
      ],
      "contact": {
        "phone": "text",
        "email": "text",
        "fax": "text",
        "website": "text"
      },
      "externalId": "text"
    }
  ],
  "pagination": {
    "cursor": "text",
    "limit": 1
  }
}

Get Natural Person

get

Get natural person

Authorizations

Path parameters

naturalPersonIdstring · uuidRequired

Natural Person ID

Responses

200

OK

application/json

400

Bad Request

application/json

404

Not Found

application/json

get

GET /entities/natural-persons/{naturalPersonId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "deathDay": "2025-10-14",
  "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
  "globalId": "text",
  "createdOn": "2025-10-14T10:36:16.109Z",
  "modifiedOn": "2025-10-14T10:36:16.109Z",
  "verifiedOn": "2025-10-14T10:36:16.109Z",
  "isPep": true,
  "isPepRelated": true,
  "isSanction": true,
  "riskLevel": "LOW",
  "naturalPersonStatus": "CREATED",
  "naturalPersonIdentifications": [
    {
      "identificationId": "123e4567-e89b-12d3-a456-426614174000",
      "createdOn": "2025-10-14T10:36:16.109Z",
      "modifiedOn": "2025-10-14T10:36:16.109Z",
      "externalVerifier": "WEB_ID",
      "identificationType": "VIDEO_IDENT",
      "identificationDate": "2025-10-14",
      "identificationDocumentType": "ID",
      "documentNumber": "text",
      "documentCountry": "AF",
      "documentIssuer": "text",
      "documentIssueDate": "2025-10-14",
      "documentExpiryDate": "2025-10-14",
      "documentMotherFullName": "text",
      "documentMotherResidenceCity": "text",
      "documentFatherFullName": "text",
      "documentFatherResidenceCity": "text"
    }
  ],
  "naturalPersonSignedDocuments": [
    {
      "partnerDocumentId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "documentType": "TERMS_AND_CONDITIONS",
      "version": 1,
      "customerId": "123e4567-e89b-12d3-a456-426614174000",
      "createdOn": "2025-10-14T10:36:16.109Z",
      "modifiedOn": "2025-10-14T10:36:16.109Z"
    }
  ],
  "tradingProfile": {
    "basicProfileAcknowledgement": {
      "acknowledged": true,
      "acknowledgedOn": "2025-10-14T10:36:16.109Z",
      "acknowledgmentVersionCode": "ACKNOWLEDGMENT_BASIC_PROFILE_V1_DE_2025",
      "content": "text"
    },
    "assetTypeProfiles": [
      {
        "assetType": "BOND",
        "hasKnowledge": true,
        "hasExperience": true,
        "tradingExperience": {
          "yearsOfExperience": 1,
          "numberOfTrades": 1,
          "tradeVolume": 1
        },
        "createdOn": "2025-10-14T10:36:16.109Z",
        "modifiedOn": "2025-10-14T10:36:16.109Z"
      }
    ],
    "investmentObjectives": {
      "growthAndSavings": [
        "CAPITAL_GROWTH"
      ],
      "capitalProtectionAndHedging": [
        "WEALTH_PRESERVATION"
      ],
      "incomeAndLiquidity": [
        "INCOME_GENERATION"
      ],
      "retirementAndFuturePlanning": [
        "PENSION_PLANNING"
      ],
      "specificInvestmentTypes": [
        "INVESTMENT_IN_LISTED_EQUITIES"
      ],
      "taxAndEstatePlanning": [
        "TAX_PLANNING"
      ]
    }
  },
  "gender": "MALE",
  "title": "PROFESSOR",
  "firstName": "text",
  "lastName": "text",
  "maritalStatus": "MARRIED",
  "birthDay": "2025-10-14",
  "birthPlace": "text",
  "birthCountry": "AF",
  "nationalities": [
    {
      "countryCode": "AF",
      "nationalIdentifier": "text",
      "nationalIdentifierType": "CONCAT"
    }
  ],
  "language": "da",
  "taxDetails": [
    {
      "taxId": "text",
      "taxResidency": "AF",
      "noTinConfirmation": false
    }
  ],
  "isUsNationality": true,
  "profession": "text",
  "professionGroup": "EMPLOYED",
  "naceSectors": [
    {
      "section": "text",
      "description": "text"
    }
  ],
  "mainAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "correspondenceAddress": {
    "street": "text",
    "streetNumber": "text",
    "city": "text",
    "zip": "text",
    "country": "AF",
    "additionalInfo": "text"
  },
  "annualIncomeNet": 1,
  "sourceOfIncome": [
    "INCOME_FROM_EMPLOYMENT"
  ],
  "availableAssets": 1,
  "originOfAssets": [
    "NON_EMPLOYED_LABOR"
  ],
  "contact": {
    "phone": "text",
    "email": "text",
    "fax": "text",
    "website": "text"
  },
  "externalId": "text"
}

Update Natural Person

patch

Update natural person

Authorizations

Path parameters

naturalPersonIdstring · uuidRequired

Natural Person ID

Header parameters

Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Body

documentIdstring · uuidOptional

Document ID in UUID format for those params where a document upload is required (title, lastName, deathDay)

Responses

202

Accepted

No content

400

Bad Request

application/json

patch

PATCH /entities/natural-persons/{naturalPersonId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Requestor-ID: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 954

{
  "naturalPersonUpdateData": {
    "annualIncomeNet": 1,
    "sourceOfIncome": [
      "INCOME_FROM_EMPLOYMENT"
    ],
    "availableAssets": 1,
    "originOfAssets": [
      "NON_EMPLOYED_LABOR"
    ],
    "contact": {
      "phone": "text",
      "email": "text",
      "fax": "text",
      "website": "text"
    },
    "mainAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "correspondenceAddress": {
      "street": "text",
      "streetNumber": "text",
      "city": "text",
      "zip": "text",
      "country": "AF",
      "additionalInfo": "text"
    },
    "title": "PROFESSOR",
    "lastName": "text",
    "firstName": "text",
    "gender": "MALE",
    "maritalStatus": "MARRIED",
    "profession": "text",
    "professionGroup": "EMPLOYED",
    "naceSectors": [
      {
        "section": "text",
        "description": "text"
      }
    ],
    "taxDetails": [
      {
        "taxId": "text",
        "taxResidency": "AF",
        "noTinConfirmation": false
      }
    ],
    "nationalities": [
      {
        "countryCode": "AF",
        "nationalIdentifier": "text",
        "nationalIdentifierType": "CONCAT"
      }
    ],
    "externalId": "text",
    "deathDay": "2025-10-14"
  },
  "documentId": "123e4567-e89b-12d3-a456-426614174000"
}

No content