RITM API V1 (2023.12.0)

Download OpenAPI specification:Download

License: OneWelcome License Terms of Service

RITM is a delegated identity management system that allows organisations to securely connect identities through roles and their associated entitlements, while leveraging self-service capabilities.

Introduction to the RITM API

Next to technical API's that are typically used by the RITM platform itself, OneWelcome also provides more functional oriented API's to ease integrations with the customers' applications. This specification is meant to provide information and guidance with respect to the functional RITM API's.

Versions of the API

Our API's are versioned and will remain backwards-compatible for 6 months after the end-of-life for this particular version is announced. Newer versions are expected to be compatible with old versions but both request parameters and response bodies could be subject to changes between versions.

The response body for an API call could contain more information then described in this specification and users of the API should ignore this extra information.

Find out more about RITM

Access and Authorisation information

Calls related to retrieving access and authorisation information (both self-service and admin).

Retrieve profile information of the authenticated user

The profile of a user contains several attributes with information about this user. This API retrieves attributes and their values related to the profile of the authenticated user.

This endpoint:

is intended to return information for the authenticated caller of the API (by means of an OAuth Access Token) not for any given user
will only return attribute related information and not group membership or role assignment information as this is by-default shielded by RITM for the user when looking at his own profile (UI and/or API)

Authorizations:

OAuth2APIKey

query Parameters

attributesOf

string

Default: "MANAGEMENT_USER_EDIT"

Enum: "AFFECTED_IDENTITIES" "API_USER_CREATE" "MANAGEMENT_IMPORT" "MANAGEMENT_USER_ADD" "MANAGEMENT_USER_EDIT" "MANAGEMENT_USER_PROFILE" "MANAGEMENT_USER_INVITE" "MANAGEMENT_USER_SEND_INVITATION" "MANAGEMENT_USERS" "MASS_UPDATES" "PROFILE_MANAGED_IDENTITIES" "REPORTS_USERS" "STRUCTURES" "USER_PROFILE"

Defined set of attributes whereby the possible options relate to the corresponding functionality in the RITM UI.

The MANAGEMENT_USER_EDIT option, for example, will return the profile information (if available) that can also be found on the first tab of the "Edit user" page in the RITM UI.

AFFECTED_IDENTITIES
API_USER_CREATE
MANAGEMENT_IMPORT
MANAGEMENT_USER_ADD
MANAGEMENT_USER_EDIT
MANAGEMENT_USER_PROFILE
MANAGEMENT_USER_INVITE
MANAGEMENT_USER_SEND_INVITATION
MANAGEMENT_USERS
MASS_UPDATES
PROFILE_MANAGED_IDENTITIES
REPORTS_USERS
STRUCTURES
USER_PROFILE

Responses

Response samples

200
400
401
403
422

Content type

application/json

Example

Name only

{"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"name": {"givenName": "John",
"familyName": "Doe"
}
}

Get the managed groups of the authenticated user

Users with RITM Admin roles and the appropriate entitlements can manage several groups with structures. This API fetches these managed group for the authenticated user.

This endpoint:

is intended to return information for the authenticated caller of the API (by means of an OAuth Access Token) not for any given user

Authorizations:

OAuth2APIKey

Responses

Response samples

200
400
401
403

Content type

application/json

Example

No managed structures and groups

{"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"managedStructures": [ ]
}

Retrieve the roles that the authenticated user is allowed to assign

A user with one or more RITM Admin roles could have the appropriate entitlements to assign roles to their managed identities. This endpoint can be used to retrieve:

all possible roles that can be assigned
roles that can be assigned, but related to a specific application

Authorizations:

OAuth2APIKey

query Parameters

application	string Example: application=application_client_id
structureCode required	string Example: structureCode=structure-t04wu2fQbnEk
groupCode required	string Example: groupCode=my_defined_groupcode

Responses

Response samples

200
400
401
404

Content type

application/json

Example

No assignable roles

{"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"cascadableAdminRoles": [ ],
"cascadablePersonalRoles": [ ],
"cascadableAccessRoles": [ ]
}

Retrieve application specific roles of the authenticated user or of a managed identity

Any user could potentially have been assigned one or more roles related to third party application access. This API will retrieve all the third party application roles, for a given application, that are assigned to a particular user.

This information could either be retrieved for the user himself (authenticating with an OAuth Access Token) or for any of the managed identities of the caller (typically by authenticating with an OAuth Access Token or API-Key). application will always be required as a request parameter. The application is the actual application code as defined in RITM and could be typically seen as the client_id in case of an OAuth/OIDC application or a SAML EntityID of the SP.

Authorizations:

OAuth2APIKey

query Parameters

uid	string (uid) Example: uid=8d90b808-1e93-11eb-adc1-0242ac120002 If uid is not included as a parameter, the API will retrieve the application specific roles of the authenticated user.
application required	string Example: application=application_client_id

Responses

Response samples

200
400
401
404

Content type

application/json

Example

No application roles for the given user/application

{"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"application": "drift",
"applicationRoles": [ ]
}

Retrieve profile, group and role information of managed identities

Any user with will have several attributes as part of their profile but they will also have one or more group memberships and potentially one or more assigned roles. This API retrieves all the mentioned information for one specific managed identity (user) or all the managed identities of the authenticated user.

Authorizations:

OAuth2APIKey

query Parameters

uid	string (uid) Example: uid=8d90b808-1e93-11eb-adc1-0242ac120002 If uid is not included as a parameter, the API will retrieve all managed identities of the authenticated user (with pagination).
attributesOf	string Default: "MANAGEMENT_USER_EDIT" Enum: "AFFECTED_IDENTITIES" "API_USER_CREATE" "MANAGEMENT_IMPORT" "MANAGEMENT_USER_ADD" "MANAGEMENT_USER_EDIT" "MANAGEMENT_USER_PROFILE" "MANAGEMENT_USER_INVITE" "MANAGEMENT_USER_SEND_INVITATION" "MANAGEMENT_USERS" "MASS_UPDATES" "PROFILE_MANAGED_IDENTITIES" "REPORTS_USERS" "STRUCTURES" "USER_PROFILE" Defined set of attributes whereby the possible options relate to the corresponding functionality in the RITM UI. The MANAGEMENT_USER_EDIT option, for example, will return the profile information (if available) that can also be found on the first tab of the "Edit user" page in the RITM UI. AFFECTED_IDENTITIES API_USER_CREATE MANAGEMENT_IMPORT MANAGEMENT_USER_ADD MANAGEMENT_USER_EDIT MANAGEMENT_USER_PROFILE MANAGEMENT_USER_INVITE MANAGEMENT_USER_SEND_INVITATION MANAGEMENT_USERS MASS_UPDATES PROFILE_MANAGED_IDENTITIES REPORTS_USERS STRUCTURES USER_PROFILE
structureCode	string Example: structureCode=structure-t04wu2fQbnEk structureCode is an optional filter to only retrieve the managed identities from that particular structure. structureCode is only required if groupCode is also used.
groupCode	string Example: groupCode=my_code_for_group1 groupCode is an optional filter to only retrieve the managed identities from that particular group.
showGroupAttributes	boolean Default: true Example: showGroupAttributes=false showGroupAttributes is an optional filter to be able to specify if custom group attributes should also be included in the response or not. By default it is set to true.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401
403
422

