/
REST API 1.2 - CustomerID

REST API 1.2 - CustomerID

2021-01-19

Last reviewed: 2019-08-12

Note: The term Remove used in in the APIs is exactly the same as the Delete function.  Calling any API with the Remove term will result in the associated data being deleted from the database. There is no recovery function for these Remove calls.


XML Schema

<?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="organization"> <xs:complexType> <xs:complexContent> <xs:extension base="organization-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="user"> <xs:complexType> <xs:complexContent> <xs:extension base="user-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="pendingUser"> <xs:complexType> <xs:complexContent> <xs:extension base="pendingUser-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="role"> <xs:complexType> <xs:complexContent> <xs:extension base="role-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="mandatetemplate"> <xs:complexType> <xs:complexContent> <xs:extension base="mandatetemplate-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="mandate"> <xs:complexType> <xs:complexContent> <xs:extension base="mandate-type"></xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="mandatelist"> <xs:complexType> <xs:sequence> <xs:element name="givenmandatelist" type="mandatelist-type" /> <xs:element name="receivedmandatelist" type="mandatelist-type" /> <xs:any namespace="##any" processContents="skip" /> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="givenmandatelist"> <xs:complexType> <xs:complexContent> <xs:extension base="mandatelist-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="receivedmandatelist"> <xs:complexType> <xs:complexContent> <xs:extension base="mandatelist-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="entitylist"> <xs:complexType> <xs:complexContent> <xs:extension base="entitylist-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="idlist"> <xs:complexType> <xs:complexContent> <xs:extension base="idlist-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="mandateidlist"> <xs:complexType> <xs:sequence> <xs:element name="givenmandateidlist" type="idlist-type" /> <xs:element name="receivedmandateidlist" type="idlist-type" /> <xs:any namespace="##any" processContents="skip" /> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="roleinvitation"> <xs:complexType> <xs:complexContent> <xs:extension base="roleinvitation-type" /> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="error"> <xs:complexType> <xs:sequence> <xs:element name="code" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="message" type="xs:string" minOccurs="0" maxOccurs="1" /> </xs:sequence> </xs:complexType> </xs:element> <!-- Type definitions --> <xs:complexType name="organization-type"> <xs:sequence> <xs:element name="id" type="xs:string" /> <xs:element name="virtual" type="xs:string" /> <xs:element name="friendlyName" type="xs:string" /> <xs:element name="technicalname" type="xs:string" /> <xs:element name="organizationClass" type="xs:string" /> <xs:element name="customattribute" type="customattribute-type" minOccurs="0" maxOccurs="unbounded" /> <xs:element name="memberships" type="memberships-type" /> <xs:element name="members" type="members-type" /> <xs:element name="roles" type="roles-type" /> <xs:element name="applicationCount" type="xs:string" /> <xs:element name="pendingOrganizations" type="pendingOrganizations-type" /> <xs:element name="givenmandates" type="mandates-type" /> <xs:element name="receivedmandates" type="mandates-type" /> <xs:any namespace="##any" processContents="skip" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="user-type"> <xs:sequence> <xs:element name="id" type="xs:string" /> <xs:element name="organization" type="xs:string" /> <xs:element name="organizationFriendlyName" type="xs:string" /> <xs:element name="status" type="xs:string" /> <xs:element name="attributes" type="attributes-type" /> <xs:element name="roleassignments" type="roleassignments-type" /> <xs:element name="groupassignments" type="groupassignments-type" /> <xs:element name="authentication" type="authentication-type" /> <xs:element name="givenmandates" type="mandates-type" /> <xs:element name="receivedmandates" type="mandates-type" /> <xs:any namespace="##any" processContents="skip" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="attributes-type"> <xs:sequence> <xs:element name="uid" type="xs:string" /> <xs:element name="firstname" type="xs:string" /> <xs:element name="surname" type="xs:string" /> <xs:element name="email" type="xs:string" /> <xs:element name="mobile" type="xs:string" /> <xs:element name="hetu" type="xs:string" /> <xs:element name="cn" type="xs:string" /> <xs:element name="organization" type="xs:string" /> <xs:element name="customattribute" type="customattribute-type" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="customattribute-type"> <xs:sequence> <xs:element name="value" type="xs:string" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> <xs:attribute name="name" type="xs:string" use="optional" /> </xs:complexType> <xs:complexType name="memberships-type"> <xs:choice> <xs:sequence> <xs:element name="id" type="xs:string" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> <xs:sequence> <xs:element name="organization" type="organization-type" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:choice> </xs:complexType> <xs:complexType name="members-type"> <xs:sequence> <xs:element name="id" type="xs:string" minOccurs="1" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="roles-type"> <xs:sequence> <xs:element name="role" type="role-type" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="role-type"> <xs:sequence> <xs:element name="id" type="xs:string" /> <xs:element name="roleassignments" type="roleassignments-type" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="roleassignments-type"> <xs:sequence> <xs:element name="roleassignment" type="roleassignment-type" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="roleassignment-type"> <xs:choice> <xs:element name="role" type="role-type" /> <xs:element name="userid" type="xs:string" /> <xs:element name="user" type="user-type" /> </xs:choice> </xs:complexType> <xs:complexType name="pendingOrganizations-type"> <xs:sequence> <xs:element name="count" type="xs:string" /> <xs:element name="newest" type="xs:string" /> <xs:element name="oldest" type="xs:string" /> <xs:element name="url" type="xs:string" /> </xs:sequence> </xs:complexType> <xs:complexType name="groupassignments-type"> <xs:sequence> <xs:element name="groupassignment" type="groupassignment-type" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="groupassignment-type"> <xs:sequence> <xs:element name="group" type="group-type" /> </xs:sequence> </xs:complexType> <xs:complexType name="group-type"> <xs:sequence> <xs:element name="id" type="xs:string" /> </xs:sequence> </xs:complexType> <xs:complexType name="authentication-type"> <xs:sequence> <xs:element name="password" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="sms.activated" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="otp.activated" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="otp.state" type="xs:string" minOccurs="0" maxOccurs="1" /> </xs:sequence> </xs:complexType> <xs:complexType name="idlist-type"> <xs:sequence> <xs:element name="id" type="xs:string" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="entitylist-type"> <xs:sequence> <xs:element ref="organization" minOccurs="0" maxOccurs="unbounded" /> <xs:element ref="user" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="mandatelist-type"> <xs:sequence> <xs:choice> <xs:element ref="mandate" minOccurs="0" maxOccurs="unbounded" /> <xs:element name="id" type="xs:string" minOccurs="0" maxOccurs="unbounded" /> </xs:choice> </xs:sequence> </xs:complexType> <xs:complexType name="error-type"> <xs:sequence> <xs:element name="code" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="message" type="xs:string" minOccurs="0" maxOccurs="1" /> </xs:sequence> </xs:complexType> <xs:complexType name="delegations-type"> <xs:sequence> <xs:element name="userid" type="xs:string" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="mandates-type"> <xs:sequence> <xs:element name="mandate" type="mandate-type" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="mandate-type"> <xs:sequence> <xs:element name="id" type="xs:string" /> <xs:element name="name" type="xs:string" /> <xs:element name="type" type="xs:string" /> <xs:element name="mandater" type="xs:string" /> <xs:element name="mandatee" type="xs:string" /> <xs:element name="roles" type="roles-type" /> <xs:element name="delegations" type="delegations-type" /> <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="skip" /> </xs:sequence> </xs:complexType> <xs:complexType name="mandatetemplates-type"> <xs:sequence> <xs:element name="mandatetemplate" type="mandatetemplate-type" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> <xs:complexType name="mandatetemplate-type"> <xs:sequence> <xs:element name="id" type="xs:string" /> <xs:element name="name" type="xs:string" /> <xs:element name="type" type="xs:string" /> <xs:element name="mandater" type="xs:string" /> <xs:element name="roles" type="roles-type" /> <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="skip" /> </xs:sequence> </xs:complexType> <xs:complexType name="roleinvitation-type"> <xs:sequence> <xs:element name="user" type="user-type"></xs:element> <xs:element name="roles" type="roles-type"></xs:element> </xs:sequence> </xs:complexType> <xs:complexType name="pendingUser-type"> <xs:sequence> <xs:element name="userid" type="xs:string"></xs:element> <xs:element name="pendinguserid" type="xs:string"></xs:element> <xs:element name="registrationwf" type="xs:string"></xs:element> </xs:sequence> </xs:complexType> </xs:schema>

