Quick start

This page shows you how to make your first API call to Tuum. Follow these four steps to authenticate and start exploring.

1

Get your credentials

Contact the Tuum team or your organisation's designated representative to receive your username and password.

2

Identify the base URL

Select the base URL for your target environment. Tuum uses different subdomains for different APIs.

For the sandbox environment, use:

Auth API

https://auth-api.sandbox.tuumplatform.com

Person API

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

For organisation-specific environments, contact your Tuum representative for base URLs.

3

Authenticate

Use the base URL and your credentials to authenticate by calling the authentication API endpoint.

Request bash

curl -X POST 'https://auth-api.sandbox.tuumplatform.com/api/v1/employees/authorise' \
-H 'Content-Type: application/json' \
--data-raw '{
"username": "your_username",
"password": "your_password"
}'

Upon a successful authentication, you will receive a JWT.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDMtMDhUMDg6NDg6NDkiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2NzgyNjUzMjl9.G7rqNTJbeyMdMy1ZGwu1G7JRSvwAg084IiBYhOEz4I8"
    }
}

Save the token value – you will need it in Step 4.

4

Start making API calls

Include your JWT in the x-auth-token header for all API calls.

To create a person record, call the create person API endpoint.

Request bash

curl --location 'https://person-api.sandbox.tuumplatform.com/api/v2/persons' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjUtMDEtMTRUMTU6MDA6MzQiLCJleHAiOjE3MzY4NjY4MzQsInJvbGVzIjpbIkFETUlOIl19.Y80MTpnA-h5xQ-8W194W0h-I8SbhgOJoZApPbREBB-0' \
--header 'Content-Type: application/json' \
--data '{
    "personTypeCode": "P",
    "surname": "Tuum",
    "givenName": "Trevor",
    "identificationNumbers": [
        {
            "idNumber": "QQ123456B",
            "idCountryCode": "GB",
            "primary": true
        }
    ],
    "addresses": [
        {
            "addressTypeCode": "R",
            "countryCode": "GB",
            "cityCounty": "Broomhill",
            "street1": "85 Park End St",
            "zip": "NE65 0YW"
        }
    ]
}'

If your call is successful, you will receive the following response.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "personId": "ID-3726",
        "statusCode": "ACTIVE",
        "source": null,
        "tenantCode": "MB",
        "forgotten": false,
        "legalForm": null,
        "creationDate": "2025-01-14",
        "personalInfo": {
            "personTypeCode": "P",
            "givenName": "Trevor",
            "middleName": null,
            "surname": "Tuum",
            "name": null,
            "email": null,
            "phoneNumber": null,
            "phoneCountryCode": null,
            "residencyCountryCode": null,
            "sex": null,
            "nationality": null,
            "dependantPersons": null,
            "legalForm": 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,
            "businessAreaCodes": [],
            "businessModelDescription": null,
            "intraOrgCode": null,
            "counterpartySectorCode": null
        },
        "work": {
            "activityCode": null,
            "businessAreaCodes": [],
            "employmentTimeCode": null,
            "fixedEmploymentLength": null
        },
        "home": null,
        "addresses": [
            {
                "addressId": "ID-4870",
                "personId": "ID-3726",
                "addressTypeCode": "R",
                "street1": "85 Park End St",
                "street2": null,
                "cityCounty": "Broomhill",
                "stateRegion": null,
                "zip": "NE65 0YW",
                "countryCode": "GB",
                "moveInDate": null,
                "validityRange": {
                    "endTime": null,
                    "startTime": "2025-01-14T14:21:58.145Z"
                }
            }
        ],
        "documents": [],
        "relationships": [],
        "additionalContacts": [],
        "personGroupCodes": [],
        "identificationNumbers": [
            {
                "idNumberId": "ID-3715",
                "personId": "ID-3726",
                "idNumber": "QQ123456B",
                "idCountryCode": "GB",
                "validityRange": {
                    "endTime": null,
                    "startTime": "2025-01-14T14:21:58.291Z"
                },
                "primary": true
            }
        ],
        "taxNumbers": [],
        "accessRestricted": false,
        "fullName": "Trevor Tuum"
    }
}

Next steps

Decide what you would like to try next:

• Explore the Employee API to see RBAC in action:

  curl -X GET 'https://employee-api.sandbox.tuumplatform.com/api/v2/employees/{employeeId}' \
    --header 'x-auth-token: your-jwt-token'

Discover additional sample calls for the Employee API in the API cookbook, or browse all endpoints in the API explorer.

• Retrieve a person record you created:

  curl -X GET 'https://person-api.sandbox.tuumplatform.com/api/v2/persons/{personId}' \
    --header 'x-auth-token: your-jwt-token'

Discover additional sample calls for the Person API in the API cookbook, or browse all endpoints in the API explorer.

• Try domain-specific APIs:

  • Account API: Find examples in the Account API cookbook or browse endpoints in the Account API explorer.

  • Card API: Find examples in the Card API cookbook or browse endpoints in the Card API explorer.

  • Loan API: Find examples in the Loan API cookbook or browse endpoints in the Loan API explorer.