Content type

application/json

Example

One or more managed identities, showGroupAttributes set to true

{"totalItems": 1,
"limit": 10,
"page": 1,
"pageCount": 1,
"result": [{"profileInformation": {"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"name": {"givenName": "John",
"familyName": "Doe"
},
"emails": [{"type": "work",
"value": "john.p.doe@example.com",
"primary": true
}
]
},
"roleAssignments": {"adminRoles": [{"code": "role-wYSRxmeChQdJ",
"name": "Customer Care",
"startDate": "2021-08-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z"
}
],
"personalRoles": [{"code": "role-LJxdruuzjERF",
"name": "Self Service",
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z"
}
],
"accessRoles": [{"code": "role-JgvpFeGFykyd",
"name": "Drift - Account Owner",
"startDate": "2021-04-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z",
"assignedStructureCode": "structure-t04wu2fQbnEk",
"assignedStructureGroup": "my_code_for_group1",
"applications": [{"code": "drift",
"name": "Drift",
"applicationRoles": ["Account Owner"
]
}
]
}
]
},
"structureMemberships": [{"code": "structure-t04wu2fQbnEk",
"name": "Structure 1",
"groupMemberships": [{"code": "my_code_for_group1",
"name": "Group 1",
"attributes": {"vatNumber": 63826382
}
}
]
}
]
}
]
}

Get the group memberships of managed identities

Users with RITM Admin roles can retrieve group memberships for a managed identity by using this API.

Authorizations:

OAuth2APIKey

query Parameters

uid required	string (uid) Example: uid=8d90b808-1e93-11eb-adc1-0242ac120002
showGroupAttributes	boolean Default: true Example: showGroupAttributes=false showGroupAttributes is an optional filter to be able to specify if custom group attributes should also be included in the response or not. By default it is set to true.

Responses

Response samples

200
400
401
404

Content type

application/json

Example

One or more group memberships

{"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"structureMemberships": [{"code": "structure-t04wu2fQbnEk",
"name": "Structure 1",
"groupMemberships": [{"code": "my_code_for_group1",
"name": "Group 1",
"attributes": {"vatNumber": 63826382
}
}
]
}
]
}

Users

Calls related to managing users.

Create a new user

A user with a RITM Admin role with the appropriate rights has the ability to create users. These can either be so-called ACTIVE users where all profile information is passed or INACTIVE users that are created to trigger an invitation flow that could allow for profile enrichment.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

required	object (profile)
required	Array of objects
	Array of objects

Responses

Request samples

Payload

Content type

application/json

Example

Minimal inactive user (non multi-company)

{"profileInformation": {"name": {"givenName": "Firstname",
"familyName": "Lastname"
},
"emails": [{"value": "firstname.lastname@mailinator.com",
"type": "work",
"primary": true
}
],
"urn:scim:schemas:extension:iwelcome:1.0": {"state": "INACTIVE"
}
},
"structureMemberships": [{"code": "structure-t04wu2fQbnEk",
"groupMemberships": [{"code": "my_code_for_group1"
}
]
}
],
"roleAssignments": [{"code": "role-LJxdruuzjERF"
}
]
}

Response samples

200
400
401
403
422

Content type

application/json

Example

Full response (non multi-company)

{"profileInformation": {"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"name": {"givenName": "Firstname",
"familyName": "Lastname"
},
"emails": [{"value": "firstname.lastname@mailinator.com",
"type": "work",
"primary": true
}
],
"urn:scim:schemas:extension:iwelcome:1.0": {"state": "INACTIVE"
}
},
"roleAssignments": {"adminRoles": [ ],
"personalRoles": [{"code": "role-LJxdruuzjERF",
"name": "Self Service",
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z"
}
],
"accessRoles": [ ]
},
"structureMemberships": [{"code": "structure-t04wu2fQbnEk",
"name": "Structure 1",
"groupMemberships": [{"code": "my_code_for_group1",
"name": "Group 1"
}
]
}
]
}

Edit a user

A user with a RITM Admin role with the appropriate rights has the ability to edit his managed identities. The group and role management options for these users depend on the specific entitlements this admin user has on the affected user. Any user with the appropriate RITM Personal role and attribute entitlements is able to edit their profile. Group memberships and role assignments fpr these users can only be managed by an admin user.

Authorizations:

OAuth2APIKey

path Parameters

uid

required

string (uid)

Example: 8d90b808-1e93-11eb-adc1-0242ac120002

Request Body schema: application/json

	object (profile)
	Array of objects
	Array of objects

Responses

Request samples

Payload

Content type

application/json

Example

Change profile information

{"profileInformation": {"name": {"givenName": "OtherFirstname"
}
}
}

Response samples

200
401
403
404
422

Content type

application/json

Example

Full response (non multi-company)

{"profileInformation": {"uid": "65b7a29080f545eb9720f771f054b6e4",
"name": {"givenName": "OtherFirstname",
"familyName": "Lastname"
},
"emails": [{"value": "firstname.lastname@mailinator.com",
"type": "work",
"primary": true
}
],
"urn:scim:schemas:extension:iwelcome:1.0": {"state": "INACTIVE"
}
},
"roleAssignments": {"adminRoles": [ ],
"personalRoles": [{"code": "role-LJxdruuzjERF",
"name": "Self Service",
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z"
}
],
"accessRoles": [{"code": "role-JgvpFeGFykyd",
"name": "Drift - Account Owner",
"startDate": "2021-04-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z",
"applications": [{"code": "drift",
"name": "Drift",
"applicationRoles": ["Account Owner"
]
}
]
}
]
},
"structureMemberships": [{"code": "structure-t04wu2fQbnEk",
"name": "Structure 1",
"groupMemberships": [{"code": "my_code_for_group1",
"name": "Group 1"
}
]
}
]
}

Edit a user

A user with a RITM Admin role with the appropriate rights has the ability to edit his managed identities. The group and role management options for these users depend on the specific entitlements this admin user has on the affected user. Any user with the appropriate RITM Personal role and attribute entitlements is able to edit their profile. Group memberships and role assignments fpr these users can only be managed by an admin user.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

uid required	string (uid)
	object (profile)
	Array of objects
	Array of objects

Responses

Request samples

Payload

Content type

application/json

Example

Change profile information

