Go directly to contents.
Suomi.fi e-Authorizations

Interface description of the mandate check query when a company is acting on behalf of a person – OrganizationalPersonMandates query

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

Calling the interface

The OrganizationalPersonMandates interface provided by the e-Authorizations service is used to check whether a company has the right to act on behalf of a person 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 OrganizationalPersonMandates interface.

Interface

Description

WSDL

OrganizationalPersonMandates

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

orgpersonmandates.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 OrganizationalPersonMandates interface

Request message

A request sent to the OrganizationalPersonMandates interface contains two elements:

  • The delegate element identifies the company whose mandate to act on behalf of a person is being checked.
  • The principal element identifies the person on whose behalf the 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 persons.

This table describes the key information of a request message sent to the OrganizationalPersonMandates 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 person who granted the mandate. There can be several elements. This information is required.

personal identity code or UID

Response message

As a response to the request message, the OrganizationalPersonMandates interface returns a list (principalList) of mandates granted to the company acting on behalf of the person. The mandates are grouped according to which mandates each person has granted to a company acting on their 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 OrganizationalPersonMandates interface.

Principal element

Element name

Description

Domain

response





principalList

List of persons who 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 personal identity code or UID of the person who granted the mandate and the themes that the mandate concerns.

Principal element

Element name

Description

Domain

principalList





principal

The person who granted mandates and the mandates they granted.

principal, issue

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

  • PrincipalId indicates the personal identity code or UID of the person who granted the mandate.
  • Issue describes what theme(s) the person authorised the company to address.
  • Incomplete indicates whether all rules could be checked for the person who granted the mandate.

Principal element

Element name

Description

Domain

principal





principalId

Unique identifier of the person who granted the mandate.

personal identity code or UID


issue

Granted mandate. There can be several elements. If there are no mandates or if the person who granted the mandate is not eligible for representation, the element is omitted.

mandate theme


incomplete

If one or more rules related to the person who granted the mandate have not been checked because of an error, the value is true, otherwise false.

boolean

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 a person.

OrgPersonMandates - Retrieving the person mandates of an organisation using the service.

<!-- 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>kaparova</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>rovaOrgPersonMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns2:rovaOrgPersonMandatesService xmlns:ns2="http://xml.vrk.fi/ws/Rova/OrgPersonMandates/Entities" xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegate>aaaaaaa-a</delegate>
                <principal>ppkkvv-aaaa<</principal>
                <principal>ppkkvv-bbbb<</principal>
                <principal>ppkkvv-cccc<</principal>
            </request>
        </ns2:rovaOrgPersonMandatesService>
    </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>kaparova</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>rovaOrgPersonMandatesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns4:rovaOrgPersonMandatesServiceResponse 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>ppkkvv-aaaa</principal>
                <principal>ppkkvv-bbbb</principal>
                <principal>ppkkvv-cccc</principal>
            </request>
            <response>
                <principalList>
                    <principal>
                        <principalId>ppkkvv-aaaa</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>ppkkvv-bbbb</principalId>
                        <incomplete>false</incomplete>
                    </principal>
                    <principal>
                        <principalId>ppkkvv-cccc</principalId>
                        <incomplete>true</incomplete>
                    </principal>
                </principalList>
            </response>
        </ns4:rovaOrgPersonMandatesServiceResponse>
    </S:Body>
</S:Envelope>
Updated: 5/11/2024

Are you satisfied with the content on this page?