REST API 2.1 - CustomerID

Owned by John Jellema
Last updated: 2024-12-03

Last reviewed: 2021-07-22


XML Schema

 Click here to expand...
<?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

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

friendlyName

String




Human readable name of the organization.

organizationType

String from Configured Set




Organization type defining the initial configuration of the created organization. Role to role mappings shall be refreshed based on role hierarchy rules only if the organization type is modified.

"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

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

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"
}

PUT125 Force Password Change for User

Description

Updates User so that they are forced to change password next time are logging in with a password method.

Works only when user repository is Ubilogin Directory. When user repository is Active Directory, an error response is returned with status code 404.

Target Type

None.

Request URL

Request URL defines the user to be forced to be change password based on the user ID of the user.

Example

Request Method

PUT

Request URL Parameters

No request specific request URL parameters.

Curl Example

Response Status

204 No Content

Response Document

None.

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.

Examples

  • https://HOSTNAME/customerid-rest/services/2.1/users/
  • https://HOSTNAME/customerid-rest/services/2.1/users?attributeName=attributeValue&attribute2Name=attribute2Value

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

<any user attribute name>

String




Include only users with exact matching search criteria value for the specified attribute name(s). You may use any of the builtin or custom attribute names here. The value given is searched from the attribute defined. You may use multiple different attribute names (and limiting search criteria values) in a single query (all must then match for the result to be returned). You cannot use the same attribute name multiple times in a single query.

You can also search by user status. Use either the status code or the status technical name. For example "pending" is equally suitable as "0". See Data model - CustomerID for a list of user statuses.

maxResults

Integer



No Limit

Limit the maximum number of results. A value of zero means no limit.

exactMatch

Boolean



false

When limiting attribute values are used, this parameter defines if the value must be found exactly like given (true) or if the database value just needs to start with the given value (false).

Curl Examples

List all users

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/users/"

List all pending users

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/users?status=0"

List all enabled users

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/users?status=Enabled"

Response Document

List of Identifiers

<Users xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users" method="GET">
 <Id>USERID1</Id>
 <Id>USERID2</Id>
</Users>

GET113 List Organization's Users

Description

List users from an organization. You can limit the returned users based on given search criteria.

Target Type

Collection

Request URL

Request URL defines the organization which users are to be listed and possibly the search criteria.

Examples

  • https://HOSTNAME/customerid-rest/services/2.1/organizations/ORGANIZATIONID/users
  • https://HOSTNAME/customerid-rest/services/2.1/organizations/ORGANIZATIONID/users?attributeName=attributeValue&attribute2Name=attribute2Value

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

recursive

Boolean



false

Include users from the suborganizations.

<any user attribute name>

String




Include only users with exact matching search criteria value for the specified attribute name(s). You may use any of the builtin or custom attribute names here. The value given is searched from the attribute defined. You may use multiple different attribute names (and limiting search criteria values) in a single query (all must then match for the result to be returned). You cannot use the same attribute name multiple times in a single query.

You can also search by user status . Use either the status code or the status technical name. For example "pending" is equally suitable as "0". See Data model - CustomerID for a list of user status es.

maxResults

Integer



No Limit

Limit the maximum number of results. A value of zero means no limit.

Curl Example

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/organizations/XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/users/?recursive=true"

Response Document

List of Identifiers

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

GET105 Query User

Description

Query information about the specified user based on the user ID of the user.

Target Type

Entity

Request URL

Request URL defines the queried user based on the user ID of the user.

Example

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

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

curl --insecure -X GET -u restuser:secret "https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Response Document

<?xml version="1.0" encoding="utf-8"?>
 <User xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" method="GET">
   <Attribute name="id">
     <Value>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</Value>
   </Attribute>
   <Attribute name="firstname">
     <Value>Firstname</Value>
   </Attribute>
   <Attribute name="surname">
     <Value>Lastname</Value>
   </Attribute>
   <Attribute name="mobile">
     <Value>+0123456789</Value>
   </Attribute>
   <Attribute name="cn">
     <Value>YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY</Value>
   </Attribute>
   <Attribute name="login">
     <Value>firstname.lastname</Value>
   </Attribute>
   <Attribute name="email">
     <Value>firstname.lastname@example.org</Value>
   </Attribute>
   <Attribute name="ssn">
     <Value>010199-1234</Value>
   </Attribute>
   <Attribute name="organization">
     <Value>My Subsidiary</Value>
   </Attribute>
   <Attribute name="organizationEntityName">
     <Value>5555555-6/1234567-1</Value>
   </Attribute>
   <Attribute name="organizationId">
     <Value>ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZZZZZ</Value>
   </Attribute>
   <Attribute name="status">
     <Value>Enabled</Value>
   </Attribute>
