Company Engagements

The Company Engagements API provides detailed insights into an individual’s involvement across different companies. It identifies their roles, such as CEO, board member, auditor, or external signatory, and displays a complete list of the companies they are engaged with. This data is valuable for understanding an individual’s professional reach, governance roles, and potential conflicts of interest. It supports organizations in assessing risks, ensuring compliance with regulations, and mitigating reputational harm.

Key Features:

• Access a list of companies associated with an individual.
• Identify the roles an individual holds, including board member, CEO, or auditor.
• Streamline customer onboarding and enhance the quality of customer data.
• Ensure compliance by verifying roles for AML/KYC checks.

Use case:

• A bank is onboarding a new B2B client. To ensure the individual representing the company is not involved with any high-risk entities, the bank uses the Company Engagements API to check the individual's directorships and board positions across other companies.

• A municipality uses the company engagement API to track all board or executive roles of individuals affiliated with potential vendors. This helps uncover cross-company ties that could signal conflicts of interest in the procurement process.

Below is a list of available Role codes for roles that persons can have in a company. The information is displayed as a code with a descriptive text.

The history endpoint now supports optional pagination. This solves timeouts and errors when fetching large histories (e.g., accountants with hundreds of engagement changes).

How to use it

Add page to your request to enable pagination:

GET /se/company/engagement/3.0/history/{personalNumber}?page=1&pageSize=10

The response includes a pagination object:

{
  "records": [...],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalPages": 17,
    "totalRecords": 167,
    "maxPageSize": 30,
    "paginationToken": "eyJpZCI6..."
  },
  "status": { "code": 0, "text": "records found" }
}

To get the next page for free (no additional billing), pass the paginationToken from the response:

GET /history/{personalNumber}?page=2&pageSize=10&paginationToken={token}

Parameters

Key points

• Only the first page is billed. All follow-up pages with a valid token are free (0 credits).
• The token works for any page — you can go forward, backward, or jump to any page number.
• Without page, nothing changes — existing integrations are unaffected.
• The token expires after 1 hour. Request a new first page to get a fresh token.
• Records are sorted newest first (most recent changes on page 1).

Page Size

You may specify pageSize (default: 20, max: 500). For most entities, your requested size is respected exactly. For entities with very large records (e.g., accountants with hundreds of company engagements per version), the server may reduce the effective pageSize to ensure response stability.

Guarantees:

• pagination.pageSize always shows the actual page size used
• pagination.maxPageSize shows the maximum the server will accept for this entity
• pagination.totalPages is calculated from the effective page size — use it for loop termination
• The effective pageSize is consistent for the entire session

Recommendation: Omit pageSize to use the safe default (20). If you need more records per round-trip, you may request up to maxPageSize. Always use pagination.totalPages to determine how many pages to iterate — do not use records.length < pageSize as a "last page" indicator.

When does the server reduce pageSize?

Rarely. Only entities with very high engagement counts per version (< 0.1% of persons) experience reduction when using the default pageSize. If you explicitly request a large pageSize, the table below shows when reduction occurs:

Iterating all pages (integration example)

page = 1
token = None
all_records = []

while True:
    params = {"page": page, "pageSize": 20}
    if token:
        params["paginationToken"] = token
    
    response = api.get(f"/history/{pnr}", params=params)
    data = response.json()
    
    all_records.extend(data["records"])
    token = data["pagination"]["paginationToken"]
    
    if page >= data["pagination"]["totalPages"]:
        break
    page += 1

Errors

Without pagination (existing behavior)

If you don't provide the page parameter, the endpoint behaves exactly as before — returning the full result set in a single response. For entities with large histories (e.g., accountants or board members with many company engagements), the server returns a 400 error recommending you use pagination instead.

Specifically, a 400 is returned when:

• The person has more than 500 history versions (always requires pagination), or
• The person has more than 100 versions with a combined payload exceeding the size limit

For these persons, simply add ?page=1 to your request to switch to paginated mode.