{"uid": "8d90b808-1e93-11eb-adc1-0242ac120002",
"profileInformation": {"name": {"givenName": "OtherFirstname"
}
}
}

Response samples

200
401
403
404
422

Content type

application/json

Example

Full response (non multi-company)

{"profileInformation": {"uid": "65b7a29080f545eb9720f771f054b6e4",
"name": {"givenName": "OtherFirstname",
"familyName": "Lastname"
},
"emails": [{"value": "firstname.lastname@mailinator.com",
"type": "work",
"primary": true
}
],
"urn:scim:schemas:extension:iwelcome:1.0": {"state": "INACTIVE"
}
},
"roleAssignments": {"adminRoles": [ ],
"personalRoles": [{"code": "role-LJxdruuzjERF",
"name": "Self Service",
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z"
}
],
"accessRoles": [{"code": "role-JgvpFeGFykyd",
"name": "Drift - Account Owner",
"startDate": "2021-04-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z",
"applications": [{"code": "drift",
"name": "Drift",
"applicationRoles": ["Account Owner"
]
}
]
}
]
},
"structureMemberships": [{"code": "structure-t04wu2fQbnEk",
"name": "Structure 1",
"groupMemberships": [{"code": "my_code_for_group1",
"name": "Group 1"
}
]
}
]
}

Send an invitation to a user

A user with a RITM Admin role with the appropriate rights has the ability to send invitations to users. This API can only be used with an access token and the required scope workflow:invitation:admin:post.

Authorizations:

OAuth2

Request Body schema: application/json

email required	string Email-address of the user that is invited
phone required	string Phone number of the user that is invited
note	string An optional note to the user that is invited
language	string Preferred language of the user that is invited
	object (nameSCIM1.1)
	Array of objects (addressesSCIM1.1)
	object (iwelcomeExtensionSCIM1.1)
	object (ritmExtensionSCIM1.1)
	object (customExtensionSCIM1.1)
required	Array of objects
	Array of objects

Responses

Request samples

Payload

Content type

application/json

Example

Full send invitation with all information (non multi-company)

{"email": "firstname.lastname@mailinator.com",
"phone": "+31612345678",
"language": "en_GB",
"note": "You have been invited to join Company",
"name": {"givenName": "Firstname",
"familyName": "Lastname"
},
"urn:scim:schemas:extension:iwelcome:1.0": {"birthDate": "01/01/1985"
},
"urn:scim:schemas:extension:custom:1.0": {"customAttribute1": "value1",
"customAttribute2": 12345,
"customAttribute3": true,
"customAttribute4": ["arrayValue1",
"arrayValue2"
],
"customAttribute5": {"subAttribute1": "subValue1",
"subAttribute2": 12345,
"subAttribute3": false
},
"customAttribute6": [{"subAttribute1": "subValue1",
"subAttribute2": 12345,
"subAttribute3": false
}
]
},
"structureMemberships": [{"code": "structure-jgw373i938y3",
"groupMemberships": [{"code": "uk"
}
]
}
],
"roleAssignments": [{"code": "role-673f20jvsklwh",
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2023-01-01T00:00:00.000Z"
}
]
}

Response samples

200
400
401
403
422

Content type

application/json

{"result": {"email": "firstname.lastname@mailinator.com",
"phone": "+31612345678",
"language": "en_GB",
"note": "You have been invitated to join Company",
"name": {"givenName": "Firstname",
"familyName": "Lastname"
},
"urn:scim:schemas:extension:iwelcome:1.0": {"birthDate": "01/01/1985"
},
"urn:scim:schemas:extension:custom:1.0": {"customAttribute1": "value1",
"customAttribute2": 12345,
"customAttribute3": true,
"customAttribute4": ["arrayValue1",
"arrayValue2"
],
"customAttribute5": {"subAttribute1": "subValue1",
"subAttribute2": 12345,
"subAttribute3": false
},
"customAttribute6": [{"subAttribute1": "subValue1",
"subAttribute2": 12345,
"subAttribute3": false
}
]
},
"structureMemberships": [{"code": "structure-jgw373i938y3",
"groupMemberships": [{"code": "uk"
}
]
}
],
"roleAssignments": [{"code": "role-87398hjhvsn",
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2023-01-01T00:00:00.000Z",
"assignedStructureCode": "structure-jgw373i938y3",
"assignedStructureGroup": "uk"
}
]
}
}

Applications

Calls related to 3rd party applications

Create a new application (3rd party)

Users with RITM Admin roles and with the correct platform access can create a new 3rd party application.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

name required	string The name of the application
description	string A short description of the application
protocol	string Default: "NONE" Enum: "NONE" "OAuth/OIDC" "SAML" The protocol if integrated with the IdP
identifier	string The identifier (ClientID or entityID) as specified at the integrated Identity Provider
url required	string The url that the user is redirected to in the RITM UI if the application tile is clicked
applicationRoles	Array of strings
applicationCategories	Array of strings
logo	string Base64 encoded picture
smallLogo	string Base64 encoded picture
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the new application. Can be ACTIVE or INACTIVE.

Responses

Request samples

Payload

Content type

application/json

{"name": "Drift",
"description": "Conversational Marketing platform that combines chat, email, video, and automation to remove the friction from business buying",
"protocol": "OAuth/OIDC",
"identifier": "drift",
"url": "https://start.drift.com/login",
"applicationRoles": ["Account Owner",
"Admin",
"User"
],
"applicationCategories": ["thirdpartyappcategory-RGupzjTTQSBl"
],
"logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAAA8CAYAAAAjW/WRAAAAjElEQVR42u3TIQEAMAgAsNPxnihkpgEFMPitw6Lz1wNWIQgIAoKAICAICAKCgCAgCAgCCAKCgCAgCAgCgoAgIAgIAoIIAoKAICAICAKCgCAgCAgCggCCgCAgCAgCgoAgIAgIAoKAIIAgIAgIAoKAICAICAKCgCCAICAICAKCgCAgCAgCgoAgIAggCFwMcz2AcT/1oYUAAAAASUVORK5CYII=",
"smallLogo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAF4AAABACAYAAACTDsCFAAAAdElEQVR42u3QIQEAMAgAsNPxnihkpgGaAqgtwqLz1+NciBcvHvHiES8e8eIRLx7x4sWLFy8e8eIRLx7x4hEvHvHixYsXLx7x4hEvHvHiES8e8eLFixcvHvHiES8e8eIRLx7x4sVrEC8e8eIRLx7x4hEvnm0AtTOJAXB2hPAAAAAASUVORK5CYII=",
"status": "ACTIVE"
}

Response samples

200
400
401
404
422

Content type

application/json

