Last reviewed: 2021-07-22

1 XML Schema
2 Modification Operations
- 2.1 POST100 Create Organization
- 2.2 PUT101 Update Organization
- 2.3 DEL102 Delete User
- 2.4 PUT103 Update User
- 2.5 PUT123 Reinvite User
- 2.6 PATCH124 Update User
3 Request Operations
- 3.1 GET104 List Users
- 3.2 GET113 List Organization's Users
- 3.3 GET105 Query User
- 3.4 GET106 List Organizations
- 3.5 GET107 Query Organization
- 3.6 GET108 List Roles
- 3.7 GET117 List User's Roles
- 3.8 GET109 Query Role
- 3.9 GET110 List Mandates
- 3.10 GET118 List Organization's Given Mandates
- 3.11 GET119 List Organization's Received Mandates
- 3.12 GET120 List User's Given Mandates
- 3.13 GET121 List User's Received Mandates
- 3.14 GET122 List User's Received Mandate Delegations
- 3.15 GET111 Query Mandate
- 3.16 GET112 List Role Invitations
- 3.17 GET114 List Role Invitations (for user)
- 3.18 GET115 List Received Mandate Role Delegations (for user)
- 3.19 GET116 Query Mandate Role Delegation

XML Schema

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    version="2.1" xmlns="http://schema.ubisecure.com/customerid/api"
    targetNamespace="http://schema.ubisecure.com/customerid/api"
    elementFormDefault="qualified">
 
    <!-- core entity objects -->
    <xs:element name="User" type="EntityType" />
    <xs:element name="Organization" type="EntityType" />
    <xs:element name="Role" type="EntityType" />
    <xs:element name="Mandate" type="EntityType" />
    <xs:element name="Workflow" type="EntityType" />
    <xs:element name="Delegation" type="EntityType" />
 
    <!-- relation objects -->
    <xs:element name="MandateTemplate" type="EntityType" />
    <xs:element name="RoleInvitation" type="EntityType" />

    <!-- collections -->
    <xs:element name="Roles" type="IdListType" />
    <xs:element name="Mandates" type="IdListType" />
    <xs:element name="Users" type="IdListType" />
    <xs:element name="Organizations" type="IdListType" />
    <xs:element name="Workflows" type="IdListType" />
    <xs:element name="RoleInvitations" type="IdListType" />
    <xs:element name="MandateInvitations" type="IdListType" />
    <xs:element name="Delegations" type="IdListType" />
 
    <!-- specific request and response types -->
    <xs:element name="ReinviteResponse" type="ReinviteResponse" />
    <xs:element name="UserDTO" type="UserDTOType"/>
    <xs:element name="UserRequest" type="UserRequestType"/>
    <xs:element name="UserResponse" type="UserResponseType"/> 
 
    <xs:complexType name="EntityType">
        <xs:sequence>
            <xs:element name="Attribute" type="AttributeType"
                maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="inResponseTo" type="xs:anyURI"/>
        <xs:attribute name="method" type="httpMethod"/>
        <xs:attribute name="type" type="xs:string"/>
    </xs:complexType>

    <xs:complexType name="IdListType">
        <xs:annotation>
            <xs:documentation>
                Since customerid-rest-schema 2.0:
                roleInvitation contains a list of ids that are either
                relative or absolute URLs. inResponseTo attribute
                indicates what kind of query this message was produced
                by
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="Id" type="IdType" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element name="User" type="EntityType" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element name="Organization" type="EntityType" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element name="Role" type="EntityType" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element name="Mandate" type="EntityType" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element name="Delegations" type="EntityType" maxOccurs="unbounded" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="inResponseTo" type="xs:anyURI" />
        <xs:attribute name="method" type="httpMethod" use="required" />
    </xs:complexType>

    <xs:complexType name="AttributeType">
        <xs:choice>
            <xs:element name="Value" type="AttributeValueType" minOccurs="0" maxOccurs="unbounded"/>
            <xs:element name="Entity" type="EntityType" minOccurs="0" maxOccurs="unbounded"/>
        </xs:choice>
        <xs:attribute name="name" type="xs:string" />
    </xs:complexType>

    <xs:complexType name="AttributeValueType">
        <xs:simpleContent>
            <xs:extension base="xs:string">
                <xs:attribute name="type" type="xs:string" />
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
 
    <xs:simpleType name="IdType">
        <xs:restriction base="xs:string" />
    </xs:simpleType>

    <xs:simpleType name="httpMethod">
        <xs:restriction base="xs:token">
            <xs:enumeration value="GET" />
            <xs:enumeration value="PUT" />
            <xs:enumeration value="POST" />
            <xs:enumeration value="DELETE" />
            <xs:enumeration value="PATCH"/>
            <xs:enumeration value="UPDATE" />
            <xs:enumeration value="HEAD" />
            <xs:enumeration value="STATUS" />
            <xs:enumeration value="CONNECT" />
            <xs:enumeration value="OPTIONS" />
            <xs:enumeration value="TRACE" />
        </xs:restriction>
    </xs:simpleType>
 
    <xs:complexType name="ReinviteResponse">
        <xs:annotation>
            <xs:documentation>
                Specific response returned by REST API 2.1 users/{userId}/reinvite endpoint.
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="userId" type="xs:string" />
            <xs:element name="email" type="xs:string" />
        </xs:sequence>
        <xs:attribute name="inResponseTo" type="xs:anyURI" />
        <xs:attribute name="method" type="httpMethod" />
    </xs:complexType>

    <xs:complexType name="CustomAttributesType">
        <xs:sequence>
            <xs:element name="attribute" type="CustomAttribute" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="CustomAttribute">
        <xs:sequence>
            <xs:element name="value" type="xs:string" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="name" type="xs:string" use="required" />
    </xs:complexType>

    <xs:complexType name="UserDTOType">
        <xs:annotation>
            <xs:documentation>
                Base type which is common to request and response of REST API 2.1 PATCH users/{userId} endpoint.
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="firstname" type="xs:string" minOccurs="0" />
            <xs:element name="surname" type="xs:string" minOccurs="0" />
            <xs:element name="login" type="xs:string" minOccurs="0" />
            <xs:element name="email" type="xs:string" minOccurs="0" />
            <xs:element name="mobile" type="xs:string" minOccurs="0" />
            <xs:element name="ssn" type="xs:string" minOccurs="0" />
            <xs:element name="locale" type="xs:string" minOccurs="0" />
            <xs:element name="status" type="xs:string" minOccurs="0" />
            <xs:element name="customAttributes" type="CustomAttributesType" />
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="UserRequestType">
        <xs:annotation>
            <xs:documentation>
                Specific request for the REST API 2.1 PATCH users/{userId} endpoint.
            </xs:documentation>
        </xs:annotation>
        <xs:complexContent>
            <xs:extension base="UserDTOType">
                <xs:sequence>
                    <xs:element name="pwd" type="xs:string" minOccurs="0" />
                    <xs:element name="pwd.activated" type="xs:string" minOccurs="0" />
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    <xs:complexType name="UserResponseType">
        <xs:annotation>
            <xs:documentation>
                Specific response returned by REST API 2.1 PATCH users/{userId} endpoint.
            </xs:documentation>
        </xs:annotation>
        <xs:complexContent>
            <xs:extension base="UserDTOType">
                <xs:sequence>
                    <xs:element name="userId" type="xs:string" />
                    <xs:element name="repoId" type="xs:string" minOccurs="0" />
                    <xs:element name="organization" type="xs:string" minOccurs="0" />
                    <xs:element name="organizationEntityName" type="xs:string" minOccurs="0" />
                </xs:sequence>
                <xs:attribute name="inResponseTo" type="xs:anyURI" />
                <xs:attribute name="method" type="httpMethod" />
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>

    
</xs:schema>

