NextGen APIs

GET /integration/configurations/identity/r1/users

Http Verb

GET

Url

/integration/configurations/identity/r1/users

Permissions required

User’s types: View user’s type (foundation.base.userType.view)

User’s types: Edit user’s type (foundation.base.userType.edit)

User’s: View users (foundation.base.user.view)

Users: Edit user (foundation.base.user.edit)

Last Modified Version

r1

Tech Tags

MULTILANGUAGE-FIELDS

Available Async

No

BPMN Diagram (TBD)


Business Logic

This Integration API retrieves the users present in a system.

System verifies Permission Required and starts the elaboration that is organized in steps.

STEP 1 - External System Validation

System takes Input fields and checks their existence in internal configuration.

API Verb: GET

Resource: External Systems

Input: externalSystemCode, active=true

Output: externalSystemId

If System can obtain the Output fields → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

STEP 2 - User Retrieve

System takes Input fields and checks their existence in internal configuration.

API Verb: GET

Resource: Users

Input: email, startDate, endDate, onlyValid, _page

Output: email, startDate, endDate, language, typeId, list of [additionalRoleId], name, surname, username

If System can obtain the Output fields → continue to the next step

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:
Others - see link in Resource

STEP 3 - User Type Transcode

System takes Input fields and gets the resource.

API Verb: GET

Resource: User Types

Input: typeId, list of [additionalRoleId]

Output: typeCode

If System can obtain the Output fields → Elaboration is stopped.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

  • Others - see link in Resource

Path Parameters

As their name suggests, they are included in the URL path of the endpoint.

Not applicable.

Query String Parameters

Start with a ? and includes parameters listed one after the another separated by &.

Filter

Field

Description

Mandatory

Constraint

1

_page

Object for pagination

N

Null or Not Blank

2

externalSystemCode

External System Code

Y


3

email

Email

N

Null or Not Blank

4

startDate

Interval of date (from-to) of resource start date for filtering

N


5

endDate

Interval of date (from-to) of resource end date for filtering

N


6

onlyValid

Flag to extract ony users with a valid period

N


Fields

The parameter _fields allows to choose output fields. More info here How to use APIs: Output fields selection.

Header Parameters

Parameters included in the request headers. Generally, request headers are used to keep authorization parameters.

Default.

Request example

HTML
{baseUrl}/integration/configurations/identity/r1/users?externalSystemCode=SAP

Response documentation

Response payload fields

Field

Field Type

Description

1

email


Email

2

type

typeObject

User Type

3

additionalRoles

additionRolesObject

User Additional Types

4

language


User Language

5

startDate


Start validity date

6

endDate


End validity date

typeObject

Field

Description

1

code

User Type Code

2

description

User Type Description

additionRolesObject


Field

Description

1

typeObject

(minOccurs=0,

maxOccurs=N)

code

User Type Code

2

description

User Type Description


Compliant with RFC Standard https://www.rfc-editor.org/rfc/rfc9457.html

Extension fields:

Field

Description

Note

code

Extension member of a Problem Details Object that contains the error code

Only for ERROR

Response example

JSON
{
  "email": "john.smith@example.com",
  "type": {
    "code": "TECH",
    "description": "TECHNICIAN"
  },
  "additionalRoles": [
    {
      "type": {
        "code": "DISP",
        "description": "DISP"
      }
    }
  ],
  "startDate": "2026-07-20T00:00:00Z",
  "endDate": "2026-12-31T23:59:59Z"
}

Error example

JSON
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "External system string does not exist",
  "instance": "/integration/workforce/r1/resource-skills",
  "code": "IA001_001"
}

 Response error codes