# Quick Start Guide
source: https://developer.mastercard.com/identity-insights-solutions/documentation/quick-start-guide/index.md

## Overview {#overview}

Use this guide to go from account setup to your first successful Sandbox request for Identity Insights Solutions. You will create a project, generate credentials, make a test call, and prepare the same project for Production access.
Tip: If you want the fastest path to a working Sandbox request, start with the [Postman Collections page](https://developer.mastercard.com/identity-insights-solutions/documentation/developer-tools/postman-collection/index.md). It lets you test Sandbox and Production flows without writing code first.

### Before You Begin {#before-you-begin}

* Create a [Mastercard Developers](https://developer.mastercard.com/) account.
* Have a secure place to store downloaded MTLS certificate and encryption keys.
* Decide how you want to test: Postman, Insomnia, the reference application, or your own client.

### Sandbox Checklist {#sandbox-checklist}

| # |        Step        |                                         What to do                                         |
|---|--------------------|--------------------------------------------------------------------------------------------|
| 1 | Create API Project | Provision a Mastercard Developers Project with credentials for the Identity Solutions API. |
| 2 | Sandbox Request    | Send your first Sandbox Request.                                                           |
| 3 | Validation         | Use the values in the Testing Page to validate positive and negative flows.                |
| 4 | Promote            | Request Production Access.                                                                 |

## Step 1: Create API Project and Credentials {#step-1-create-api-project-and-credentials}

1. Go to [Mastercard Developers](https://developer.mastercard.com/) and create an account.

2. Activate your account by opening the link sent to your email address, and log in.

3. Open your [My Projects](https://developer.mastercard.com/dashboard) page, start a new project, and select 'Identity Insights Solutions' from the API's drop-down list. If you are creating the project on behalf of a client, update the radio button to 'Yes'.
   ![](https://static.developer.mastercard.com/content/identity-insights-solutions/uploads/api-selection.png)

4. Provide your ICA number.  

   * Your ICA number is retrieved from setting ICA in the Select Asset Option within the Portfolio Page of My Company Manager Application on Mastercard Connect.
5. Update the radio button values to reflect your requirement to be able to avail of the Issuer Data Sharing (Pilot) and Identity Insights Risk Score (IIRS) products.
   ![](https://static.developer.mastercard.com/content/identity-insights-solutions/uploads/service-details1.png)

6. Read and accept the terms and conditions appropriate to your selection.  

   * Acceptance of these terms enables eligible customers to access Identity Insights Data Sharing and Identity Insights Risk Scoring capabilities in production.  
   * A contract covering commercial terms is required to access the Identity Insights for Transactions (IIT) product in Production. Your Mastercard representative can facilitate the provision of such a contract. ![](https://static.developer.mastercard.com/content/identity-insights-solutions/uploads/legal-agreements2.png)
7. Create a key alias and keystore password for your MTLS certificate, and record them securely. Specify the values to be referenced in the Distinguished Name of your Certificate Signing Request and click 'Proceed'.
   ![](https://static.developer.mastercard.com/content/identity-insights-solutions/uploads/project-credentials.png)

8. Optional -- Generate your Client Encryption Key if you want to avail of payload encryption alongside MTLS.
   ![](https://static.developer.mastercard.com/content/identity-insights-solutions/uploads/additional-credentials1.png)

9. Download your keys and store them in a safe place.
   ![](https://static.developer.mastercard.com/content/identity-insights-solutions/uploads/create-project.png)

10. Once you receive an email informing you that the Sandbox Authentication key is approved, reach out to your [Mastercard representative](https://developer.mastercard.com/identity-insights-solutions/documentation/support/index.md) to complete your onboarding.

## Step 2: Generate Your First Sandbox Request {#step-2-generate-your-first-sandbox-request}

1. Once you have Sandbox credentials, make a simple POST request to confirm that your project is set up correctly.
2. To make a request, you need:  
   Your Sandbox MTLS certificate and corresponding private key issued for Sandbox access  
   If payload encryption is required, the Mastercard Encryption library, and your client encryption key.

Note: For a full client setup, including encryption configuration, refer to [API Basics](https://developer.mastercard.com/identity-insights-solutions/documentation/api-basics/index.md#how-to-consume-the-identity-insights-solutions-service-api).

#### Example Request (cURL) {#example-request-curl}

```bash
CERT="<PATH_TO_CLIENT_CERT.pfx>"
CERT_PASS="<CLIENT_CERT_PASSWORD>"
URL="https://sandbox.idv.mastercard.com/identity/insights"

curl -v "$URL" \
  --cert-type P12 \
  --cert "${CERT}:${CERT_PASS}" \
  --compressed \
  --header 'User-Agent: PostmanRuntime/7.39.0' \
  --header 'Accept: */*' \
  --header 'X-Encrypted-Payload: false' \
  --header 'Content-Type: application/json' \
  --data-binary @- <<'JSON' 2>&1
{
  "accountDetails": {
    "accAgeInd": "05",
    "accChange": "20260325",
    "accPwChange": "20260325",
    "txnActivityDay": "234",
    "txnActivityYear": "10"
  },
  "deviceDetails": {
    "colorDepth": 24,
    "deviceId": "04",
    "deviceLatitude": "40.7128",
    "deviceLongitude": "74.0060",
    "deviceType": "01",
    "language": "zh-TW",
    "screenHeight": "820",
    "screenWidth": "1024",
    "sdkAppID": "550e8400-e29b-41d4-a716-446655440000",
    "sdkMajorVersion": 12,
    "sdkMinorVersion": 0,
    "sdkModel": "iPhone",
    "timeZone": "600",
    "userAgent": "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 7.0; InfoPath.3; .NET CLR 3.1.40767; Trident/6.0; en-IN)",
    "ipAddress": "198.51.100.42"
  },
  "endCustomerReferenceId": "45342",
  "merchantDetails": {
    "acquirerBin": "54349600",
    "acquirerMerchantId": "ACME123456",
    "categoryCode": "0742",
    "countryCode": "840",
    "name": "Acme Inc"
  },
  "merchantTrustAssessment": {
    "additionalSignals": "R",
    "merchantRiskScore": "0",
    "refundGuarantee": true
  },
  "primaryPersonDetails": {
    "address": {
      "city": "Houston",
      "country": "840",
      "postCode": "63124",
      "state": "TX",
      "streetLine1": "912 Uclan Dr",
      "streetLine2": "Apt 34"
    },
    "emailAddress": "john@mastercard.com",
    "name": "Waidong L Syrws",
    "phoneNumber1": {
      "countryCode": "1",
      "subscriberNumber": "3143978691"
    },
    "phoneNumber2": {
      "countryCode": "1",
      "subscriberNumber": "3143978691"
    }
  },
  "requestId": "14cda309-f33b-4ff7-b8cf-3dbf87b2a232",
  "secondaryPersonDetails": {
    "address": {
      "city": "Houston",
      "country": "840",
      "postCode": "63124",
      "state": "TX",
      "streetLine1": "912 Uclan Dr",
      "streetLine2": "Apt 34"
    },
    "emailAddress": "ted@mastercard.com",
    "name": "Waidong L Syrws",
    "phoneNumber1": {
      "countryCode": "1",
      "subscriberNumber": "3143978691"
    }
  },
  "paymentMethodDetails": {
    "accountNumber": "5434960000000000000",
    "cardBin": "54349600",
    "cardExpiryDate": "2311",
    "cardLast4": "4242",
    "isCardOnFile": true
  },
  "transactionDetails": {
    "amount": "12345",
    "currencyCode": "840",
    "currencyExponent": "2",
    "itemCount": 3,
    "purchaseDate": "20250721173228",
    "recurringPaymentDetails": {
      "expiryDate": "20260325",
      "frequency": "345"
    },
    "shippingIndicator": "02",
    "topItemBrand": "Samsung",
    "topItemCost": "12345",
    "transactionType": "02"
  },
  "workflowId": 1
}
JSON
```

This example shows the required header fields explicitly, but uses placeholders for sensitive values. Replace `PATH_TO_CLIENT_CERT` with the MTLS certificate from your project.

For a step-by-step example, refer to the [Integration and Testing](https://developer.mastercard.com/identity-insights-solutions/documentation/tutorials-and-guides/api-testing-tutorial/index.md) tutorial.

#### Expected Response {#expected-response}

```bash
{
   "requestId":"14cda309-f33b-4ff7-b8cf-3dbf87b2a232",
   "responseId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
   "alerts":[
      "Limited Identity Insights are available to comply with applicable law"
   ],
   "warnings":[
    
   ],
   "deviceInsights":{
      "application":"Safari",
      "platform":"iOS",
      "type":"iPhone",
      "riskScore":{
         "current":{
            "value":0.12
         }
      }
   },
   "ipInsights":{
      "carrier":{
         "name":"Cloudflare",
         "city":"Melbourne",
         "state":"Victoria",
         "country":"Australia"
      },
      "connectionType":"cable-dsl",
      "isProxy":false,
      "lastSeen":"35",
      "proxyInsightsClass":"low",
      "riskScore":{
         "current":{
            "value":0.08
         }
      }
   },
   "primaryPersonInsights":{
      "emailAddress":{
         "firstSeen":"453",
         "lastSeen":"12",
         "isValid":true,
         "isDisposable":false,
         "matchToName":"match",
         "domainProvider":{
            "creationDate":"2000-11-29"
         },
         "riskScore":{
            "current":{
               "value":0.05
            }
         }
      },
      "phoneNumber1":{
         "carrier":{
            "name":"Telco"
         },
         "isValid":true,
         "lineType":"mobile",
         "matchToName":"match"
      },
      "phoneNumber2":{
         "carrier":{
            "name":"Telco"
         },
         "isValid":true,
         "lineType":"mobile",
         "matchToName":"match"
      },
      "address":{
         "firstSeen":"234",
         "lastSeen":"12",
         "matchToName":"match",
         "validityLevel":"valid_to_street"
      }
   },
   "secondaryPersonInsights":{
      "phoneNumber1":{
         "carrier":{
            "name":"Telco"
         },
         "isValid":true,
         "lineType":"mobile",
         "matchToName":"match"
      },
      "address":{
         "firstSeen":"120",
         "lastSeen":"10",
         "matchToName":"match",
         "validityLevel":"valid"
      }
   },
   "identityInsights":{
      "riskScore":{
         "current":{
            "value":0.16,
            "reasonCode":"RA"
         }
      },
      "ipWithDevice":{
         "differenceBetweenIpCarrierDeviceTimezones":3,
         "firstSeen":"453"
      },
      "paymentAccountNumberWithPrimaryName":{
         "firstSeen":"453",
         "velocity":6
      },
      "primaryAddressWithIp":{
         "distanceBetweenAddressIpCarrier":125
      },
      "secondaryAddressWithIp":{
         "distanceBetweenAddressIpCarrier":15
      },
      "primaryAddressWithSecondaryAddress":{
         "relationship":"seen_together"
      }
   },
   "transactionInsights":{
      "totalSpendMccRatio":0.25
   }
}
```

Refer to [Testing](https://developer.mastercard.com/identity-insights-solutions/documentation/testing/index.md) for additional scenarios.

## Step 3: Validate positive and negative flows {#step-3-validate-positive-and-negative-flows}

After the first Sandbox request succeeds, choose the integration path that matches your workflow:

* Postman: Use the Postman Collection page for setup.
* Reference Application: Use the Reference Application page.
* cURL or a custom client: Use the Testing page for test cases and additional examples.

## Step 4: Request Production Access {#step-4-request-production-access}

Once your project is working in Sandbox, request Production access for that same project. To request Production access, contact the [Mastercard representative](https://developer.mastercard.com/identity-insights-solutions/documentation/support/index.md). Note that the SLA for Production access is five business days.

### Transition your project from Sandbox to Production {#transition-your-project-from-sandbox-to-production}

1. **Open your project in Mastercard Developers** Go to your [My Projects](https://developer.mastercard.com/dashboard) page and open the Identity Insights Solutions Project you used for Sandbox testing.

2. **Provide commercial countries for your project** In the project dashboard, select the commercial countries where you intend to use the service. This information is required for Mastercard to process your Production access request.

   ![Commercial countries selection drop-down list on the project dashboard](https://static.developer.mastercard.com/content/identity-insights-for-transactions/uploads/select-countries-project.png)
3. **Request Production access for that project** In the project dashboard, select 'Request Production Access'. Your Sandbox and Production statuses are shown separately on the project page, so you can track when Production moves from `Not Requested` to an enabled `Ready` state.

4. **Generate or download your Production keys** After Production access is approved, download the Production MTLS certificate and encryption keys for the same project. Keep the Production key material separate from your Sandbox keys.

5. **Update your application configuration** Switch the base URL from Sandbox to Production:

   * Sandbox:
     * `https://sandbox.idv.mastercard.com/identity`
     * `https://sandbox.idv.mastercard.eu/identity`
     * `https://sandbox.idv.mastercard.asia/identity`
   * Production:
     * `https://idv.mastercard.com/identity`
     * `https://idv.mastercard.eu/identity`
     * `https://idv.mastercard.asia/identity`

   Update your application to use the Production consumer key, signing key, and encryption certificates.

Note: JWE payload encryption work the same way in Sandbox and Production. The main changes are the Production key set, the Production approval state, and the Production base URL.

## Step 5: Request Escalation in Event of a Missed SLA {#step-5-request-escalation-in-event-of-a-missed-sla}

Provisioning of your project for Sandbox or Production Access is expected to be completed within five business days.

If, after five business days, you are still receiving errors referencing gateway authorization or client configuration issues, please reach out to your Mastercard Representative, citing the nature of the issue being encountered and providing them with the following details:

* The name of the API and Product that the support request is related to
* The URI of the resource which is returning the error
* The Client ID from the Mastercard Developer portal associated to the project and environment that is returning the error
* The workflow ID value set in the request body
* The correlation ID detailed in the response header
* The details of the error object being returned in the response body
* The last step confirmed as successfully completed within the Quick Start Guide

On receipt of your request, your Mastercard Representative will respond within two business days.

### Next Steps {#next-steps}

Continue with the documentation that matches your next task:

* [API Reference](https://developer.mastercard.com/identity-insights-solutions/documentation/api-reference/index.md) for endpoint details
* [API Basics](https://developer.mastercard.com/identity-insights-solutions/documentation/api-basics/index.md) for authentication, encryption, and client configuration
* [Testing](https://developer.mastercard.com/identity-insights-solutions/documentation/testing/index.md) for additional request scenarios
* [Onboarding Checklist](https://developer.mastercard.com/identity-insights-solutions/documentation/tutorials-and-guides/prerequisites/index.md) for the full operational go-live process