Returns a Recommendation Based on Object

POST 
/recommendations/request

experimental

This API is currently in an experimental state. The API is subject to change based on feedback and further testing. You must include the X-SailPoint-Experimental header and set it to true to use this endpoint.

The getRecommendations API returns recommendations based on the requested object. The recommendations are invoked by IdentityIQ and IdentityNow plug-ins that retrieve recommendations based on the performed calculations.

Request

Header Parameters

X-SailPoint-Experimental stringrequired
Default value: true
Use this header to enable this experimental API.
Example: true

application/json

Body

required

requests

object[]

Array [

identityId string

The identity ID

item

object

id string

ID of the access item to retrieve the recommendation for.

type string

Possible values: [ENTITLEMENT, ACCESS_PROFILE, ROLE]

Access item's type.

]

excludeInterpretations boolean

Default value: false

Exclude interpretations in the response if "true". Return interpretations in the response if this attribute is not specified.

includeTranslationMessages boolean

Default value: false

When set to true, the calling system uses the translated messages for the specified language

includeDebugInformation boolean

Default value: false

Returns the recommender calculations if set to true

prescribeMode boolean

Default value: false

When set to true, uses prescribedRulesRecommenderConfig to get identity attributes and peer group threshold instead of standard config.

Responses

200

The recommendations for a customer

application/json

Schema

Schema

response

object[]

Array [

request

object

identityId string

The identity ID

item

object

id string

ID of the access item to retrieve the recommendation for.

type string

Possible values: [ENTITLEMENT, ACCESS_PROFILE, ROLE]

Access item's type.

recommendation string

Possible values: [YES, NO, MAYBE, NOT_FOUND]

The recommendation - YES if the access is recommended, NO if not recommended, MAYBE if there is not enough information to make a recommendation, NOT_FOUND if the identity is not found in the system

interpretations string[]

The list of interpretations explaining the recommendation. The array is empty if includeInterpretations is false or not present in the request. e.g. - [ "Not approved in the last 6 months." ]. Interpretations will be translated using the client's locale as found in the Accept-Language header. If a translation for the client's locale cannot be found, the US English translation will be returned.

translationMessages

object[]

The list of translation messages, if they have been requested.

Array [

key string

The key of the translation message

values string[]

The values corresponding to the translation messages

]

recommenderCalculations

RecommenderCalculations

The calcuations performed behind the scenes that provide recommendations to the user.

identityId string

The ID of the identity

entitlementId string

The entitlement ID

recommendation string

The actual recommendation

overallWeightedScore number

The overall weighted score

featureWeightedScores

object

The weighted score of each individual feature

property name* number

threshold number

The configured value against which the overallWeightedScore is compared

identityAttributes

object

The values for your configured features

property name*

object

value string

featureValues

object

The feature details

feature string

The type of feature

numerator int32

The number of identities that have access to the feature

denominator int32

The number of identities with the corresponding feature

]

Example (from schema)

{
  "response": [
    {
      "request": {
        "identityId": "2c938083633d259901633d25c68c00fa",
        "item": {
          "id": "2c938083633d259901633d2623ec0375",
          "type": "ENTITLEMENT"
        }
      },
      "recommendation": "YES",
      "interpretations": [
        "75% of identities with the same department have this access. This information had a high impact on the overall score.",
        "67% of identities with the same peer group have this access. This information had a low impact on the overall score.",
        "42% of identities with the same location have this access. This information had a low impact on the overall score."
      ],
      "translationMessages": [
        {
          "key": "recommender-api.V2_WEIGHT_FEATURE_PRODUCT_INTERPRETATION_HIGH",
          "values": [
            "75",
            "department"
          ]
        }
      ],
      "recommenderCalculations": {
        "identityId": "2c91808457d8f3ab0157e3e62cb4213c",
        "entitlementId": "2c91809050db617d0150e0bf3215385e",
        "recommendation": "YES",
        "overallWeightedScore": 0,
        "featureWeightedScores": {},
        "threshold": 0,
        "identityAttributes": {},
        "featureValues": {
          "feature": "department",
          "numerator": 14,
          "denominator": 14
        }
      }
    }
  ]
}

400

Client Error - Returned if the request body is invalid.

application/json

Schema

Schema

detailCode string

Fine-grained error code providing more detail of the error.

trackingId string

Unique tracking id for the error.

messages

object[]

