Create legal person

Use case

Here you can learn how to create a legal person - record of your customer's business organisation. In this example, we will use the following data:

Use case data	API parameters with values
Legal person	"personTypeCode": "L"
The company name is New company Ltd	"name": "New company Ltd"
The company registration address: Carnaby street 10, London, Great Britain, 13347	"addresses": [ { "addressTypeCode": "R", "street1": "Carnaby 10", "cityCounty": "London", "zip": "13347", "countryCode": "GB" } ]
The company registration number is 111111	"identificationNumber": { "idNumber": "111111", "idCountryCode": "GB" }

The private person is created with a minimal set of data. Find more information

Sample API call

To create a legal person, make the following API call.

https://person-api.sandbox.tuumplatform.com/api/v2/persons

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

Sample request

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

JSON

{
  "personTypeCode": "L",
  "name": "New company Ltd",
  "addresses": [
    {
      "addressTypeCode": "R",
      "street1": "Carnaby 10",
      "cityCounty": "London",
      "zip": "13347",
      "countryCode": "GB"
    }
  ],
  "identificationNumber": {
    "idNumber": "111111",
    "idCountryCode": "GB"
    }
 }

cURL

curl 'https://person-api.sandbox.tuumplatform.com/api/v2/persons' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTNUMjA6MDM6MDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODY2ODY1ODB9.bF0nEpm7Z1LgW08F9Fri-q1zAyDH5PsFwqhJCygdODQ' \
-H 'Content-Type: application/json' \
-d '{
  "personTypeCode": "L",
  "name": "New company Ltd",
  "addresses": [
    {
      "addressTypeCode": "R",
      "street1": "Carnaby 10",
      "cityCounty": "London",
      "zip": "13347",
      "countryCode": "GB"
    }
  ],
  "identificationNumber": {
    "idNumber": "111111",
    "idCountryCode": "GB"
    }
 }'

Sample response

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

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "personId": "ID-3397",
        "statusCode": "ACTIVE",
        "source": null,
        "tenantCode": "MB",
        "forgotten": false,
        "creationDate": "2023-06-13",
        "personalInfo": {
            "personTypeCode": "L",
            "givenName": null,
            "middleName": null,
            "surname": null,
            "name": "New company Ltd",
            "email": null,
            "phoneNumber": null,
            "phoneCountryCode": null,
            "residencyCountryCode": null,
            "sex": null,
            "nationality": null,
            "dependantPersons": null,
            "legalForm": null,
            "identificationNumber": {
                "idNumberId": "ID-1773",
                "personId": "ID-3397",
                "idNumber": "111111",
                "idCountryCode": "GB",
                "vatNumber": null,
                "taxNumber": null,
                "validityRange": {
                    "startTime": "2023-06-13T19:06:34.159654Z",
                    "endTime": null
                }
            }
        },
        "additionalInfo": {
            "birthDate": null,
            "countryOfBirth": null,
            "placeOfBirth": null,
            "language": null,
            "educationCode": null,
            "maritalStatusCode": null,
            "dependantPersons": null,
            "taxResidencyCountry": null,
            "usResident": false,
            "pep": false,
            "customerTypeCode": null,
            "statusCodeReason": null,
            "deathDate": null,
            "liquidationDate": null,
            "inactivationDate": null,
            "tradingName": null,
            "registrationDate": null,
            "webAddress": null,
            "pepExplanation": null,
            "businessModelDescription": null,
            "intraOrgCode": null,
            "counterpartySectorCode": null
        },
        "work": null,
        "home": null,
        "addresses": [
            {
                "addressId": "ID-3057",
                "personId": "ID-3397",
                "addressTypeCode": "R",
                "street1": "Carnaby 10",
                "street2": null,
                "cityCounty": "London",
                "stateRegion": null,
                "zip": "13347",
                "countryCode": "GB",
                "moveInDate": null,
                "validityRange": {
                    "startTime": "2023-06-13T19:06:34.057318Z",
                    "endTime": null
                }
            }
        ],
        "documents": [],
        "relationships": [],
        "additionalContacts": [],
        "personGroupCodes": [],
        "identificationNumbers": [
            {
                "idNumberId": "ID-1773",
                "personId": "ID-3397",
                "idNumber": "111111",
                "idCountryCode": "GB",
                "validityRange": {
                    "startTime": "2023-06-13T19:06:34.159654Z",
                    "endTime": null
                },
                "primary": true
            }
        ],
        "taxNumbers": [],
        "fullName": "New company Ltd"
    }
}

Result

A new legal person ID-3397 is created and activated. The legal person record is now available for the further actions.