Modification Operations

MOD014 Create Mandate

Description

Create a new mandate.

Target Type

Collection

Request URL

Request URL defines the constant mandate collection.

Example

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

Request Method

POST

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

mandateType

  • ORGTOORG

  • PERTOORG

  • ORGTOPER

  • PERTOPER

 

X

 

Defines the type of the mandate.

roles

List of role entity names

X

X

 

At least one role has to be defined. Multiple roles are separated with ',' character.

mandater

Entity Name

 

X

 

 

mandatee

Entity Name

 

X

 

 

name

String

 

 

 

If not defined the name will be generated by the system.

Curl Example

curl --insecure -X POST -u restuser:secret "https://localhost:7443/customerid-rest/services/mandates/?mandateType=ORGTOORG&roles=6666666-6/TestRole&mandater=6666666-6&mandatee=7777777-7"

Response Document

<idlist>  <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD015 Update Mandate

Description

Update the mandate.

Target Type

Entity

Request URL

Request URL defines the mandate to be updated.

Example

  • https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME

Request Method

PUT

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

roles

List of role entity names

X

X

 

At least one role has to be defined.

Curl Example

curl --insecure -X PUT -u restuser:secret "https://localhost:7443/customerid-rest/services/mandate/7777777-7XXXXXXXXXXXXXXXXXXXX?roles=6666666-6/TestRole2"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD016 Delegate Mandate