Generic localized reason for error

Array [

locale stringnullable

The locale for the message text, a BCP 47 language tag.

localeOrigin LocaleOrigin (string)nullable

Possible values: [DEFAULT, REQUEST, null]

An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.

text string

Actual text of the error message in the indicated locale.

]

causes

object[]

Plain-text descriptive reasons to provide additional detail to the text provided in the messages field

Array [

locale stringnullable

The locale for the message text, a BCP 47 language tag.

localeOrigin LocaleOrigin (string)nullable

Possible values: [DEFAULT, REQUEST, null]

An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.

text string

Actual text of the error message in the indicated locale.

]

Example (from schema)

{
  "detailCode": "400.1 Bad Request Content",
  "trackingId": "e7eab60924f64aa284175b9fa3309599",
  "messages": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "The request was syntactically correct but its content is semantically invalid."
    }
  ],
  "causes": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "The request was syntactically correct but its content is semantically invalid."
    }
  ]
}

401

Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.

application/json

Schema

Schema

error

A message describing the error

Example (from schema)

{
  "error": "JWT validation failed: JWT is expired"
}

403

Forbidden - Returned if the user you are running as, doesn't have access to this end-point.

application/json

Schema

Schema

detailCode string

Fine-grained error code providing more detail of the error.

trackingId string

Unique tracking id for the error.

messages

object[]

Generic localized reason for error

Array [

locale stringnullable

The locale for the message text, a BCP 47 language tag.

localeOrigin LocaleOrigin (string)nullable

Possible values: [DEFAULT, REQUEST, null]

An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.

text string

Actual text of the error message in the indicated locale.

]

causes

object[]

Plain-text descriptive reasons to provide additional detail to the text provided in the messages field

Array [

locale stringnullable

The locale for the message text, a BCP 47 language tag.

localeOrigin LocaleOrigin (string)nullable

Possible values: [DEFAULT, REQUEST, null]

An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.

text string

Actual text of the error message in the indicated locale.

]

Example (from schema)

{
  "detailCode": "400.1 Bad Request Content",
  "trackingId": "e7eab60924f64aa284175b9fa3309599",
  "messages": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "The request was syntactically correct but its content is semantically invalid."
    }
  ],
  "causes": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "The request was syntactically correct but its content is semantically invalid."
    }
  ]
}

403

An example of a 403 response object

{
  "detailCode": "403 Forbidden",
  "trackingId": "b21b1f7ce4da4d639f2c62a57171b427",
  "messages": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "The server understood the request but refuses to authorize it."
    }
  ]
}

429

Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.

application/json

Schema

Schema

message

A message describing the error

Example (from schema)

{
  "message": " Rate Limit Exceeded "
}

500

Internal Server Error - Returned if there is an unexpected error.

application/json

Schema

Schema

detailCode string

Fine-grained error code providing more detail of the error.

trackingId string

Unique tracking id for the error.

messages

object[]

Generic localized reason for error

Array [

locale stringnullable

The locale for the message text, a BCP 47 language tag.

localeOrigin LocaleOrigin (string)nullable

Possible values: [DEFAULT, REQUEST, null]

An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.

text string

Actual text of the error message in the indicated locale.

]

causes

object[]

Plain-text descriptive reasons to provide additional detail to the text provided in the messages field

Array [

locale stringnullable

The locale for the message text, a BCP 47 language tag.

localeOrigin LocaleOrigin (string)nullable

Possible values: [DEFAULT, REQUEST, null]

An indicator of how the locale was selected. DEFAULT means the locale is the system default. REQUEST means the locale was selected from the request context (i.e., best match based on the Accept-Language header). Additional values may be added in the future without notice.

text string

Actual text of the error message in the indicated locale.

]

Example (from schema)

{
  "detailCode": "400.1 Bad Request Content",
  "trackingId": "e7eab60924f64aa284175b9fa3309599",
  "messages": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "The request was syntactically correct but its content is semantically invalid."
    }
  ],
  "causes": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "The request was syntactically correct but its content is semantically invalid."
    }
  ]
}

500

An example of a 500 response object

{
  "detailCode": "500.0 Internal Fault",
  "trackingId": "b21b1f7ce4da4d639f2c62a57171b427",
  "messages": [
    {
      "locale": "en-US",
      "localeOrigin": "DEFAULT",
      "text": "An internal fault occurred."
    }
  ]
}

Loading...