{"code": "thirdpartyapp-sKUkb2QhmWLS",
"name": "Drift",
"applicationCategories": ["thirdpartyappcategory-RGupzjTTQSBl"
],
"protocol": "OAuth/OIDC",
"identifier": "drift",
"status": "ACTIVE",
"description": "Conversational Marketing platform that combines chat, email, video, and automation to remove the friction from business buying",
"applicationRoles": ["Account Owner",
"Admin",
"User"
],
"url": "https://start.drift.com/login",
"smallLogo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAF4AAABACAYAAACTDsCFAAAAdElEQVR42u3QIQEAMAgAsNPxnihkpgGaAqgtwqLz1+NciBcvHvHiES8e8eIRLx7x4sWLFy8e8eIRLx7x4hEvHvHixYsXLx7x4hEvHvHiES8e8eLFixcvHvHiES8e8eIRLx7x4sVrEC8e8eIRLx7x4hEvnm0AtTOJAXB2hPAAAAAASUVORK5CYII=",
"logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAAA8CAYAAAAjW/WRAAAAjElEQVR42u3TIQEAMAgAsNPxnihkpgEFMPitw6Lz1wNWIQgIAoKAICAICAKCgCAgCAgCCAKCgCAgCAgCgoAgIAgIAoIIAoKAICAICAKCgCAgCAgCggCCgCAgCAgCgoAgIAgIAoKAIIAgIAgIAoKAICAICAKCgCCAICAICAKCgCAgCAgCgoAgIAggCFwMcz2AcT/1oYUAAAAASUVORK5CYII="
}

Search for existing applications

Users with RITM Admin roles and with the correct platform access can search for existing 3rd party applications.

Authorizations:

OAuth2APIKey

query Parameters

code	string The code of the application. Case-sensitive and exact match.
name	string The name of the application. Case-sensitive and exact match.
identifier	boolean The identifier of the application. Case-sensitive and exact match.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401

Content type

application/json

Example

One or more applications found

{"totalItems": 1,
"limit": 10,
"page": 1,
"pageCount": 1,
"result": [{"code": "thirdpartyapp-sKUkb2QhmWLS",
"name": "Drift",
"applicationCategories": ["thirdpartyappcategory-RGupzjTTQSBl"
],
"protocol": "OAuth/OIDC",
"identifier": "drift",
"status": "ACTIVE",
"description": "Conversational Marketing platform that combines chat, email, video, and automation to remove the friction from business buying",
"applicationRoles": ["Account Owner",
"Admin",
"User"
],
"url": "https://start.drift.com/login",
"smallLogo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAF4AAABACAYAAACTDsCFAAAAdElEQVR42u3QIQEAMAgAsNPxnihkpgGaAqgtwqLz1+NciBcvHvHiES8e8eIRLx7x4sWLFy8e8eIRLx7x4hEvHvHixYsXLx7x4hEvHvHiES8e8eLFixcvHvHiES8e8eIRLx7x4sVrEC8e8eIRLx7x4hEvnm0AtTOJAXB2hPAAAAAASUVORK5CYII=",
"logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAAA8CAYAAAAjW/WRAAAAjElEQVR42u3TIQEAMAgAsNPxnihkpgEFMPitw6Lz1wNWIQgIAoKAICAICAKCgCAgCAgCCAKCgCAgCAgCgoAgIAgIAoIIAoKAICAICAKCgCAgCAgCggCCgCAgCAgCgoAgIAgIAoKAIIAgIAgIAoKAICAICAKCgCCAICAICAKCgCAgCAgCgoAgIAggCFwMcz2AcT/1oYUAAAAASUVORK5CYII="
}
]
}

Retrieve an existing application

Users with RITM Admin roles and with the correct platform access can retrieve a specific existing 3rd party application.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: thirdpartyapp-sKUkb2QhmWLS

The code of the application.

Responses

Response samples

200
400
401
404

Content type

application/json

{"code": "thirdpartyapp-sKUkb2QhmWLS",
"name": "Drift",
"applicationCategories": ["thirdpartyappcategory-RGupzjTTQSBl"
],
"protocol": "OAuth/OIDC",
"identifier": "drift",
"status": "ACTIVE",
"description": "Conversational Marketing platform that combines chat, email, video, and automation to remove the friction from business buying",
"applicationRoles": ["Account Owner",
"Admin",
"User"
],
"url": "https://start.drift.com/login",
"smallLogo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAF4AAABACAYAAACTDsCFAAAAdElEQVR42u3QIQEAMAgAsNPxnihkpgGaAqgtwqLz1+NciBcvHvHiES8e8eIRLx7x4sWLFy8e8eIRLx7x4hEvHvHixYsXLx7x4hEvHvHiES8e8eLFixcvHvHiES8e8eIRLx7x4sVrEC8e8eIRLx7x4hEvnm0AtTOJAXB2hPAAAAAASUVORK5CYII=",
"logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAAA8CAYAAAAjW/WRAAAAjElEQVR42u3TIQEAMAgAsNPxnihkpgEFMPitw6Lz1wNWIQgIAoKAICAICAKCgCAgCAgCCAKCgCAgCAgCgoAgIAgIAoIIAoKAICAICAKCgCAgCAgCggCCgCAgCAgCgoAgIAgIAoKAIIAgIAgIAoKAICAICAKCgCCAICAICAKCgCAgCAgCgoAgIAggCFwMcz2AcT/1oYUAAAAASUVORK5CYII="
}

Update an existing application

Users with RITM Admin roles and with the correct platform access can update a specific existing 3rd party application.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: thirdpartyapp-sKUkb2QhmWLS

The code of the application.

Request Body schema: application/json

name	string The name of the application
description	string A short description of the application
protocol	string Default: "NONE" Enum: "NONE" "OAuth/OIDC" "SAML" The protocol if integrated with the IdP
identifier	string The identifier (ClientID or entityID) as specified at the integrated Identity Provider. Mandatory if protocol is not "NONE"
url	string The url that the user is redirected to in the RITM UI if the application tile is clicked
applicationRoles	Array of strings
applicationCategories	Array of strings
logo	string Base64 encoded picture
smallLogo	string Base64 encoded picture
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the new application. Can be ACTIVE or INACTIVE.

Responses

Request samples

Payload

Content type

application/json

Example

Change the name

{"name": "Drift V2"
}

Response samples

200
400
401
404
422

Content type

application/json

