Create person representation

Use case

In this example, we will show how to set up person representation. We will set a private person Trevor Tuum as a representative of the legal person, New company Ltd.

Use case data	API parameters with values
The personId of the New company Ltd is ID-3394.	...persons/ID-3394/relations

To create the representation rights, you can use the personId of the parent (legal person) or representative (dependant private person).

Use case data	API parameters with values
The identification number of the private person Trevor Tuum is DQ654327C.	"idNumber": "DQ654327C"
The private person is registered in the Great Britain.	"idCountryCode": "GB"
The private person is the representative of the New company Ltd.	"relationTypeCode": "REPRESENTATIVE"
The representation is in active status.	"statusCode": "ACTIVE"
The private person is the beneficiary owner of the company. Note: If the private person is not a benificiary owner of the company, set to false.	"beneficiary": true
The representation validity period. The date format: YYYY-MM-DD.	"representingRange": { "startDate": "2023-06-06", "endDate": "2023-06-13" }

It is possible to set up representation rights for one or multiple persons to represent a legal or another private person.

Sample API call

To set the representation rights, call the following endpoint.

https://person-api.sandbox.tuumplatform.com/api/v1/persons/{personId}/relations

Learn more about the create person representation endpoint details in the Tuum developer portal.

Sample request

Below is an example request body of the API call for creating person representation.

JSON

{
  "relationships": [
    {
      "idNumber": "DQ654327C",
      "idCountryCode": "GB",
      "relationTypeCode": "REPRESENTATIVE",
      "statusCode": "ACTIVE",
      "beneficiary": true,
      "representingRange": {
        "startDate": "2023-06-06",
        "endDate": "2023-06-13"
      }
    }
  ]
}

cURL

curl 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3394/relations' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTNUMjM6MDc6NDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODY2OTc2NjB9.Tt708jxWsjUQPurWItoY9QVqa2tb5PbnFBV-8voVRxY' \
-H 'Content-Type: application/json' \
-d '{
  "relationships": [
    {
      "idNumber": "DQ654327C",
      "idCountryCode": "GB",
      "relationTypeCode": "REPRESENTATIVE",
      "statusCode": "ACTIVE",
      "beneficiary": true,
      "representingRange": {
        "startDate": "2023-06-06",
        "endDate": "2023-06-13"
      }
    }
  ]
}'
```

Sample response

Below you will find an example response to the API call from above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": [
        {
            "personRelationshipId": "ID-1003",
            "parentPersonId": "ID-3394",
            "personId": "ID-3392",
            "relationTypeCode": "REPRESENTATIVE",
            "statusCode": "ACTIVE",
            "role": null,
            "percentageOfShares": null,
            "percentageOfSignature": null,
            "beneficiary": true,
            "representingRange": {
                "startDate": "2023-06-06",
                "endDate": "2023-06-13"
            },
            "additionalData": null,
            "validityRange": {
                "startTime": "2023-06-14T21:32:09.684826Z",
                "endTime": null
            },
            "parentIdNumber": null,
            "personIdNumber": null,
            "parent": {
                "personId": "ID-3394",
                "personTypeCode": "L",
                "statusCode": "ACTIVE",
                "statusCodeReason": null,
                "name": "New company Ltd",
                "givenName": null,
                "middleName": null,
                "surname": null,
                "birthDate": null,
                "creationDate": "2023-06-13",
                "deathDate": null,
                "liquidationDate": null,
                "inactivationDate": null,
                "registrationDate": null,
                "sex": null,
                "email": null,
                "customerTypeCode": null,
                "nationality": null,
                "taxResidencyCountry": null,
                "placeOfBirth": null,
                "countryOfBirth": null,
                "phoneCountryCode": null,
                "phoneNumber": null,
                "idNumber": "120045",
                "idCountryCode": "GB",
                "residencyCountryCode": null,
                "language": null,
                "educationCode": null,
                "activityCode": null,
                "housingTypeCode": null,
                "buildingTypeCode": null,
                "moveInDate": null,
                "maritalStatusCode": null,
                "dependantPersons": null,
                "employmentTimeCode": null,
                "fixedEmploymentLength": null,
                "businessAreaCode": null,
                "intraOrgCode": null,
                "tradingName": null,
                "webAddress": null,
                "pepExplanation": null,
                "legalForm": null,
                "businessModelDescription": null,
                "counterpartySectorCode": null,
                "forgotten": null,
                "usResident": false,
                "pep": false,
                "source": null,
                "tenantCode": "MB",
                "fullName": "New company Ltd"
            },
            "person": {
                "personId": "ID-3392",
                "personTypeCode": "P",
                "statusCode": "ACTIVE",
                "statusCodeReason": null,
                "name": null,
                "givenName": "Trevor",
                "middleName": "Harry",
                "surname": "Tuum",
                "birthDate": null,
                "creationDate": "2023-06-01",
                "deathDate": null,
                "liquidationDate": null,
                "inactivationDate": null,
                "registrationDate": null,
                "sex": null,
                "email": null,
                "customerTypeCode": null,
                "nationality": null,
                "taxResidencyCountry": null,
                "placeOfBirth": "Alabama",
                "countryOfBirth": null,
                "phoneCountryCode": null,
                "phoneNumber": null,
                "idNumber": "DQ654327C",
                "idCountryCode": "GB",
                "residencyCountryCode": null,
                "language": null,
                "educationCode": null,
                "activityCode": null,
                "housingTypeCode": null,
                "buildingTypeCode": null,
                "moveInDate": null,
                "maritalStatusCode": null,
                "dependantPersons": null,
                "employmentTimeCode": null,
                "fixedEmploymentLength": null,
                "businessAreaCode": null,
                "intraOrgCode": null,
                "tradingName": null,
                "webAddress": null,
                "pepExplanation": null,
                "legalForm": null,
                "businessModelDescription": null,
                "counterpartySectorCode": null,
                "forgotten": null,
                "usResident": false,
                "pep": false,
                "source": null,
                "tenantCode": "MB",
                "fullName": "Trevor Tuum"
            }
        }
    ]
}
```

Result

A new person relationship is created:

Parameter and value	Explanation
"personRelationshipId": "ID-1003"	The code ID-1003 is a unique identifier of the person relationship between a legal and a private person.
"parentPersonId": "ID-3394", "personId": "ID-3392", "relationTypeCode": "REPRESENTATIVE"	A legal person (New company Ltd) was set as a parent person. And a private person (Trevor Tuum) was added as a company representative.