Modification Operations

POST100 Create Organization

Description

Create a new organization.

Target Type

Collection

Request URL

Request URL should point to the root of the organizations collection.

Examples

https://HOSTNAME/customerid-rest/services/2.1/organizations/

Request Method

POST

Request URL Parameters

Name	Accepted Values	Multivalued	Mandatory	Default	Description

Name	Accepted Values	Multivalued	Default	Description
virtual	Boolean		false	Defines whether the organization is virtual.
technicalName	String		A generated value in UUID format.	Technical name of the organization to be created.
friendlyName	String		The same as technical name.	Human readable name of the organization.
parentOrganizationId	Organization ID		Root organization.	Organization ID of the organization under which the new organization will be created.
organizationType	String from Configured Set		The configured default organization type. A separate default exists for normal and virtual organizations.	Organization type defining the initial configuration of the created organization.
"custom attribute"	String	X		Organization's custom attribute and a value (multiple values are separated with comma). For example, vatnumber=12345

Curl Example

curl --insecure -X POST -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/organizations/?friendlyName=Luotava%20Organisaatio&parentOrganizationId=d9cbed24-d3b7-4611-ae8f-f0327eb60a48"

Response Document

<Organizations xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/organizations/" method="POST">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
</Organizations>

PUT101 Update Organization

Description

Update the organization data. Replaces all the defined attributes, empty value removes the attribute, and missing attribute does not change the existing value.

Target Type

Entity

Request URL

Request URL defines the organization to be updated.

Examples

