Natural Persons

Create Identification Verification

post

Create Identification Verification

After successful request link to a video call should be retrieved with Get Identification Verification endpoint from identificationUrl field of the response.

Currently only externalVerifier = WEB_ID and identificationType = VIDEO_IDENT is supported.

Authorizations

Header parameters

Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Body

naturalPersonIdstring · uuidRequired

externalVerifierstring · enumRequired

The legal name of the vendor/company performing the identification for this natural person

Possible values:

identificationTypestring · enumRequired

Method used to identify the customer

Possible values:

Responses

200

OK

application/json

400

Bad Request

application/json

501

Not Implemented

application/json

post

HTTPcURLJavaScriptPython

POST /entities/identification-verifications 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: 121

{
  "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
  "externalVerifier": "WEB_ID",
  "identificationType": "VIDEO_IDENT"
}

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

Get Identification Verifications

get

Get Identification Verifications

Authorizations

Query parameters

cursorstringOptional

String value used for pagination

limitinteger · min: 1Required

Maximum number of items to return

Default: 20

Header parameters

Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Responses

200

OK

application/json

400

Bad Request

application/json

501

Not Implemented

application/json

get

HTTPcURLJavaScriptPython

GET /entities/identification-verifications HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Requestor-ID: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "data": [
    {
      "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
      "identificationVerificationId": "123e4567-e89b-12d3-a456-426614174000",
      "externalVerifier": "WEB_ID",
      "identificationType": "VIDEO_IDENT",
      "identificationUrl": "text",
      "documentId": "123e4567-e89b-12d3-a456-426614174000",
      "naturalPersonIdentificationId": "123e4567-e89b-12d3-a456-426614174000",
      "createdOn": "2025-08-29T18:58:17.640Z",
      "modifiedOn": "2025-08-29T18:58:17.640Z",
      "status": "RECEIVED"
    }
  ],
  "pagination": {
    "cursor": "text",
    "limit": 1
  }
}

Get Identification Verification

get

Get Identification Verification

Authorizations

Path parameters

identificationVerificationIdstring · uuidRequired

Identification Verification ID

Header parameters

Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Responses

200

OK

application/json

400

Bad Request

application/json

501

Not Implemented

application/json

get

HTTPcURLJavaScriptPython

GET /entities/identification-verifications/{identificationVerificationId} HTTP/1.1
Host: tvda-api.platform-test.tradevest.ai
Authorization: Bearer YOUR_OAUTH2_TOKEN
Requestor-ID: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
  "identificationVerificationId": "123e4567-e89b-12d3-a456-426614174000",
  "externalVerifier": "WEB_ID",
  "identificationType": "VIDEO_IDENT",
  "identificationUrl": "text",
  "documentId": "123e4567-e89b-12d3-a456-426614174000",
  "naturalPersonIdentificationId": "123e4567-e89b-12d3-a456-426614174000",
  "createdOn": "2025-08-29T18:58:17.640Z",
  "modifiedOn": "2025-08-29T18:58:17.640Z",
  "status": "RECEIVED"
}

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

501

Not Implemented

application/json

post

HTTPcURLJavaScriptPython

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-08-29",
  "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

501

Not Implemented

application/json

get

HTTPcURLJavaScriptPython

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

