# Identity Insights Solutions Request Parameters source: https://developer.mastercard.com/identity-insights-solutions/documentation/tutorials-and-guides/data-explanations/iis-request/index.md ## Overview {#overview} The products available on the Identity Insights Solutions API are designed to provide a holistic assessment of risk across all aspects of an identity. To achieve the optimal efficacy for your use case, it is recommended that you share as many of the inputs available on the API when requesting insights. As the Identity Risk Score calculates the overall risk across all aspects of the identity, a minimum of three of the major inputs listed, must be present in the request for it to be returned: * Name (Primary or Secondary) * Email Address (Primary or Secondary) * Phone Number (Primary 1 or Primary 2 or Secondary) * Address (Primary or Secondary) * Payment Account Number (Funding PAN, Device Token, Network Token) * IP Address (IPv4 or IPv6) * Device Details (All of User-Agent, Screen Width/Height, Timezone, Language) ### Request Parameters {#request-parameters} | **Attribute** | **Description** | **Application** | |--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| | accountDetails.accAgeInd | Length of time that the cardholder has had the account with the Requestor. Values Accepted: * 01 = No account (guest checkout) * 02 = Created during this transaction * 03 = Less than 30 days * 04 = 30 - 60 days * 05 = More than 60 days | Issuer Data Share only | | accountDetails.accChange | Date that the cardholder's account with the Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. Converted to UTC. | Issuer Data Share only | | accountDetails.accPwChange | Date that the cardholder's account with the Requestor had a password change or account reset. | Issuer Data Share only | | accountDetails.txnActivityDay | Number of transactions, successful and abandoned, for this cardholder account with the Requestor across all payment accounts in the previous 24 hours. | Issuer Data Share only | | accountDetails.txnActivityYear | Number of transactions, successful and abandoned, for this cardholder account with the Requestor across all payment accounts in the previous year. | Issuer Data Share only | | deviceDetails.colorDepth | The value representing the bit depth of the color palette for displaying images, in bits per pixel. | Insights and Issuer Data Share | | deviceDetails.deviceId | A unique, persistent, and unchangeable identifier\* assigned to a physical or logical device that is consistently associated across all transactions with the same device for a given merchant. | Insights and Issuer Data Share | | deviceDetails.deviceLatitude | The latitude of the consumer's device. | Issuer Data Share only | | deviceDetails.deviceLongitude | The longitude of the consumer's device. | Issuer Data Share only | | deviceDetails.deviceType | An indicator of the type of device used for the purchase. Phone, Tablet, Computer or Others. * 01 = Phone * 02 = Tablet * 03 = Computer * 04 = Other | Issuer Data Share only | | deviceDetails.ipAddress | The IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in every set is in the range 0 to 255. The IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits. The groups are separated by colons (:). Required to generate device risk score | Insights and Issuer Data Share | | deviceDetails.language | The language of the consumer device. The language must be a string representing the language version as defined in BCP-47. Required to generate device risk score | Insights and Issuer Data Share | | deviceDetails.screenHeight | The screen height of the consumer device in pixels, attempting to authorize with your product or service. Required to generate device risk score | Insights and Issuer Data Share | | deviceDetails.screenWidth | The screen width of the consumer device in pixels, attempting to authorize with your product or service. Required to generate device risk score | Insights and Issuer Data Share | | deviceDetails.sdkAppID | A universally unique ID created upon all installations of the merchant app on a consumer device. This will be newly generated and stored by the SDK for each installation. | Issuer Data Share only | | deviceDetails.sdkMajorVersion | Major operating system version. | Insights and Issuer Data Share | | deviceDetails.sdkMinorVersion | Minor operating system version. | Insights and Issuer Data Share | | deviceDetails.sdkModel | Mobile device manufacturer and mode lAndroid: Build.MANUFACTURER + " " + Build.MODEL returns the mobile device manufacturer and model, for example,"samsung SM-G960U1". iOS: utsname.machine returns the device model, for example, "iPhone10.4". Note: Apple as a manufacturer is not included because it is the same for all iOS devices. | Insights and Issuer Data Share | | deviceDetails.timeZone | Time zone offset in minutes between UTC and the device local time. It must be an Integer in the range of -720 to 840, coded as a string. Required to generate device risk score | Insights and Issuer Data Share | | deviceDetails.userAgent | The user-agent string of the consumer device attempting to authorize with your product or service. The user-agent must represent the HTTP client of the service consumer with details on the software originating the request. Required to generate device risk score | Insights and Issuer Data Share | | endCustomerReferenceId | A unique identifier for the end-customer on a reseller's platform where the solution is being resold. Enables Mastercard to be able to share reports with resellers that are segregated by their end-customers. | Insights and Issuer Data Share | | merchantDetails.acquirerBin | The BIN (Bank Identification Number) of the acquirer. | Insights and Issuer Data Share | | merchantDetails.acquirerMerchantId | An Acquirer assigned merchant identifier. It is the same value used in the authorization request. | Issuer Data Share only | | merchantDetails.categoryCode | The Merchant Category Code associated with the transaction. | Insights and Issuer Data Share | | merchantDetails.countryCode | The ISO-3166 numeric country code of the merchant associated with the transaction. See: ISO-3166. | Insights and Issuer Data Share | | merchantDetails.name | The name of the merchant from whom a transaction originates from | Insights and Issuer Data Share | | merchantTrustAssessment.additionalSignals | Additional signals/insights about the transaction. | Issuer Data Share only | | merchantTrustAssessment.merchantRiskScore | Merchant / Partner's transaction risk assessment converted into a scale. 0: Lowest Risk 9: Highest Risk | Issuer Data Share only | | merchantTrustAssessment.refundGuarantee | A signal that represents refund guarantee/auth boost by Auth Boost customer -- only applicable for the Auth Boost customers that are separately enrolled for Auth Boost through API. | Issuer Data Share only | | paymentMethodDetails.accountNumber | A unique identifier for the Primary Account Number or Token associated with transaction. When tokenized values are provided, the extent of the insights provided will be constrained by the context of the token (Device, Network, Acquirer, and so on). | Insights and Issuer Data Share | | paymentMethodDetails.cardBin | The first six to eight digits of the funding PAN. | Insights and Issuer Data Share | | paymentMethodDetails.cardExpiryDate | The expiry date of the funding PAN. | Insights and Issuer Data Share | | paymentMethodDetails.cardLast4 | The last 4 digits of the funding PAN. | Insights and Issuer Data Share | | paymentMethodDetails.isCardOnFile | "True" when a card stored on file is used for purchase else "False". | Issuer Data Share only | | primaryPersonDetails.address | The postal address of the primary person in the request. Where multiple persons are party to the transaction, the primary person is the person directly associated with the payment credential the transaction. For any address insights to be returned the address must be resolvable to at least the city. | Insights and Issuer Data Share | | primaryPersonDetails.emailAddress | The email address of the primary person in the request. Where multiple persons are party to the transaction, the primary person is the person directly associated with the payment credential the transaction. | Insights and Issuer Data Share | | primaryPersonDetails.name | The name of the primary person in the request. Where multiple persons are party to the transaction, the primary person is the person directly associated with the payment credential of the transaction. | Insights and Issuer Data Share | | primaryPersonDetails.phoneNumber1 | The principle phone number of the primary person in the request. Where multiple persons are party to the transaction, the primary person is the person directly associated with the payment credential of the transaction. For any phone insights to be returned the county code associated with the phone number must be provided. | Insights and Issuer Data Share | | primaryPersonDetails.phoneNumber2 | The secondary phone number of the primary person in the request. Where multiple persons are party to the transaction, the primary person is the person directly associated with the payment credential of the transaction. For any phone insights to be returned the county code associated with the phone number must be provided. | Insights and Issuer Data Share | | requestId | A unique identifier on the customer's system that can be used for troubleshooting issues with Mastercard. | Insights and Issuer Data Share | | secondaryPersonDetails.address | The postal address of the secondary person in the request. Where multiple persons are party to the transaction, the secondary person is NOT the person directly associated with the payment credential of the transaction. For any address insights to be returned the address must be resolvable to at least the city. | Insights and Issuer Data Share | | secondaryPersonDetails.emailAddress | The email address of the secondary person in the request. Where multiple persons are party to the transaction, the secondary person is NOT the person directly associated with the payment credential of the transaction. | Insights and Issuer Data Share | | secondaryPersonDetails.name | The name of the secondary person in the request. Where multiple persons are party to the transaction, the secondary person is NOT the person directly associated with the payment credential of the transaction. | Insights and Issuer Data Share | | secondaryPersonDetails.phoneNumber1 | The principle phone number of the secondary person in the request. Where multiple persons are party to the transaction, the secondary person is NOT the person directly associated with the payment credential of the transaction. For any phone insights to be returned the county code associated with the phone number must be provided. | Insights and Issuer Data Share | | transactionDetails.amount | The amount of the transaction in the currency's basic unit. If the purchase amount is USD 123.45, the element will contain the value 12345. | Insights and Issuer Data Share | | transactionDetails.currencyCode | The currency of the transaction amount, as an ISO-4217 currency code. See: ISO-4217 format: ISO-4217-3. | Insights and Issuer Data Share | | transactionDetails.currencyExponent | The Purchase currency Exponent. If the purchase amount is USD 123.45, then the exponent will contain 2. | Insights and Issuer Data Share | | transactionDetails.itemCount | Indicates the number of items in the order. | Issuer Data Share only | | transactionDetails.purchaseDate | The purchase date in YYYYMMDDHHMMSS format. | Issuer Data Share only | | transactionDetails.recurringPaymentDetails | Object containing details related to recurring payments (expiration date for payment, frequency of payment). | Issuer Data Share only | | transactionDetails.shippingIndicator | Indicates the shipping method chosen for the transaction. 01 = Ship to the cardholder billing address. 02 = Ship to another verified address on file with the merchant. 03 = Ship to an address that is different than the cardholder billing address. 04 = Ship to store / pick up at local store. 05 = Digital goods (includes online services, electronic gift cards, and so on). 06 = Travel and event tickets, not shipped. 07 = Other 08 = Pick up and Go Delivery 09 = Locker Delivery | Issuer Data Share only | | transactionDetails.topItemBrand | Indicates the brand of the highest price item in the order, | Issuer Data Share only | | transactionDetails.topItemCost | Indicates the cost of the highest price item in the order. | Issuer Data Share only | | transactionDetails.transactionType | Where the cardholder is present or actively interacting with the merchant during the transaction, the value should be set to '01' to reflect a standard cardholder-present transaction context. For transactions categorized as recurring or installment---where the cardholder is not actively engaged in a session with the merchant at the time of transaction initiation---the value must be set to '02'. This designation ensures proper classification of such transactions for downstream processing. For a transaction initiated and completed by an AI agent on behalf of a user, the value must be set to '03'. | Issuer Data Share only | | workflowId | The workflowId is used to uniquely identify a customer's chosen use case, linking it to relevant product features. 1 - Identity Insights for Transactions 2 - Identity Insights Risk Score | Insights and Issuer Data Share | ### Next Steps {#next-steps} * Refer to the [API Reference](https://developer.mastercard.com/identity-insights-solutions/documentation/api-reference/index.md) for more details on each endpoint and related parameters. * Refer to the [Code and Formats](https://developer.mastercard.com/identity-insights-solutions/documentation/code-and-formats/index.md) for more details on error codes.