{"code": "thirdpartyapp-sKUkb2QhmWLS",
"name": "Drift V2",
"applicationCategories": ["thirdpartyappcategory-RGupzjTTQSBl"
],
"protocol": "SAML",
"identifier": "drifsaml",
"status": "ACTIVE",
"description": "Conversational Marketing platform that combines chat, email, video, and automation to remove the friction from business buying",
"applicationRoles": ["Writer",
"Reader"
],
"url": "https://start.drift.com/login",
"smallLogo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAF4AAABACAYAAACTDsCFAAAAdElEQVR42u3QIQEAMAgAsNPxnihkpgGaAqgtwqLz1+NciBcvHvHiES8e8eIRLx7x4sWLFy8e8eIRLx7x4hEvHvHixYsXLx7x4hEvHvHiES8e8eLFixcvHvHiES8e8eIRLx7x4sVrEC8e8eIRLx7x4hEvnm0AtTOJAXB2hPAAAAAASUVORK5CYII=",
"logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAAA8CAYAAAAjW/WRAAAAjElEQVR42u3TIQEAMAgAsNPxnihkpgEFMPitw6Lz1wNWIQgIAoKAICAICAKCgCAgCAgCCAKCgCAgCAgCgoAgIAgIAoIIAoKAICAICAKCgCAgCAgCggCCgCAgCAgCgoAgIAgIAoKAIIAgIAgIAoKAICAICAKCgCCAICAICAKCgCAgCAgCgoAgIAggCFwMcz2AcT/1oYUAAAAASUVORK5CYII="
}

Delete an existing application

Users with RITM Admin roles and with the correct platform access can delete a specific existing 3rd party application.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: thirdpartyapp-sKUkb2QhmWLS

The code of the application.

Responses

Response samples

200
400
401

Content type

application/json

{ }

Applications - Application categories

Calls related to 3rd party application categories

Create a new application category

Users with RITM Admin roles and with the correct platform access can create a new application category using this API.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

name required	string The name of the application category
description	string A short description of the application category
visible	boolean Default: true If the application category should be shown on the self-service pages of users

Responses

Request samples

Payload

Content type

application/json

{"name": "Marketing & Sales",
"description": "All marketing and sales related applications",
"visible": true
}

Response samples

200
400
401

Content type

application/json

{"code": "thirdpartyappcategory-63x3P26TZKj2",
"name": "Marketing & Sales",
"description": "All marketing and sales related applications",
"visible": true
}

Search for existing application categories

Users with RITM Admin roles and with the correct platform access can retrieve application categories using this API. The search parameters are AND-ed.

Authorizations:

OAuth2APIKey

query Parameters

code	string The code of the application category. Case-sensitive and exact match.
name	string The name of the application category. Case-sensitive and exact match.
visible	boolean If the application category is shown on the self-services pages.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401

Content type

application/json

Example

One or more application categories found

{"totalItems": 1,
"limit": 10,
"page": 1,
"pageCount": 1,
"result": [{"code": "thirdpartyappcategory-63x3P26TZKj2",
"name": "Marketing & Sales",
"description": "All marketing and sales related applications",
"visible": true
}
]
}

Retrieve an existing application category

Users with RITM Admin roles and with the correct platform access can retrieve a specific application category.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: thirdpartyappcategory-63x3P26TZKj2

The code of the application category.

Responses

Response samples

200
400
401
404

Content type

application/json

{"code": "thirdpartyappcategory-63x3P26TZKj2",
"name": "Marketing & Sales",
"description": "All marketing and sales related applications",
"visible": true
}

Update an existing application category

Users with RITM Admin roles and with the correct platform access can update a specific application category.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: thirdpartyappcategory-63x3P26TZKj2

The code of the application category.

Request Body schema: application/json

name	string The name of the application category
description	string A short description of the application category
visible	boolean If the application category should be shown on the self-service pages of users

Responses

Request samples

Payload

Content type

application/json

{"name": "Sales & Marketing"
}

Response samples

200
400
401
404

Content type

application/json

{"code": "thirdpartyappcategory-63x3P26TZKj2",
"name": "Marketing & Sales",
"description": "All marketing and sales related applications",
"visible": true
}

Delete an existing application category

Users with RITM Admin roles and with the correct platform access can delete a specific application category.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: thirdpartyappcategory-63x3P26TZKj2

The code of the application category.

Responses

Response samples

200
400
401

Content type

application/json

{ }

Applications - Resource types

Calls related to resource types

Create a new resource type

Users with RITM Admin roles and with the correct platform access can create a new resource type using this API.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

name required	string The name of the resource type
description	string A short description of the resource type
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the new resource type. Can be ACTIVE or INACTIVE.

Responses

Request samples

Payload

Content type

application/json

{"name": "Resource type 1",
"description": "A description for resource type 1",
"status": "ACTIVE"
}

Response samples

200
400
401

Content type

application/json

{"code": "resourcestype-jdTYKbEPTmZO",
"name": "Resource type 1",
"description": "A description for resource type 1",
"status": "ACTIVE"
}

Search for existing resource types

Users with RITM Admin roles and with the correct platform access can retrieve resource types using this API.

Authorizations:

OAuth2APIKey

query Parameters

code	string The code of the resource type. Case-sensitive and exact match.
name	string The name of the resource type. Case-sensitive and exact match.
status	string Enum: "ACTIVE" "INACTIVE" Example: status=INACTIVE The status of the resource type. Case-insensitive and partial match.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401

Content type

application/json

Example

One or more resource types found

{"totalItems": 1,
"limit": 10,
"page": 1,
"pageCount": 1,
"result": [{"code": "resourcestype-jdTYKbEPTmZO",
"name": "Resource type 1",
"description": "A description for resource type 1",
"status": "ACTIVE"
}
]
}

Retrieve an existing resource type

Users with RITM Admin roles and with the correct platform access can retrieve a specific resource type using this API.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: resourcestype-jdTYKbEPTmZO

The code of the resource type.

Responses

Response samples

200
400
401
404

Content type

application/json

{"code": "resourcestype-jdTYKbEPTmZO",
"name": "Resource type 1",
"description": "A description for resource type 1",
"status": "ACTIVE"
}

Update an existing resource type

Users with RITM Admin roles and with the correct platform access can update a specific resource type using this API.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: resourcestype-jdTYKbEPTmZO

The code of the resource type.

Request Body schema: application/json

name	string The name of the resource type
description	string A short description of the resource type
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the resource type. Can be ACTIVE or INACTIVE.

Responses

Request samples

Payload

Content type

application/json

{"name": "New name for resource type 1"
}

Response samples

200
400
401
404

Content type

application/json

{"code": "resourcestype-jdTYKbEPTmZO",
"name": "New name for resource type 1",
"description": "A description for resource type 1",
"status": "ACTIVE"
}

Delete an existing resource type

Users with RITM Admin roles and with the correct platform access can delete a specific resource type using this API.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: resourcestype-jdTYKbEPTmZO

The code of the resource type.

Responses

Response samples

200
400
401
404

Content type

application/json

{ }

Applications - Resources

Calls related to resources

Create a new resource

Users with RITM Admin roles and with the correct platform access can create a new resource using this API.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

name required	string The name of the resource
description	string A short description of the resource
identifier	string An internal customer identifier
privileges	Array of strings
resourceTypes	Array of strings
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the new resource. Can be ACTIVE or INACTIVE.