https://HOSTNAME/customerid-rest/services/2.1/organizations/ORGANIZATIONID

Request Method

PUT

Request URL Parameters

Name	Accepted Values	Multivalued	Mandatory	Default	Description

Name	Accepted Values	Multivalued	Description
friendlyName	String		Human readable name of the organization.
organizationType	String from Configured Set		Organization type defining the initial configuration of the created organization.
"custom attribute"	String	X	Organization's custom attribute and a value (multiple values are separated with comma). These attributes must have been defined in eidm2.properties (data.organization.fields or ui.admin.organizationinfo.fields.order) For example, organizationid=12345

Curl Example

curl --insecure -X PUT -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/organizations/27e326f1-b6ad-46a6-917f-1c3c377c73ee?friendlyName=TestOrganizationRENAME"

Response Document

<Organizations xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/organizations/27e326f1-b6ad-46a6-917f-1c3c377c73ee" method="PUT">
 <Id>27e326f1-b6ad-46a6-917f-1c3c377c73ee</Id>
</Organizations>

DEL102 Delete User

Description

Delete the specified user.

Target Type

Entity

Request URL

Request URL defines the user to be deleted.

Example

https://HOSTNAME/customerid-rest/services/2.1/users/USERID

Request Method

DELETE

Request URL Parameters

No request specific request URL parameters.

Curl Example

curl --insecure -X DELETE -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Response Document

<Users xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" method="DELETE">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</Id>
</Users>

PUT103 Update User

Description

Update the user information. Replaces all the defined attributes, empty value removes the attribute, and missing attribute does not change the existing value.

Target Type

Entity

Request URL

Request URL defines the user to be updated based on the user ID of the user.

Example

https://HOSTNAME/customerid-rest/services/2.1/users/USERID1

Request Method

PUT

Request URL Parameters

Name	Accepted Values	Multivalued	Mandatory	Default	Description

Name	Accepted Values	Multivalued	Description
login	String		User login name.
email	String		User email address.
firstname	String		First name of the user.
surname	String		Surname of the user.
mobile	String		Mobile phone number.
ssn	String		Social Security Number (henkilötunnus)
locale	String		User preferred locale setting.
pwd	String		New password.
pwd.activated	Boolean		Defines if the password authentication method is active for the user or not.
status	String from Configured Set		Set the user status Enabled or Disabled. For more information on user statuses see Data model - CustomerID.
"custom attribute"	String	X	User's custom attribute and a value. For example, age=45. Adding multiple key-value parameters with the same key will create multi-valued attributes. For example, browsers=IE&browsers=chrome.

Curl Example

curl --insecure -X PUT -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX?mobile=+358401234567891&status=Enabled"

Response Document

<Users xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" method="PUT">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</Id>
</Users>

PUT123 Reinvite User

Description

Sends an remainder email for an unregistered user to register without waiting for the remainder period to be passed. There are two different kind of remainder mail messages that are applicable depending on how the initial invitation was made: email.inviteUserRenotify.user and email.inviteUserRenotify.role, see Email text localization.

The email is sent to the email address that is currently set for the user. If original invitation was sent to wrong address, update email address first for example with PUT103 Update User.

The user status must be Waiting for registration in order to be reinvited. This functionality does not support invitations related to mandates.

Target Type

ReinviteResponse

Request URL

Request URL defines the user to be reinvited based on the user ID of the user.

Example

https://HOSTNAME/customerid-rest/services/2.1/users/USERID1

Request Method

PUT

Request URL Parameters

No request specific request URL parameters.

Curl Example

curl --insecure -X PUT -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/reinvite

Response Document

When using media type application/xml in the Accept header (default)

<ReinviteResponse xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/7a2e00a8-cd4e-4ad2-bb99-164d3c5b004f/reinvite" method="PUT">
    <userId>7a2e00a8-cd4e-4ad2-bb99-164d3c5b004f</userId>
    <email>maija.virtanen@example.org</email>
</ReinviteResponse>

When using media type application/json in the Accept header

{
    "userId": "7a2e00a8-cd4e-4ad2-bb99-164d3c5b004f",
    "email": "maija.virtanen@example.org"
}

PATCH124 Update User

Description

Update the user information. Replaces all the defined attributes, empty value removes the attribute, and missing attribute does not change the existing value. Validates only updated attributes.

Target Type

UserResponse

Request URL

Request URL defines the user to be updated based on the user ID of the user.

Examples:

https://HOSTNAME/customerid-rest/services/2.1/users/USERID1

Request Method

PATCH

Request Parameters

PATCH124 Update User request can take data in 3 ways.

Form URL Encoded

With Content-Type header on application/x-www-form-urlencoded

Name	Accepted Values	Multivalued	Mandatory	Default	Description

