Go directly to contents.
Suomi.fi e-Authorizations

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

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

Calling the interface

The OrganizationalRoles interface provided by the Suomi.fi e-Authorizations service is used to check whether a person has the right to act on behalf of a company and what kind of role they have in relation to the company. 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.

Interface

Description

WSDL

OrganizationalRoles

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

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

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 OrganizationalRoles interface

Request message

A request sent to the OrganizationalRoles interface contains two elements:

  • The delegateIdentifier element identifies the person whose mandate to act on behalf of a company is being checked.
  • The organizationIdentifier element identifies the company on whose behalf the person wants to act.

There can be several organizationIdentifier elements in a request message, which means that a single request message can be used to check mandates granted by several companies.

Principal element

Element name

Description

Domain

request





delegateIdentifier

Unique identifier of the agent. This information is required.

personal identity code or UID


organizationIdentifier

The identifier of the organisation being retrieved. There may be several.

business ID

Response message

As a response to the request message, the OrganizationalRoles interface returns a list (organizationList) of companies associated with the agent and the agent’s roles in them. If any of the roles remain unspecified, for example because of a remote call time out, the returned value for the exceptionMessage field in the response will be ‘incomplete’. If an error occurs during the processing of the request, the reason for the error is returned in the exceptionMessage field.

Principal element

Element name

Description

Domain

response





organizationList

List of companies that have granted a mandate.

list n*[organization] or empty


exceptionMessage

Possible error message.

String. The value is ‘incomplete’ if some of the roles remain unspecified.

This table describes the details of the organizationList element. OrganizationList contains one or more organization elements that indicate the business ID and name of the company that granted the mandate and a list of the agent’s roles in the company.

Principal element

Element name

Description

Domain

organizationList





organization

The company that granted the mandate and the roles of the agent.

organizationIdentifier, name, roles

This table describes the details of the ‘organization’ element. It contains three elements: organizationIdentifier, name and roles. OrganizationIdentifier indicates the business ID of the company that granted the mandate, and ‘name’ indicates the name of the company. ‘Roles’ indicates the roles that the agent has in the company.

Principal element

Element name

Description

Domain

organization





organizationIdentifier

Identifier of the organisation that granted the mandate.

business ID


name

Name of the company that granted the mandate.

company name


roles

List of the agent’s roles in the company.

List n*[role [”NIMKO”, ”TJ”, String]]

If the role element contains a URI, the content may contain character entity references. For example, the & symbol is in this case represented as

&

If a response features specifiers in the URI of a mandate theme, the keys and values of the specifiers are displayed in a URL-encoded format.

On specifiers

The types and names of specifiers are defined in the mandate theme code set. If specifiers have been defined for a mandate theme, they are added in the response after the mandate theme identifier as key value pairs:

  1. The value of a PRINCIPAL_ID type specifier indicates the assignor’s identifier.
  2. The significance of the value of a DEFAULT type specifier depends on the context, so the system does not address it.

The response in the message example below has a principalId qualifier of type PRINCIPAL_ID. Its value indicates the assignor. The response also includes a subOrganization specifier of type DEFAULT. Based on the name of the specifier, the mandate is limited to a specific sub-organisation.

If authority was received through a mandate to represent, the business ID of the company that is being represented is attached as a fragment to the mandate theme. For example, http://valtuusrekisteri.suomi.fi/palkkatietojen-ilmoittaminen#1234567-1 indicates that the original mandate has been granted to 1234567-1, who have granted the mandate to represent to the agent subject to the request.

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 person’s mandate to act on behalf of a company.

OrgRoles – Retrieving the company roles of a person acting on behalf of a company

<!-- 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>xxxxxxx-x</ns3:memberCode>
            <ns3:subsystemCode>subsys</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>xxxxxxx-x</ns3:memberCode>
            <ns3:subsystemCode>subsys</ns3:subsystemCode>
            <ns3:serviceCode>rovaOrganizationalRolesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns2:rovaOrganizationalRolesService
            xmlns:ns2="http://xml.vrk.fi/ws/Rova/OrgRoles/Entities" xmlns:ns3="http://x-road.eu/xsd/identifiers"
            xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
                <!--
                <organizationIdentifier>aaaaaaa-a</organizationIdentifier>
                <organizationIdentifier>bbbbbbb-b</organizationIdentifier>
                -->
            </request>
        </ns2:rovaOrganizationalRolesService>
    </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">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 ns3:objectType="SUBSYSTEM" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
         <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
         <ns3:memberClass>COM</ns3:memberClass>
         <ns3:memberCode>xxxxxxx-x</ns3:memberCode>
         <ns3:subsystemCode>subsys</ns3:subsystemCode>
      </client>
      <service ns3:objectType="SERVICE" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
         <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
         <ns3:memberClass>COM</ns3:memberClass>
         <ns3:memberCode>xxxxxxx-x</ns3:memberCode>
         <ns3:subsystemCode>subsys</ns3:subsystemCode>
         <ns3:serviceCode>rovaOrganizationalRolesService</ns3:serviceCode>
         <ns3:serviceVersion>v1</ns3:serviceVersion>
      </service>
      <ns3:requestHash algorithmId="http://www.w3.org/2001/04/xmlenc#sha512" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd">fhN8bdnbHRPjbYEbm7rannc0oImF9szcU4+bXZVpIRCCzUcMlNIZhjt2I0NNwXK7vacVsuOiFLXMsIm4DvzoTw==</ns3:requestHash>
   </SOAP-ENV:Header>
   <S:Body>
      <ns4:rovaOrganizationalRolesServiceResponse 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/OrgRoles/Entities">
         <request>
            <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
         </request>
         <response>
            <organizationList>
               <organization>
                  <organizationIdentifier>aaaaaaa-a</organizationIdentifier>
                  <name>Maanrakennus Ari Eerola T:mi</name>
                  <roles>
                     <role>NIMKO</role>
                  </roles>
               </organization>
               <organization>
                  <organizationIdentifier>bbbbbbb-b</organizationIdentifier>
                  <name>Rova Oy 1</name>
                  <roles>
                     <role>NIMKO</role>
                  </roles>
               </organization>
               <organization>
                  <organizationIdentifier>ccccccc-c</organizationIdentifier>
                     <name>Pasilan Puu ja Pallo</name>
                     <roles>
                        <role>http://valtuusrekisteri.suomi.fi/palkkatietojen-ilmoittaminen?principalId=ccccccc-c&amp;subOrganization=123</role>
                        <role>http://valtuusrekisteri.suomi.fi/palkkatietojen-ilmoittaminen?principalId=ccccccc-c&amp;subOrganization=a%26b</role>
                     </roles>
               </organization>
            </organizationList>
         </response>
      </ns4:rovaOrganizationalRolesServiceResponse>
   </S:Body>
</S:Envelope>
Updated: 12/11/2024

Are you satisfied with the content on this page?