Responses

Request samples

Payload

Content type

application/json

Example

All information passed

{"name": "Resource 1",
"description": "A description for resource 1",
"identifier": "ID12345678",
"privileges": ["verify",
"change"
],
"resourceTypes": ["resourcestype-UOoPGYOaHzkR"
],
"status": "ACTIVE"
}

Response samples

200
400
401
404

Content type

application/json

{"code": "resources-phyC7DOOteRG",
"name": "Resource 1",
"description": "A description for resource 1",
"identifier": "ID12345678",
"privileges": ["verify",
"change"
],
"resourceTypes": ["resourcestype-UOoPGYOaHzkR"
],
"status": "ACTIVE"
}

Search for existing resources

Users with RITM Admin roles and with the correct platform access can retrieve resource using this API.

Authorizations:

OAuth2APIKey

query Parameters

code	string The code of the resource. Case-sensitive and exact match.
name	string The name of the resource. Case-sensitive and exact match.
identifier	string The identifier of the resource. Case-insensitive and exact match.
status	string Enum: "ACTIVE" "INACTIVE" Example: status=INACTIVE The status of the resource. Case-sensitive and exact match.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401

Content type

application/json

Example

One or more resources found

{"totalItems": 1,
"limit": 10,
"page": 1,
"pageCount": 1,
"result": [{"code": "resources-phyC7DOOteRG",
"name": "Resource 1",
"description": "A description for resource 1",
"identifier": "ID12345678",
"privileges": ["verify",
"change"
],
"resourceTypes": ["resourcestype-UOoPGYOaHzkR"
],
"status": "ACTIVE"
}
]
}

Retrieve an existing resource

Users with RITM Admin roles and with the correct platform access can retrieve a specific resource using this API.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: resources-phyC7DOOteRG

The code of the resource.

Responses

Response samples

200
400
401
404

Content type

application/json

{"code": "resources-phyC7DOOteRG",
"name": "Resource 1",
"description": "A description for resource 1",
"identifier": "ID12345678",
"privileges": ["verify",
"change"
],
"resourceTypes": ["resourcestype-UOoPGYOaHzkR"
],
"status": "ACTIVE"
}

Update an existing resource

Users with RITM Admin roles and with the correct platform access can update a specific resource using this API.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: resources-phyC7DOOteRG

The code of the resource.

Request Body schema: application/json

name	string The name of the resource
description	string A short description of the resource
identifier	string An internal customer identifier
privileges	Array of strings
resourceTypes	Array of strings
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the resource. Can be ACTIVE or INACTIVE.

Responses

Request samples

Payload

Content type

application/json

Example

Change the identifier

{"identifier": "ID87654321"
}

Response samples

200
400
401
404

Content type

application/json

{"code": "resources-phyC7DOOteRG",
"name": "Resource 1",
"description": "A description for resource 1",
"identifier": "ID12345678",
"privileges": ["verify",
"change"
],
"resourceTypes": ["resourcestype-UOoPGYOaHzkR"
],
"status": "ACTIVE"
}

Delete an existing resource

Users with RITM Admin roles and with the correct platform access can delete a specific resource using this API.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: resources-phyC7DOOteRG

The code of the resource.

Responses

Response samples

200
400
401
404

Content type

application/json

{ }

Access - Access roles

Calls related to access roles.

Create a new access role

Users with RITM Admin roles and with the correct platform access can create a new access role using this API.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

name required	string The name of the access role
description	string A short description of the access role
status required	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the new access role. Can be ACTIVE or INACTIVE.
	Array of objects Array of code/value combinations
	Array of objects Array of 3rd party application and potentially application roles
	Array of objects Array of resources and potentially privileges

Responses

Request samples

Payload

Content type

application/json

{"name": "Drift - Admin",
"description": "An admin has access to everything in Drift.",
"status": "ACTIVE",
"customAttributes": [{"code": "appIdentifier",
"value": "12345678"
},
{"code": "appLicense",
"value": "Commercial"
}
],
"applications": [{"applicationCode": "thirdpartyapp-BayOJOgTTQCM",
"applicationRoles": ["Admin"
]
}
],
"resources": [{"resourceCode": "resources-phyC7DOOteRG",
"privileges": ["read"
]
}
]
}

Response samples

200
400
401
404
422

Content type

application/json

{"code": "role-TNtOQ4fB6aq6",
"name": "Drift - Admin",
"type": "ACCESS",
"status": "ACTIVE",
"description": "An admin has access to everything in Drift.",
"customAttributes": [{"code": "appIdentifier",
"value": "12345678"
},
{"code": "appLicense",
"value": "Commercial"
}
],
"applications": [{"applicationCode": "thirdpartyapp-BayOJOgTTQCM",
"applicationName": "Drift",
"applicationRoles": ["Admin"
]
}
],
"resources": [{"resourceCode": "resources-phyC7DOOteRG",
"privileges": ["read"
]
}
]
}

Search for existing access roles

Users with RITM Admin roles and with the correct platform access can retrieve access roles using this API. The search parameters are AND-ed.

Authorizations:

OAuth2APIKey

query Parameters

code	string The code of the access role. Case-sensitive and exact match.
name	string The name of the access role. By default, case-insensitive and partial match (see nameMatch parameter to overwrite).
nameMatch	string Default: "PARTIAL" Enum: "EXACT" "PARTIAL" Example: nameMatch=EXACT The way that searches are done. PARTIAL is the default and will use a case-insensitive and partial search. EXACT will use an exact, case-sensitive, search.
status	string Enum: "ACTIVE" "INACTIVE" Example: status=INACTIVE The status of the access role.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401
422

Content type

application/json

Example

One or more access roles found

{"totalItems": 1,
"limit": 10,
"page": 1,
"pageCount": 1,
"result": [{"code": "role-TNtOQ4fB6aq6",
"name": "Drift - Admin",
"description": "An admin has access to everything in Drift. The Account Owner is by default an Admin.",
"applications": [{"applicationCode": "thirdpartyapp-BayOJOgTTQCM",
"applicationName": "Drift",
"applicationRoles": ["Admin"
]
}
],
"status": "ACTIVE",
"customAttributes": [ ],
"resources": [ ],
"type": "ACCESS"
}
]
}

Retrieve an existing access role

Users with RITM Admin roles and with the correct platform access can retrieve a specific access role.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: role-TNtOQ4fB6aq6

The code of the access role.

Responses

Response samples

200
400
401
404

Content type

application/json

{"code": "role-TNtOQ4fB6aq6",
"name": "Drift - Admin",
"description": "An admin has access to everything in Drift. The Account Owner is by default an Admin.",
"applications": [{"applicationCode": "thirdpartyapp-BayOJOgTTQCM",
"applicationName": "Drift",
"applicationRoles": ["Admin"
]
}
],
"status": "ACTIVE",
"customAttributes": [ ],
"resources": [ ],
"type": "ACCESS"
}

