Get a unit by external ID

GET /nevisidm/api/core/v1/:clientExtId/units/:extId

Since: 2.71.0

Required permission(s): AccessControl.UnitView

Returns the unit with the given external ID within the specified client, including its language-dependent display names and abbreviations.

Request

Path Parameters

clientExtId stringrequired

External ID of the client.

Example: client-123

extId stringrequired

External ID of the unit.

Example: unit-123

Responses

Unit found

application/json

Schema
Example (from schema)

Schema

created string

Creation date of the entity.

lastModified string

Date when the entity was last modified.

version int32

Version used for optimistic locking.

extId string

The external ID of the unit.

parentUnitExtId string

The external ID of the parent unit.

clientExtId string

The external ID of the client the unit belongs to.

hierarchicalName string

The path from the root unit to the actual unit. The external IDs of the units are concatenated with the '/' character.

name string

The name of the unit.

location string

Free textual description of the physical location of the unit.

description string

The textual description of the unit.

state string

Possible values: [active, disabled]

The state of the unit.

displayName object

Language-dependent name of the unit. Keys: EN, DE, FR, IT.

property name* string

abbreviation object

Short form of the unit name. Keys: EN, DE, FR, IT.

property name* string

profileless boolean

Determines whether profile assignment is allowed.

modificationComment string

Textual comment regarding the last modification.

validity object

The validity period of the unit entity.

from string

Start date of the entity's validity in ISO format.

to string

End date of the entity's validity in ISO format.

{
  "created": "2023-08-18T12:34:56Z",
  "lastModified": "2023-08-18T12:34:56Z",
  "version": 1,
  "extId": "unit-123",
  "parentUnitExtId": "parent-unit-123",
  "clientExtId": "client-123",
  "hierarchicalName": "root/parent-unit-123/unit-123",
  "name": "Engineering",
  "location": "Building A, Floor 3",
  "description": "Engineering department",
  "state": "active",
  "displayName": {
    "EN": "Engineering",
    "DE": "Technik"
  },
  "abbreviation": {
    "EN": "ENG",
    "DE": "TECH"
  },
  "profileless": false,
  "modificationComment": "Updated by admin",
  "validity": {
    "from": "2023-01-01T00:00:00Z",
    "to": "2033-12-31T23:59:59Z"
  }
}

Insufficient permissions

application/json

Schema
Example (from schema)
Permission denied
Dataroom permission denied

Schema

errors ErrorMessageDTO[]