</User>

Supported values

  • Status: See Data model - CustomerID for a list of user statuses.
  • Attributes: Includes user's all attributes (including custom attributes).

Subpaths

  • Role invitations (GET114): https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/roleinvitations
  • Received mandates (GET121): https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandates
  • Given mandates (GET120): https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/givenmandates
  • Received mandate delegations (GET122): https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandatedelegations
  • Received roles (GET117): https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/roles

GET106 List Organizations

Description

List organizations.

Target Type

Collection

Request URL

Request URL points to the root of organizations container.

Examples

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

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entityName

Entity Name




Search organization by its entity name.

technicalName

String




Search organization by its technical name.

friendlyName

String




Search organizations by their friendly name.

organizationType

String from Configured Set




Search organizations by their organization type.

<any organization attribute name>

String




Include only organizations with matching search criteria value for the specified attribute name(s). You may use any of the builtin or custom attribute names here that are present in GET107 output. The value given is searched from the attribute defined. You may use multiple different attribute names (and limiting search criteria values) in a single query (all must then match for the result to be returned). You cannot use the same attribute name multiple times in a single query.

exactMatch

Boolean



false

When limiting attribute values are used, this parameter defines if the value must be found exactly like given (true) or if the database value just needs to start with the given value (false).

Try to avoid creating too large or complex queries as they may affect the overall performance of the system. For example before adding several custom attributes to limit results, check the performance impact first in the test environment.

Curl Example

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/organizations/"

Response Document

List of Identifiers

<Organizations xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/organizations/" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</Id>
 <Id>YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY</Id>
</Organizations>

GET107 Query Organization

Description

Query information about the specified organization.

Target Type

Entity

Request URL

Request URL defines the queried organization.

Examples

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

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

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

Response Document

<?xml version="1.0" encoding="utf-8"?>
<Organization xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" method="GET">
  <Attribute name="entityName">
    <Value>Organization/EntityName</Value>
  </Attribute>
  <Attribute name="friendlyName">
    <Value>Organization Friendly Name</Value>
  </Attribute>
  <Attribute name="organizationClass">
    <Value>organization type</Value>
  </Attribute>
  <Attribute name="memberships">
    <Value>memberships</Value>
  </Attribute>
  <Attribute name="customAttribute">
    <Value>attributeValue</Value>
  </Attribute>
</Organization>

Subpaths

  • Given mandates (GET118): https://HOSTNAME/customerid-rest/services/2.1/organizations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/givenmandates
  • Received mandates (GET119): https://HOSTNAME/customerid-rest/services/2.1/organizations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandates

GET108 List Roles

Description

List roles in the system.

Target Type

Collection

Request URL

  • https://HOSTNAME/customerid-rest/services/2.1/roles

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/roles"

Response Document

<Roles xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://HOSTNAME/customerid-rest/services/2.1/roles" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX3</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX4</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX5</Id>
</Roles>

GET117 List User's Roles

Description

List roles that the defined user is a member of.

Target Type

Collection

Request URL

  • https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/roles

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

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

Response Document

<Roles xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/roles" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX3</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX4</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX5</Id>
</Roles>

GET109 Query Role

Description

Query information about the specified role.

Target Type

Entity

Request URL

Request URL defines the queried role.

Example

  • https://HOSTNAME/customerid-rest/services/2.1/roles/ROLEID

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

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

Response Document

<Role xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.1/roles/ROLEID" method="GET">
 <Attribute name="name">
    <Value>ROLENAME</Value>
 </Attribute>
 <Attribute name="entityName">
    <Value>1234567-1/ROLENAME</Value>
 </Attribute>
</Role>

GET110 List Mandates

Description

List all mandates in the system.

Target Type

Collection

Request URL

Example

  • https://HOSTNAME/customerid-rest/services/2.1/mandates/

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entities

Boolean



false

Return list of entities instead of id list.

Curl Example

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/mandates/"

Response Document

<Mandates xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/mandates" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</Mandates>

GET118 List Organization's Given Mandates

Description

List mandates given by the defined organization.

Target Type

Collection

Request URL

Example

  • https://HOSTNAME/customerid-rest/services/2.1/organizations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/givenmandates

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entities

Boolean



false

Return list of entities instead of id list.

Curl Example

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

Response Document

<Mandates xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/organizations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/givenmandates" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</Mandates>

GET119 List Organization's Received Mandates

Description

List mandates received by the defined organization.

Target Type

Collection

Request URL

Example

  • https://HOSTNAME/customerid-rest/services/2.1/organizations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandates

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entities

Boolean



false

Return list of entities instead of id list.

Curl Example

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

Response Document

<Mandates xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/organizations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandates" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</Mandates>

GET120 List User's Given Mandates