Update an existing access role

Users with RITM Admin roles and with the correct platform access can update a specific access role.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: role-TNtOQ4fB6aq6

The code of the access role.

Request Body schema: application/json

name	string The name of the access role
description	string A short description of the access role
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" The status of the access role. Can be ACTIVE or INACTIVE.
	Array of objects Array of code/value combinations
	Array of objects Array of 3rd party application and potentially application roles
	Array of objects Array of resources and potentially privileges

Responses

Request samples

Payload

Content type

application/json

{"name": "Drift - Full admin access"
}

Response samples

200
400
401
404
422

Content type

application/json

{"code": "role-TNtOQ4fB6aq6",
"name": "Drift - Full admin access",
"description": "An admin has access to everything in Drift. The Account Owner is by default an Admin.",
"applications": [{"applicationCode": "thirdpartyapp-BayOJOgTTQCM",
"applicationName": "Drift",
"applicationRoles": ["Admin"
]
}
],
"status": "ACTIVE",
"customAttributes": [ ],
"resources": [{"resourceCode": "resources-phyC7DOOteRG",
"privileges": ["read"
]
}
],
"type": "ACCESS"
}

Update an existing access role

Users with RITM Admin roles and with the correct platform access can delete a specific access role.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: role-TNtOQ4fB6aq6

The code of the access role.

Responses

Response samples

200
400
401
404

Content type

application/json

{ }

Data - Structures

Calls related to the management of structures.

Create a new structure

Users with RITM Admin roles and with the correct platform access can create a new structure using this API.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

name required	string The name of the structure.
description	string A short description of the structure, of maximum 250 characters.
isNested required	boolean Determines whether the groups configured within the structure can be configured in a flat layout, or in a branching one.
structureType	string Default: "STATIC" Value: "STATIC" The type corresponding to the structure being created.
hasCustomAttributes	boolean Indicates whether custom attributes will be used for the groups in the structure.
	Array of objects Array of code/name combinations
hasRolesPerGroup	boolean Indicates whether roles per group will be used for the groups in the structure.
status required	string Enum: "ACTIVE" "INACTIVE" The status of the new structure. Can be active or inactive.
	Array of objects The groups within the structure.

Responses

Request samples

Payload

Content type

application/json