Description

Delegate a mandate to a user. Assign all the roles defined in the mandate to the user.

Target Type

Collection

Request URL

Request URL defines the mandate to be delegated.

Example

  • https://HOSTNAME/customerid-rest/services/delegations/MANDATENAME

Request Method

PUT

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

delegate

Entity Name

 

X

 

 

Curl Example

curl --insecure -X PUT -u restuser:secret "https://localhost:7443/customerid-rest/services/delegations/7777777-7XXXXXXXXXXXXXXXXXXXX?delegate=7777777-7/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Response Document

<idlist>  <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD017 Remove Mandate Delegation

Description

Remove a mandate delegation.

Target Type

Entity

Request URL

Request URL defines the mandate.

Example

  • https://HOSTNAME/customerid-rest/services/delegations/MANDATENAME

Request Method

DELETE

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

delegate

Entity Name

 

 

 

If string does not exist then removes the role delegation from all users

Curl Example

curl --insecure -X DELETE -u restuser:secret "https://localhost:7443/customerid-rest/services/delegations/7777777-7XXXXXXXXXXXXXXXXXXXX"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD018 Delegate Mandate Role

Description

Delegate a mandate role to a user. 

Please note: Singular Mandate Role delagations are not supported by conventional SSO authentication flow, but they must be separately resolved by a backchannel query to CustomerID REST API.

Target Type

Entity

Request URL

Request URL defines the mandate to be delegated.

Example

  • https://HOSTNAME/customerid-rest/services/roledelegations/MANDATENAME

Request Method

PUT

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

role

Entity Name

 

X

 

 

delegate

Entity Name

 

X

 

 

Curl Example

curl --insecure -X PUT -u restuser:secret "https://localhost:7443/customerid-rest/services/roledelegations/7777777-7XXXXXXXXXXXXXXXXXXXX?delegate=7777777-7/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&role=1234567-8/TestRole"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD019 Remove Mandate Role Delegation

Description

Remove a mandate role delegation.

Target Type

Entity

Request URL

Request URL defines the mandate.

Example

  • https://HOSTNAME/customerid-rest/services/roledelegations/MANDATENAME