Possible values: [errors.fatalError, errors.unknownReason, errors.inconsistentData, errors.duplicateName, errors.invalidData, errors.duplicateValue, errors.duplicateEmail, errors.duplicateMobile, errors.undeletedDependencies, errors.noRecord, errors.invalidConfig, errors.missingReferenceData, errors.recordDeleted, errors.modifyReadonlyData, errors.tooManySearchResults, errors.pessimisticLockingFailure, errors.policyViolation, errors.deleteDefaultEntityFailure, errors.emailChannel, errors.noSmtpConnection, errors.SmtpNotConfigured, errors.propertyUniquenessViolated, errors.property.stringmaxlen, errors.property.stringregex, errors.property.regexinv, errors.pwdPolicyViolated, errors.certificatePolicyViolated, errors.identifierPolicyViolated, errors.passwordExists, errors.mtanFormatViolated, errors.mtanFormatE164Violated, errors.tempStrongPasswordExists, errors.safewordExists, errors.securidExists, errors.ticketExists, errors.kerberosExists, errors.tooManyOTPCards, errors.urlTicketMissingURLPrefix, errors.certificateExists, errors.vascoExists, errors.PUKExists, errors.URLTicketExists, errors.mobileSignatureExists, errors.securityQuestionsExists, errors.recoveryCodeExists, errors.securityQuestionsMaxReached, errors.qrCodeGenerationFailed, errors.oathSecretIsShared, errors.nocertcred, errors.CredTypeUnitPolicyViolated, errors.CredTypeClientPolicyViolated, errors.credentialNotActive, errors.dimensionNotMatch, errors.noTemplate, errors.pdfPrintingFailure, errors.missingMandatoryPlaceholder, errors.defaultCollectionDelete, errors.tableTypeMismatch, errors.nullRequestBody, errors.deserialization, errors.nullParameter, errors.invalidParameter, errors.invalidDate, errors.invalidDateOrDateTime, errors.invalidDateInterval, errors.invalidMobile, errors.mobileCannotBeDeleted, errors.mobileMissing, errors.userLoginIdNull, errors.userLoginFailed, errors.userLoginFailed, errors.userLoginFailed, errors.userLoginFailed, errors.userLoginFailed, errors.userLoginFailed, errors.userLoginFailed, errors.userNameNull, errors.userFirstNameNull, errors.userSexNull, errors.userCountryNull, errors.userEmailNull, errors.userMobileNull, errors.userPhoneFormat, errors.userEmailFormat, errors.msisdnFormat, errors.applicationNameNull, errors.credentialFidoUaf.invalidAuthVersionFormat, errors.credentialFidoUaf.invalidPublicKeyAlgorithm, errors.credentialFidoUaf.invalidKeyIdFormat, errors.credentialFidoUaf.invalidAaidFormat, errors.credentialFidoUaf.emptyAppId, errors.credentialFidoUaf.notUnique, errors.msspIdentifierMissing, errors.invalidTimeInterval, errors.unitInvalidValidityPeriodParent, errors.unitInvalidValidFromParameterParent, errors.unitInvalidValidUntilParameterParent, errors.unitInvalidValidityPeriodChild, errors.unitInvalidValidFromParameterChild, errors.unitInvalidValidUntilParameterChild, errors.noClientFound, errors.inconsistentClientAssignment, errors.noDefaultUnitInClient, errors.samlAttributeFormat, errors.insufficientRightsFunction, errors.maxResetCount, errors.insufficientFineGrainedRights, errors.potentialPrivilegeEscalation, errors.applDataroomDenied, errors.unitDataroomDenied, errors.eRoleDataroomDenied, errors.combinedDataroomDenied, errors.clientDataroomDenied, errors.referenceDataChangeDenied, errors.attrAccessForbidden, errors.filesystemIO, errors.reporting.tooManyRequests, errors.modifyArchivedUser, errors.modifyArchivedCredential, errors.archiveCredentialDenied, errors.modifyArchivedProfile, errors.assignDisabledUnit, errors.assignProfilelessUnit, errors.profilelessFlagCannotBeSet, errors.modifyExtId, errors.docTypeNotModifiable, errors.addIdmToApplDataroom, errors.applicationLimitsDataroomUnitsMaxExceeded, errors.assignSubunitAsParent, errors.history.norecord, errors.loginIdGeneratorFailed, errors.fileupload.vasco, errors.techUser.oneProfile, errors.urlTicket.invalidFormat, errors.passwordChangeDeadlineExceeded, errors.pcyconf.invalidParamValue, errors.pcyconf.missingParam, errors.pcyconf.missingProfilePolicy, errors.pcyconf.multipleClientPolicy, errors.pcyconf.invalidParamName, errors.userImport.fileupload.invalidTemplate, errors.enterpriseRolesDisabled, errors.queryServiceDisabled, errors.serviceDisabled, errors.invalidUri, errors.unsupportedMediaType, errors.jsonProcessingError, errors.unsupportedOperation, errors.unsupportedCredentialTypeToCreate, errors.unsupportedCredentialTypeToDelete, errors.credentialTypeWithoutProperties, errors.invalidAssignIdmroleToErole, errors.invalidJWTToken, errors.modifyProtectedFieldInvalidJWTToken, errors.optimisticLockingFailure, errors.deleteDefaultUnitCredPolicyFailure, errors.otherGenderPolicyDisabled, error.login.userState, error.job.execution.failure, errors.invalidSyntax, errors.mandatoryParameterMissing, errors.fieldIsNotIndexed, errors.fieldIsNotDirectlyIndexed, errors.entityManagerNotOpen, errors.unsuccessfulQuery, errors.queryHasTimedOut, errors.emailPolicyViolated, errors.policyInconsistency]

