Go directly to contents.
Suomi.fi e-Authorizations

Interface description of the mandate check query when a company is acting on behalf of another company – OrganizationalMandates query

This article presents the interface description of a Suomi.fi e-Authorizations mandate check query where a company acts on behalf of another company. The article describes how to call the OrganizationalMandates interface used in the query and the content of the request and response messages.

Calling the interface

The OrganizationalMandates interface provided by the e-Authorizations service is used to check whether a company has the right to act on behalf of another company and for which themes. The interface is provided via the Data Exchange Layer (X-Road 6). In addition to the Data Exchange Layer connection, X-Road SOAP headers are used to identify the e-service (client header) and the end user (userId) in the e-Authorizations service.

This table describes the key information of the OrganizationalMandates interface.

Interface

Description

WSDL

OrganizationalMandates

Query on a company’s mandates to act on behalf of another company based on the company’s identifier.

orgmandates.wsdlOpens in a new window.

Note! Allowed interfaces are defined at the time of commissioning, so all offered interfaces may not be available to the client organisation.

Interface descriptions also refer to the following X-Road schema files:

X-Road 6 attributes

This table presents the X-Road 6 attributes that have to be set when calling the e-Authorizations service.

Field

Mandatory

Additional information

service (objectType=SERVICE)

x

Includes fields:
xRoadInstance, memberClass, memberCode, subSystemCode, serviceCode and serviceVersion.

client (objectType=SUBSYSTEM)

x

Includes fields:
xRoadInstance, memberClass, memberCode and subSystemCode.

userId

x

An identifier identifying the end user; not a personal identity code (e.g. assertion of an identification event).

id

x

Unique identifier identifying the query.

issue


If interface requests are related to the same event, they need to have the same issue tag.

Note! The required fields in the table may differ from the X-Road communication protocol.

Request and response messages of the OrganizationalMandates interface

Request message

A request sent to the OrganizationalMandates interface contains two elements:

  • The delegate element identifies the company whose mandate to act on behalf of another company is being checked.
  • The principal element identifies the company on whose behalf the other company wants to act. There can be several principal elements in a request message, which means that a single request message can be used to check mandates granted by several companies.

This table describes the key information of a request message sent to the OrganizationalMandates interface.

Principal element

Element name

Description

Domain

request





delegate

Unique identifier of the company that received the mandate. This information is required.

business ID


principal

Unique identifier of the company that granted the mandate. There can be several elements. This information is required.

business ID

Response message

As a response to the request message, the OrganizationalMandates interface returns a list (principalList) of mandates granted to the company acting on behalf of the other company. The mandates are grouped according to which mandates each company has granted to the company acting on its behalf. If an error occurs during the processing of the request, the reason for the error is returned in the exceptionMessage field.

This table describes the information in the response message sent by the OrganizationalMandates interface.

Principal element

Element name

Description

Domain

response





principalList

List of companies that have granted a mandate.

list n*[principal] or empty


exceptionMessage

Possible error message.

string

This table describes the details of the principalList element. PrincipalList contains one or more principal elements that indicate the business ID of the company that granted the mandate and the themes that the mandate concerns.

Principal element

Element name

Description

Domain

principalList





principal

The company that granted mandates and the mandates granted by it.

principal, issue

This table describes the details of the principal element. The principal element contains three elements:

  • PrincipalId indicates the business ID of the company that granted the mandate.
  • Issue describes what theme(s) the company authorised the other company to address.
  • Incomplete indicates whether all rules could be checked for the company that granted the mandate.

Principal element

Element name

Description

Domain

principal





principalId

Unique identifier of the company that granted the mandate.

business ID


issue

Granted mandate. There can be several elements. If there are no mandates, the element is omitted.

mandate theme


incomplete

If one or more rules related to a company that granted a mandate have not been checked, for example because of missing background register data, the value is true, otherwise false.


Example message

The following is an example of the themes in this article. It shows calling the interface and the request and response messages when checking a company’s mandate to act on behalf of another company.

OrgMandates – Retrieving a service user’s company mandates

<!-- request -->
<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <id xmlns="http://x-road.eu/xsd/xroad.xsd">6a85dd42-04e4-42fa-ae2a-0ae646ad0956</id>
        <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
        <userId xmlns="http://x-road.eu/xsd/xroad.xsd">kela-rova-user</userId>
        <client xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SUBSYSTEM">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova3</ns3:subsystemCode>
        </client>
        <service xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SERVICE">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova</ns3:subsystemCode>
            <ns3:serviceCode>rovaOrgMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns2:rovaOrgMandatesService xmlns:ns2="http://xml.vrk.fi/ws/Rova/OrgMandates/Entities" xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegate>aaaaaaa-a</delegate>
                <principal>bbbbbbb-b</principal>
                <principal>ccccccc-c</principal>
                <principal>ddddddd-d</principal>
            </request>
        </ns2:rovaOrgMandatesService>
    </S:Body>
</S:Envelope>

<!-- response -->
<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <id xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">6a85dd42-04e4-42fa-ae2a-0ae646ad0956</id>
        <requestHash xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">Ryi6rQMaG6BDbXoLCSZbriP5IRMw0EOABKnslSvGMNoBK89k5b0b8Qj3GK/2+BSJZ3jF7O2LkX5DGaobzdPIIg==</requestHash>
        <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">4.0</protocolVersion>
        <userId xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">kela-rova-user</userId>
        <client xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SUBSYSTEM">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova3</ns3:subsystemCode>
        </client>
        <service xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://x-road.eu/xsd/identifiers" ns3:objectType="SERVICE">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>aaaaaaa-a</ns3:memberCode>
            <ns3:subsystemCode>kaparova</ns3:subsystemCode>
            <ns3:serviceCode>rovaOrgMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns4:rovaOrgMandatesServiceResponse xmlns:ns2="http://x-road.eu/xsd/identifiers" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd" xmlns:ns4="http://xml.vrk.fi/ws/Rova/OrgMandates/Entities">
            <request>
                <delegate>aaaaaaa-a</delegate>
                <principal>bbbbbbb-b</principal>
                <principal>ccccccc-c</principal>
                <principal>ddddddd-d</principal>
            </request>
            <response>
                <principalList>
                    <principal>
                        <principalId>bbbbbbb-b</principalId>
                        <issue>http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu</issue>
                        <issue>http://valtuusrekisteri.suomi.fi/palkkatietojen_ilmoittaminen?principalId=8888888-3</issue>
                        <incomplete>false</incomplete>
                    </principal>
                    <principal>
                        <principalId>ccccccc-c</principalId>
                        <incomplete>false</incomplete>
                    </principal>
                    <principal>
                        <principalId>ddddddd-d</principalId>
                        <incomplete>true</incomplete>
                    </principal>
                </principalList>
            </response>
        </ns4:rovaOrgMandatesServiceResponse>
    </S:Body>
</S:Envelope>
Updated: 5/11/2024

Are you satisfied with the content on this page?