Description

List mandates given by the defined user.

Target Type

Collection

Request URL

Example

  • https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/givenmandates

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entities

Boolean



false

Return list of entities instead of id list.

Curl Example

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

Response Document

<Mandates xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/givenmandates" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</Mandates>

GET121 List User's Received Mandates

Description

List mandates received by the defined user.

Target Type

Collection

Request URL

Example

  • https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandates

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entities

Boolean



false

Return list of entities instead of id list.

Curl Example

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

Response Document

<Mandates xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandates" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</Mandates>

GET122 List User's Received Mandate Delegations

Description

List mandates delegated to the defined user.

Target Type

Collection

Request URL

Example

  • https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandatedelegations

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entities

Boolean



false

Return list of entities instead of id list.

Curl Example

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

Response Document

<Mandates xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/receivedmandatedelegations" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</Mandates>

GET111 Query Mandate

Description

Query information about the specified mandate.

Target Type

Entity

Request URL

Request URL defines the queried mandate.

Example

  • https://HOSTNAME/customerid-rest/services/2.1/mandates/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Request Method

GET

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

entities

Boolean



false

Include referenced objects as entities instead of just ID references.

Curl Example

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/mandates/e8bba13e-e965-4042-af70-2b51d59359a2"

Response Document

<Mandate inResponseTo="/2.1/mandates/e8bba13e-e965-4042-af70-2b51d59359a2" method="GET">
 <Attribute name="id">
  <Value>e8bba13e-e965-4042-af70-2b51d59359a2</Value>
 </Attribute>
 <Attribute name="type">
  <Value>OrgToPer</Value>
 </Attribute>
 <Attribute name="entityName">
  <Value>Test%20User4z8y6pkhpya89zde5drs</Value>
 </Attribute>
 <Attribute name="name">
  <Value>Test User4z8y6pkhpya89zde5drs</Value>
 </Attribute>
 <Attribute name="assigneeEmail">
  <Value>test.user@example.org</Value>
 </Attribute>
 <Attribute name="mandater" type="organization">
  <Value>eb74ea0e-06f3-4575-aea0-13538e167e5f</Value>
 </Attribute>
 <Attribute name="mandatee" type="user">
  <Value>08a644dc-e6b4-4079-a636-5f378d876ee8</Value>
 </Attribute>
 <Attribute name="role" type="role">
  <Value>283cee64-2b42-4052-906a-9fa683829312</Value>
 </Attribute>
</Mandate>

GET112 List Role Invitations

Description

List role invitations.

Target Type

Collection

Request URL

Request URL defines that we want to list all role invitations.

Example

  • https://HOSTNAME/customerid-rest/services/2.1/roleinvitations/

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

curl --insecure -X GET -u restuser:secret "https://localhost:7443/customerid-rest/services/2.1/roleinvitations"

Response Document

<RoleInvitations xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/roleinvitations" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</RoleInvitations>

GET114 List Role Invitations (for user)

Description

List role invitations for user.

Target Type

Collection

Request URL

Request URL defines the user whose role invitations are to be listed.

Example

  • https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/roleinvitations

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

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

Response Document

<RoleInvitations xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/roleinvitations" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</RoleInvitations>

GET115 List Received Mandate Role Delegations (for user)

Description

List mandate role delegations for user.

Target Type

Collection

Request URL

Request URL defines the user whose mandate role delegations are to be listed.

Example

  • https://HOSTNAME/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/delegations

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

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

Response Document

<Delegations xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/users/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/delegations" method="GET">
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1</Id>
 <Id>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX2</Id>
</Delegations>

GET116 Query Mandate Role Delegation

Description

Query mandate role delegation.

Target Type

Collection

Request URL

Request URL defines the delegation which data should be retrieved.

Example

  • https://HOSTNAME/customerid-rest/services/2.1/delegations/XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX

Request Method

GET

Request URL Parameters

No request specific request URL parameters.

Curl Example

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

Response Document

<Delegation xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="https://localhost:7443/customerid-rest/services/2.1/delegations/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" method="GET">
 <Attribute name="role">
  <Value>ROLEID</Value>
 </Attribute>
 <Attribute name="mandatee">
  <Value>MANDATEEORGANIZATIONID</Value>
 </Attribute>
 <Attribute name="mandate">
  <Value>MANDATEID</Value>
 </Attribute>
 <Attribute name="mandateruser">
  <Value>USERID</Value>
 </Attribute>
 <Attribute name="mandaterorganization">
  <Value>ORGANIZATIONID</Value>
 </Attribute>
</Delegation>

This web page (including any attachments) may contain confidential, proprietary, or privileged information – not for disclosure without authorization from Ubisecure Inc. Copyright © 2024. All Rights Reserved.