A list of error messages describing the error(s) that occurred.

Array [

identifier object

The identifier of the entity related to the error, only used in certain error cases for BULK actions.

oneOf

CredentialExtIdIdentifierDTO
FidoUafIdentifier

clientExtId string

The external identifier of the client.

userExtId string

The external identifier of the user.

credentialExtId string

The external identifier of the credential.

code string

The error code identifying the type of error.

message string

A human-readable message providing more details about the error.

]

policyViolations PolicyViolationDTO[]

A list of policy violations that caused the error.

Array [

displayName string

The display name of the policy element that was violated.

configString string

The configuration string of the policy element that was violated.

suppliedValue string

The value that was supplied and caused the policy violation.

limitValue int32

The limit value defined in the policy element that was violated.

actualValue string

The actual value that caused the policy violation.

]

policyViolation PolicyElementViolation

cause object

stackTrace object[]

Array [

classLoaderName string

moduleName string

moduleVersion string

methodName string

fileName string

lineNumber int32

className string

nativeMethod boolean

]

message string

localizedMessage string

stackTrace object[]

Array [

classLoaderName string

moduleName string

moduleVersion string

methodName string

fileName string

lineNumber int32

className string

nativeMethod boolean

]

element PolicyElement

displayName string

messageTag string

infoTag string

limitValue int32

configString string

suppliedValue string

actualvalue string

description string

message string

suppressed object[]

Array [

stackTrace object[]

Array [

classLoaderName string

moduleName string

moduleVersion string

methodName string

fileName string

lineNumber int32

className string

nativeMethod boolean

]

message string

localizedMessage string

]

localizedMessage string

{
  "errors": [
    {
      "code": "errors.fatalError",
      "message": "The user with the given external ID was not found."
    }
  ],
  "policyViolations": [
    {
      "displayName": "string",
      "configString": "string",
      "suppliedValue": "4",
      "limitValue": 3,
      "actualValue": "5"
    }
  ],
  "policyViolation": {
    "cause": {
      "stackTrace": [
        {
          "classLoaderName": "string",
          "moduleName": "string",
          "moduleVersion": "string",
          "methodName": "string",
          "fileName": "string",
          "lineNumber": 0,
          "className": "string",
          "nativeMethod": true
        }
      ],
      "message": "string",
      "localizedMessage": "string"
    },
    "stackTrace": [
      {
        "classLoaderName": "string",
        "moduleName": "string",
        "moduleVersion": "string",
        "methodName": "string",
        "fileName": "string",
        "lineNumber": 0,
        "className": "string",
        "nativeMethod": true
      }
    ],
    "element": {
      "displayName": "string",
      "messageTag": "string",
      "infoTag": "string",
      "limitValue": 0,
      "configString": "string"
    },
    "suppliedValue": "string",
    "actualvalue": "string",
    "description": "string",
    "message": "string",
    "suppressed": [
      {
        "stackTrace": [
          {
            "classLoaderName": "string",
            "moduleName": "string",
            "moduleVersion": "string",
            "methodName": "string",
            "fileName": "string",
            "lineNumber": 0,
            "className": "string",
            "nativeMethod": true
          }
        ],
        "message": "string",
        "localizedMessage": "string"
      }
    ],
    "localizedMessage": "string"
  }
}

{
  "errors": [
    {
      "code": "errors.insufficientRightsFunction",
      "message": "Permission denied: Caller does not have the required right 'AccessControl.UnitView' to perform this action"
    }
  ]
}

{
  "errors": [
    {
      "code": "errors.combinedDataroomDenied",
      "message": "Permission denied: AccessControl.UnitView"
    }
  ]
}