{
  "data": [
    {
      "deathDay": "2025-08-29",
      "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
      "globalId": "text",
      "createdOn": "2025-08-29T18:58:17.640Z",
      "modifiedOn": "2025-08-29T18:58:17.640Z",
      "verifiedOn": "2025-08-29T18:58:17.640Z",
      "isPep": true,
      "isPepRelated": true,
      "isSanction": true,
      "riskLevel": "LOW",
      "naturalPersonStatus": "CREATED",
      "naturalPersonIdentifications": [
        {
          "identificationId": "123e4567-e89b-12d3-a456-426614174000",
          "createdOn": "2025-08-29T18:58:17.640Z",
          "modifiedOn": "2025-08-29T18:58:17.640Z",
          "externalVerifier": "WEB_ID",
          "identificationType": "VIDEO_IDENT",
          "identificationDate": "2025-08-29",
          "identificationDocumentType": "ID",
          "documentNumber": "text",
          "documentCountry": "AF",
          "documentIssuer": "text",
          "documentIssueDate": "2025-08-29",
          "documentExpiryDate": "2025-08-29",
          "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-08-29T18:58:17.640Z",
          "modifiedOn": "2025-08-29T18:58:17.640Z"
        }
      ],
      "gender": "MALE",
      "title": "PROFESSOR",
      "firstName": "text",
      "lastName": "text",
      "maritalStatus": "MARRIED",
      "birthDay": "2025-08-29",
      "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

501

Not Implemented

application/json

get

HTTPcURLJavaScriptPython

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

{
  "deathDay": "2025-08-29",
  "naturalPersonId": "123e4567-e89b-12d3-a456-426614174000",
  "globalId": "text",
  "createdOn": "2025-08-29T18:58:17.640Z",
  "modifiedOn": "2025-08-29T18:58:17.640Z",
  "verifiedOn": "2025-08-29T18:58:17.640Z",
  "isPep": true,
  "isPepRelated": true,
  "isSanction": true,
  "riskLevel": "LOW",
  "naturalPersonStatus": "CREATED",
  "naturalPersonIdentifications": [
    {
      "identificationId": "123e4567-e89b-12d3-a456-426614174000",
      "createdOn": "2025-08-29T18:58:17.640Z",
      "modifiedOn": "2025-08-29T18:58:17.640Z",
      "externalVerifier": "WEB_ID",
      "identificationType": "VIDEO_IDENT",
      "identificationDate": "2025-08-29",
      "identificationDocumentType": "ID",
      "documentNumber": "text",
      "documentCountry": "AF",
      "documentIssuer": "text",
      "documentIssueDate": "2025-08-29",
      "documentExpiryDate": "2025-08-29",
      "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-08-29T18:58:17.640Z",
      "modifiedOn": "2025-08-29T18:58:17.640Z"
    }
  ],
  "gender": "MALE",
  "title": "PROFESSOR",
  "firstName": "text",
  "lastName": "text",
  "maritalStatus": "MARRIED",
  "birthDay": "2025-08-29",
  "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

501

Not Implemented

application/json

patch

HTTPcURLJavaScriptPython

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: 919

{
  "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",
    "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-08-29"
  },
  "documentId": "123e4567-e89b-12d3-a456-426614174000"
}

No content

Create Natural Person Identification

post

Create new natural person identification

Authorizations

Path parameters

naturalPersonIdstring · uuidRequired

Natural Person ID

Header parameters

Requestor-IDstring · uuidRequired

Unique requestor identification in UUID format

Body

externalVerifierstring · enumRequired

The legal name of the vendor/company performing the identification for this natural person

Possible values:

identificationTypestring · enumRequired

Method used to identify the customer

Possible values:

identificationDatestring · dateRequired

Date on which the identification was carried out. The date must be within the last 24 months.

identificationDocumentTypestring · enumRequired

Type of the identification document which has been used for identification of the natural person.

Possible values:

documentNumberstring · min: 1 · max: 255Required

Document number of the identification document.

documentCountrystring · enumRequired

Issuing country of the identification document.

Possible values:

documentIssuerstring · min: 1 · max: 255Required

Issuing authority of the identification document

documentIssueDatestring · dateRequired

Issue date of the identification document

documentExpiryDatestring · dateRequired

Expiry date of the identification document. If the identification document is a birth certificate, the date on which the person comes of age must be entered as the expiry date.

documentMotherFullNamestring · min: 1 · max: 255Optional

Full name of the mother, only mandatory for identificationDocumentType = BIRTH_CERTIFICATE

documentMotherResidenceCitystring · min: 1 · max: 255Optional

Residence city of the mother, only mandatory for identificationDocumentType = BIRTH_CERTIFICATE

documentFatherFullNamestring · min: 1 · max: 255Optional

Full name of the father, only mandatory for identificationDocumentType = BIRTH_CERTIFICATE

documentFatherResidenceCitystring · min: 1 · max: 255Optional

Residence city of the father, only mandatory for identificationDocumentType = BIRTH_CERTIFICATE

Responses

202

Accepted

400

Bad Request

application/json

501

Not Implemented

application/json

post

HTTPcURLJavaScriptPython

POST /entities/natural-persons/{naturalPersonId}/identification 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: 408

{
  "externalVerifier": "WEB_ID",
  "identificationType": "VIDEO_IDENT",
  "identificationDate": "2025-08-29",
  "identificationDocumentType": "ID",
  "documentNumber": "text",
  "documentCountry": "AF",
  "documentIssuer": "text",
  "documentIssueDate": "2025-08-29",
  "documentExpiryDate": "2025-08-29",
  "documentMotherFullName": "text",
  "documentMotherResidenceCity": "text",
  "documentFatherFullName": "text",
  "documentFatherResidenceCity": "text"
}

No content