Request Method

DELETE

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

role

Entity Name

 

X

 

 

delegate

Entity Name

 

 

 

If empty string then removes the role delegation from all users

Curl Example

curl --insecure -X DELETE -u restuser:secret "https://localhost:7443/customerid-rest/services/roledelegations/7777777-7XXXXXXXXXXXXXXXXXXXX?role=1234567-8/TestRole"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD020 Remove Mandate

Description

Remove the mandate.

Target Type

Entity

Request URL

Request URL defines the mandate to be removed.

Example

  • https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME

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/mandate/7777777-7XXXXXXXXXXXXXXXXXXXX"

Response Document

<?xml version="1.0" encoding="UTF-8"?> <idlist> <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD021 Create Mandate Template

Description

Create a new mandate template.

Target Type

Collection

Request URL

Request URL defines the constant mandate collection.

Example

  • https://HOSTNAME/customerid-rest/services/mandatetemplates/

Request Method

POST

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

mandaterType

  • ORGTO

  • PERTO

 

X

 

Defines the type of the mandater.

mandater

Entity Name

 

X

 

 

roles

List of role entity names

X

X

 

At least one role has to be defined.

name

String

 

 

 

If not defined the name will be generated by the system.

Curl Examples

curl --insecure -X POST -u restuser:secret "https://localhost:7443/customerid-rest/services/mandatetemplates/?mandaterType=ORGTO&roles=6666666-6/TestRole&mandater=6666666-6&name=TestTemplate" curl --insecure -X POST -u restuser:secret "https://localhost:7443/customerid-rest/services/mandatetemplates/?mandaterType=PERTO&roles=6666666-6/TestRole&mandater=5555555-5/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&name=TestTemplate"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandatetemplate/MANDATETEMPLATENAME</id> </idlist>

MOD022 Update Mandate Template

Description

Update the mandate template.

Target Type

Entity

Request URL

Request URL defines the mandate to be updated.

Example

  • https://HOSTNAME/customerid-rest/services/mandatetemplate/MANDATETEMPLATENAME

Request Method

PUT

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

roles

List of role entity names

X

 

 

 If the parameter is left out of the REST call, then no changes will be made to the mandate template role set. If you want to remove all roles from the mandate template then include this parameter but leave it empty.

name

String

 

 

 

 

Curl Example

curl --insecure -X PUT -u restuser:secret "https://localhost:7443/customerid-rest/services/mandatetemplate/TestTemplate?name=TestTemplate2"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandatetemplate/MANDATETEMPLATENAME</id> </idlist>

MOD023 Assign Mandate Template

Description

Assign the mandate template to a mandatee.

Target Type

Entity

Request URL

Request URL defines the mandate to be assigned.

Example

  • https://HOSTNAME/customerid-rest/services/mandatetemplate/MANDATETEMPLATENAME

Request Method

POST

Request URL Parameters

Name

Accepted Values

Multivalued

Mandatory

Default

Description

Name

Accepted Values

Multivalued

Mandatory

Default

Description

mandateeType

  • TOORG

  • TOPER

 

X

 

 

mandatee

Entity Name

 

X

 

 

Curl Example

curl --insecure -X POST -u restuser:secret "https://localhost:7443/customerid-rest/services/mandatetemplate/TestTemplate2?mandatee=6666666-6&mandateeType=TOORG"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandate/MANDATENAME</id> </idlist>

MOD024 Remove Mandate Template

Description

Remove the mandate template.

Target Type

Entity

Request URL

Request URL defines the mandate to be removed.

Example

  • https://HOSTNAME/customerid-rest/services/mandatetemplate/MANDATETEMPLATENAME

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/mandatetemplate/TestTemplate2"

Response Document

<idlist> <id>https://HOSTNAME/customerid-rest/services/mandatetemplate/MANDATETEMPLATENAME</id> </idlist>

MOD025 Create Role Invitation

Description

Creates a new role invitation with one role for either an existing user or for a pending user.

Target Type

Collection

Request URL

Request URL defines the collection where the role invitation is to be created.