Referenced resource not found

application/json

Schema
Example (from schema)
Client not found
Unit not found

Schema

errors ErrorMessageDTO[]

A list of error messages describing the error(s) that occurred.

Array [

identifier object

The identifier of the entity related to the error, only used in certain error cases for BULK actions.

oneOf

CredentialExtIdIdentifierDTO
FidoUafIdentifier

clientExtId string

The external identifier of the client.

userExtId string

The external identifier of the user.

credentialExtId string

The external identifier of the credential.

code string

The error code identifying the type of error.

message string

A human-readable message providing more details about the error.

]

policyViolations PolicyViolationDTO[]

A list of policy violations that caused the error.

Array [

displayName string

The display name of the policy element that was violated.

configString string

The configuration string of the policy element that was violated.

suppliedValue string

The value that was supplied and caused the policy violation.

limitValue int32

The limit value defined in the policy element that was violated.

actualValue string

The actual value that caused the policy violation.

]

policyViolation PolicyElementViolation

cause object

stackTrace object[]

Array [

classLoaderName string

moduleName string

moduleVersion string

methodName string

fileName string

lineNumber int32

className string

nativeMethod boolean

]

message string

localizedMessage string

stackTrace object[]

Array [

classLoaderName string

moduleName string

moduleVersion string

methodName string

fileName string

lineNumber int32

className string

nativeMethod boolean

]

element PolicyElement

displayName string

messageTag string

infoTag string

limitValue int32

configString string

suppliedValue string

actualvalue string

description string

message string

suppressed object[]

Array [

stackTrace object[]

Array [

classLoaderName string

moduleName string

moduleVersion string

methodName string

fileName string

lineNumber int32

className string

nativeMethod boolean

]

message string

localizedMessage string

]

localizedMessage string

{
  "errors": [
    {
      "code": "errors.fatalError",
      "message": "The user with the given external ID was not found."
    }
  ],
  "policyViolations": [
    {
      "displayName": "string",
      "configString": "string",
      "suppliedValue": "4",
      "limitValue": 3,
      "actualValue": "5"
    }
  ],
  "policyViolation": {
    "cause": {
      "stackTrace": [
        {
          "classLoaderName": "string",
          "moduleName": "string",
          "moduleVersion": "string",
          "methodName": "string",
          "fileName": "string",
          "lineNumber": 0,
          "className": "string",
          "nativeMethod": true
        }
      ],
      "message": "string",
      "localizedMessage": "string"
    },
    "stackTrace": [
      {
        "classLoaderName": "string",
        "moduleName": "string",
        "moduleVersion": "string",
        "methodName": "string",
        "fileName": "string",
        "lineNumber": 0,
        "className": "string",
        "nativeMethod": true
      }
    ],
    "element": {
      "displayName": "string",
      "messageTag": "string",
      "infoTag": "string",
      "limitValue": 0,
      "configString": "string"
    },
    "suppliedValue": "string",
    "actualvalue": "string",
    "description": "string",
    "message": "string",
    "suppressed": [
      {
        "stackTrace": [
          {
            "classLoaderName": "string",
            "moduleName": "string",
            "moduleVersion": "string",
            "methodName": "string",
            "fileName": "string",
            "lineNumber": 0,
            "className": "string",
            "nativeMethod": true
          }
        ],
        "message": "string",
        "localizedMessage": "string"
      }
    ],
    "localizedMessage": "string"
  }
}

{
  "errors": [
    {
      "code": "errors.noRecord",
      "message": "Client doesn't exist with extId 'client-123'"
    }
  ]
}

{
  "errors": [
    {
      "code": "errors.noRecord",
      "message": "Unit with extId 'unit-123' doesn't exist on client with extId 'client-123'"
    }
  ]
}

Get a unit by external ID

/nevisidm/api/core/v1/:clientExtId/units/:extId

Request​

Path Parameters

Responses​

Request

Responses