Name	Accepted Values	Multivalued	Description
login	String		User login name.
email	String		User email address.
firstname	String		First name of the user.
surname	String		Surname of the user.
mobile	String		Mobile phone number.
ssn	String		Social Security Number (henkilötunnus)
locale	String		User preferred locale setting.
pwd	String		New password.
pwd.activated	Boolean		Defines if the password authentication method is active for the user or not.
status	String from Configured Set		Set the user status Enabled or Disabled. For more information on user statuses see Data model - CustomerID.
"custom attribute"	String	X	User's custom attribute and a value. For example, age=45. Adding multiple key-value parameters with the same key will create multi-valued attributes. For example, browsers=IE&browsers=chrome.

XML

With Content-Type header on application/xml

Custom Attributes are saved as multivalued. To add multiple value, add multiple values as shown below (Custom1). To remove custom attribute, give no values or give empty value.

<UserRequest xmlns="http://schema.ubisecure.com/customerid/api">
    <firstname>Firstname</firstname>
    <surname>Surname</surname>
    <login>Username</login>
    <email>email@example.com</email>
    <mobile>+358501234567</mobile>
    <ssn>111111-111C</ssn>
    <locale>en</locale>
    <status>Enabled</status>
    <pwd>Password1</pwd>
    <pwd.activated>true</pwd.activated>
    <customAttributes>
        <attribute name="Custom1">
			<value>Value1</value>
			<value>Value2</value>
		</attribute>
        <attribute name="Custom2">
            <value>Value3</value>
        </attribute>
    </customAttributes>
</UserPatchRequest>

JSON

With Content-Type header on application/json

Custom Attributes are saved as multivalued. To add multiple value, add multiple values as array (Custom1). To remove custom attribute, leave empty string as value.

{
    "firstname": "Firstname",
    "surname": "Surname",
    "login": "Username",
    "email": "email@example.com",
    "mobile": "+358501234567",
    "ssn": "111111-111C",
    "locale": "en",
    "status": "Enabled",
    "pwd": "Password1",
    "pwd.activated": "true",
    "customAttributes": {
        "Custom1": ["Value1", "Value2"]
		"Custom2": Value3
    },
}

Curl Example

curl --insecure -X PATCH -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'firstname=Example'

Response Document

When using media type application/xml in the Accept header (default)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<UserResponse xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" method="PATCH">
    <firstname>Firstname</firstname>
    <surname>Surname</surname>
    <login>Username</login>
    <email>email@example.com</email>
    <mobile>+358501234567</mobile>
    <ssn>111111-111C</ssn>
    <locale>en</locale>
    <status>Enabled</status>
    <customAttributes>
        <attribute name="Custom2">
            <value>Value3</value>
        </attribute>
        <attribute name="Custom1">
            <value>Value1</value>
            <value>Value2</value>
        </attribute>
    </customAttributes>
    <userId>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</userId>
    <repoId>YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY</repoId>
    <organization>Users</organization>
    <organizationEntityName>Users</organizationEntityName>
</User>

When using media type application/json in the Accept header

{
    "firstname": "Firstname",
    "surname": "Surname",
    "login": "Username",
    "email": "email@example.com",
    "mobile": "+358501234567",
    "ssn": "111111-111C",
    "locale": "en",
    "status": "Enabled",
    "customAttributes": {
        "Custom2": "Value3",
        "Custom1": [
            "Value1",
            "Value2"
        ]
    },
    "userId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "repoId": "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY",
    "organization": "Users",
    "organizationEntityName": "Users"
}

Request Operations

GET104 List Users

Description

List users in the system. You can limit the returned users based on given search criteria.

Target Type

Collection

Request URL

Request URL defines the search criteria. You may also list all users from the system by not using any limiting criteria values.

REST API 2.1 - CustomerID

XML Schema

Modification Operations

POST100 Create Organization

Description

Target Type

Request URL

Examples

Request Method

Request URL Parameters

Curl Example

Response Document

PUT101 Update Organization

Description

Target Type

Request URL

Examples

Request Method

Request URL Parameters

Curl Example

Response Document

DEL102 Delete User

Description

Target Type

Request URL

Example

Request Method

Request URL Parameters

Curl Example

Response Document

PUT103 Update User

Description

Target Type

Request URL

Example

Request Method

Request URL Parameters

Curl Example

Response Document

PUT123 Reinvite User

Description

Target Type

Request URL

Example

Request Method

Request URL Parameters

Curl Example

Response Document

PATCH124 Update User

Description

Target Type

Request URL

Request Method

Request Parameters

Form URL Encoded

XML

JSON

Curl Example

Response Document

Request Operations

GET104 List Users

Description

Target Type

Request URL

Examples