{"name": "Organisational Chart",
"description": "Lorem ipsum dolor sit a met",
"isNested": false,
"status": "ACTIVE",
"structureType": "STATIC",
"hasCustomAttributes": true,
"attributes": [{"code": "vatNumber",
"name": "VAT Number"
}
],
"hasRolesPerGroup": true,
"structureGroups": [{"name": "Marketing",
"code": "marketing",
"attributes": {"vatNumber": 63826382
},
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
]
}

Response samples

200
400
401
422

Content type

application/json

{"configuration": {"isNested": false,
"structureType": "STATIC"
},
"code": "structure-1234567891011",
"name": "Organisational Chart",
"description": "Lorem ipsum dolor sit a met",
"status": "ACTIVE",
"hasCustomAttributes": true,
"attributes": [{"code": "vatNumber",
"name": "VAT Number"
}
],
"hasRolesPerGroup": true,
"structureItems": [{"name": "Marketing",
"code": "marketing",
"attributes": {"vatNumber": 63826382
},
"children": [ ],
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
],
"createdBy": "8d90b808-1e93-11eb-adc1-0242ac120002"
}

Search for existing structures

Users with RITM Admin roles and with the correct platform access can retrieve structures using this API. The search parameters are AND-ed.

Authorizations:

OAuth2APIKey

query Parameters

name	string Example: name=Organisational chart The name of the structure. Case-insensitive and partial match.
code	string Example: code=structure-1234567891011 The code corresponding to the structure being retrieved. Exact match.
description	string Example: description=This structure contains the organisation's employees, grouped by job title. A short description of the structure, of maximum 250 characters. Case-insensitive and partial match.
status	string Default: "ACTIVE" Enum: "ACTIVE" "INACTIVE" Example: status=ACTIVE The status of the new structure. Can be active or inactive. Case-insensitive and exact match.
isNested	boolean Example: isNested=false isNested determines whether the groups configured within the structure can be configured in a flat layout, or in a branching one.
showInactive	boolean Example: showInactive=true If set to true also shows INACTIVE structures if status is not passed
showGroupAttributes	boolean Default: true Example: showGroupAttributes=true showGroupAttributes is an optional filter to be able to specify if custom group attributes should also be included in the response or not. By default it is set to true.
showGroupRoles	boolean Default: true Example: showGroupRoles=true showGroupRoles is an optional filter to be able to specify if group roles should also be included in the response or not. By default it is set to true.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401

Content type

application/json

Example

One or more structures found

{"totalItems": 1,
"limit": 10,
"page": 1,
"pageCount": 1,
"result": [{"configuration": {"isNested": false,
"structureType": "STATIC"
},
"code": "structure-1234567891011",
"name": "Organisational Chart",
"description": "Lorem ipsum dolor sit a met",
"status": "ACTIVE",
"hasCustomAttributes": true,
"attributes": [{"code": "vatNumber",
"name": "VAT Number"
}
],
"hasRolesPerGroup": true,
"structureGroups": [{"children": [ ],
"name": "Marketing",
"code": "marketing",
"attributes": {"vatNumber": 63826382
},
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
],
"createdBy": "8d90b808-1e93-11eb-adc1-0242ac120002"
}
]
}

Retrieve an existing structure

Users with RITM Admin roles and with the correct platform access can retrieve a specific structure by code.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: structure-1234567891011

query Parameters

showGroupAttributes	boolean Default: true Example: showGroupAttributes=false showGroupAttributes is an optional filter to be able to specify if custom group attributes should also be included in the response or not. By default it is set to true.
showGroupRoles	boolean Default: true Example: showGroupRoles=true showGroupRoles is an optional filter to be able to specify if group roles should also be included in the response or not. By default it is set to true.

Responses

Response samples

200
401
404

Content type

application/json

Example

ShowGroupAttributes is set to True

{"configuration": {"isNested": false,
"structureType": "STATIC"
},
"code": "structure-1234567891011",
"name": "Organisational Chart one",
"description": "description for Organisational",
"status": "ACTIVE",
"hasCustomAttributes": true,
"hasRolesPerGroup": true,
"attributes": [{"code": "vatNumber",
"name": "VAT Number"
}
],
"structureGroups": [{"code": "marketing",
"name": "Marketing",
"attributes": {"vatNumber": 63826382
},
"children": [ ],
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
],
"createdBy": "8d90b808-1e93-11eb-adc1-0242ac120002"
}

Update an existing structure

Users with RITM Admin roles and with the correct platform access can update a specific structure by code.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: structure-1234567891011

Request Body schema: application/json

name required	string The name of the structure.
description	string A short description of the structure, of maximum 250 characters.
isNested required	boolean Determines whether the groups configured within the structure can be configured in a flat layout, or in a branching one.
structureType	string Default: "STATIC" Value: "STATIC" The type corresponding to the structure being created.
hasCustomAttributes	boolean Indicates whether custom attributes will be used for the groups in the structure.
	Array of objects Array of code/name combinations
hasRolesPerGroup	boolean Indicates whether roles per group will be used for the groups in the structure.
status required	string Enum: "ACTIVE" "INACTIVE" The status of the new structure. Can be active or inactive.
	Array of objects The groups within the structure.

Responses

Request samples

Payload

Content type

application/json

{"name": "Organisational Chart one",
"description": "description for Organisational",
"status": "ACTIVE",
"hasCustomAttributes": true,
"attributes": [{"code": "vatNumber",
"name": "VAT Number"
}
],
"hasRolesPerGroup": true,
"structureGroups": [{"code": "marketing",
"name": "Marketing",
"attributes": {"vatNumber": 63826382
},
"children": [ ],
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
]
}

Response samples

200
401
422

Content type

application/json

{"configuration": {"isNested": false,
"structureType": "STATIC"
},
"code": "structure-1234567891011",
"name": "Organisational Chart one",
"description": "description for Organisational",
"status": "ACTIVE",
"hasCustomAttributes": true,
"attributes": [{"code": "vatNumber",
"name": "VAT Number"
}
],
"hasRolesPerGroup": true,
"structureGroups": [{"code": "marketing",
"name": "Marketing",
"attributes": {"vatNumber": 63826382
},
"children": [ ],
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
],
"createdBy": "8d90b808-1e93-11eb-adc1-0242ac120002"
}

Delete an existing structure

Users with RITM Admin roles and with the correct platform access can delete a specific structure by code.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: structure-1234567891011

Responses

Response samples

200
401
403
404

Content type

application/json

{ }

Data - Groups

Calls related to the management of groups in structures.

Create a new group

Users with RITM Admin roles and with the correct platform access can create a new group using this API.

Authorizations:

OAuth2APIKey

Request Body schema: application/json

code required	string The code corresponding to the group being created.
name required	string The name of the group.
structureCode required	string The code corresponding to the structure that the group belongs to.
groupParent	string If there is a parent, the code of the parent group.
	object
	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"code": "test4",
"name": "name for test 4",
"structureCode": "structure-1234567891011",
"groupParent": "test3",
"attributes": {"vatNumber": 63826383
},
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}

Response samples

Content type

application/json

{"configuration": {"isNested": true,
"structureType": "STATIC"
},
"code": "structure-1234567891011",
"name": "home",
"description": "test description",
"status": "ACTIVE",
"hasCustomAttributes": true,
"hasRolesPerGroup": true,
"structureGroups": [{"name": "name for test 3",
"code": "test3",
"attributes": {"vatNumber": 63826382
},
"children": [{"name": "name for test 4",
"code": "test4",
"attributes": {"vatNumber": 63826383
},
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
]
}
],
"createdBy": "8d90b808-1e93-11eb-adc1-0242ac120002"
}

Search for existing groups

Users with RITM Admin roles and with the correct platform access can retrieve groups using this API.

Authorizations:

OAuth2APIKey

query Parameters

name	string Example: name=Organisational chart The name of the group. Case-sensitive and exact match.
code	string Example: code=group-1234567891011 The code corresponding to the group being retrieved. Case-sensitive and exact match.
structureCode required	string Example: structureCode=structure-1234567891011 The code corresponding to the structure that the group belongs to. Case-sensitive and exact match.
groupParent	string Example: groupParent=group-26382930263820 If the case, code of the parent group. Case-sensitive and exact match.
limit	integer Default: 10 The number of items to return per page. Zero (0) means the highest allowed limit (currently not restricted)
page	integer Default: 1 This is the page number for a paginated response (where typically the number of pages is the total amount of items divided by the limit parameter)

Responses

Response samples

200
400
401

Content type

application/json

{"totalItems": 79,
"limit": 10,
"page": 1,
"pageCount": 8,
"result": [{"code": "test11",
"name": "test11",
"attributes": {"vatNumber": 6383982
},
"children": [{"children": [ ],
"code": "test21",
"name": "test21",
"attributes": {"vatNumber": 63826382
},
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}
]
},
{"code": "test01",
"name": "test01",
"children": [ ]
},
{"code": "test02",
"name": "group test 21",
"attributes": {"vatNumber": 1425361
},
"children": [ ]
},
{"code": "test03",
"name": "group test 31",
"attributes": {"vatNumber": 62839263
},
"children": [ ]
}
]
}

Retrieve an existing group

Users with RITM Admin roles and with the correct platform access can retrieve a specific group by code.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: group-1234567891011

query Parameters

structureCode

required

string

Example: structureCode=structure-1234567891011

Responses

Response samples

200
400
401
404

Content type

application/json

{"code": "test12",
"name": "test12",
"attributes": {"vatNumber": 63826382
},
"children": [ ],
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}

Update an existing group

Users with RITM Admin roles and with the correct platform access can update a specific group by code.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: group-1234567891011

query Parameters

moveTo	string Example: moveTo=group-1234567891011 moveTo is an optional filter that allows you to move a group to another parent group, in static, nested structures. Cannot be used in combination with the moveToLevel1 parameter.
moveToLevel1	boolean Example: moveToLevel1=true moveToLevel1 is an optional filter that allows you to move a group to level 1, in static, nested structures. Cannot be used in combination with the moveTo parameter.

Request Body schema: application/json

name	string The new name of the group.
structureCode required	string The code corresponding to the structure that the group belongs to.
groupParent	string If there is a parent, the code of the parent group.
	object
	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"name": "new name for group",
"structureCode": "structure-1234567891011",
"groupParent": "test3",
"attributes": {"vatNumber": 63826382
},
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}

Response samples

200
400
401
404
422

Content type

application/json

{"name": "new name for group",
"code": "group-1234567891011",
"attributes": {"vatNumber": 63826382
},
"children": [ ],
"roles": [{"code": "role-673f20jvsklwh",
"type": "ACCESS"
},
{"code": "role-63nso3bs9ln",
"type": "ADMIN"
}
]
}

Delete an existing group

Users with RITM Admin roles and with the correct platform access can delete a specific group by code.

Authorizations:

OAuth2APIKey

path Parameters

code

required

string

Example: group-1234567891011

query Parameters

structureCode

required

string

Example: structureCode=structure-1234567891011

Responses

Response samples

200
400
401
404

Content type

application/json

{ }