> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pr.snh-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity Match

> Compare two identity records to determine if they match

Compare candidate information against a criminal record subject to determine identity match probability. No authentication required.

## Request

<ParamField body="candidateToVerify" type="object" required>
  Candidate identity to verify (the person being checked).

  <Expandable title="Candidate Properties">
    <ParamField body="firstName" type="string">
      First name (uppercase recommended)
    </ParamField>

    <ParamField body="middleName" type="string">
      Middle name
    </ParamField>

    <ParamField body="lastName" type="string">
      Last name
    </ParamField>

    <ParamField body="dateOfBirth" type="string">
      Date of birth in `YYYY-MM-DD` format
    </ParamField>

    <ParamField body="ssn" type="string">
      Social Security Number (empty string if unavailable)
    </ParamField>

    <ParamField body="state" type="string">
      Two-letter state abbreviation
    </ParamField>

    <ParamField body="annualSalary" type="number">
      Annual salary (used for salary-based compliance rules)
    </ParamField>

    <ParamField body="aliases" type="array">
      List of alias name objects

      <Expandable title="Alias Properties">
        <ParamField body="firstName" type="string">
          Alias first name
        </ParamField>

        <ParamField body="middleName" type="string">
          Alias middle name
        </ParamField>

        <ParamField body="lastName" type="string">
          Alias last name
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="addresses" type="array">
      List of address objects

      <Expandable title="Address Properties">
        <ParamField body="streetOne" type="string">
          Primary street address
        </ParamField>

        <ParamField body="streetTwo" type="string">
          Secondary address line
        </ParamField>

        <ParamField body="city" type="string">
          City name
        </ParamField>

        <ParamField body="stateOrProvince" type="string">
          State or province code
        </ParamField>

        <ParamField body="postalCode" type="string">
          ZIP/postal code
        </ParamField>

        <ParamField body="country" type="string">
          Country code (e.g., `"US"`)
        </ParamField>

        <ParamField body="addressType" type="string">
          `"DOMESTIC"` or `"INTERNATIONAL"`
        </ParamField>

        <ParamField body="startDate" type="string">
          Address start date (`YYYY-MM-DD`)
        </ParamField>

        <ParamField body="endDate" type="string">
          Address end date (`YYYY-MM-DD`), empty for current address
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="candidateInRecord" type="object" required>
  Candidate identity found in the criminal record (the person in the record). Same structure as `candidateToVerify`.
</ParamField>

## Response

<ResponseField name="ssnScore" type="number">
  SSN match score (0–1)
</ResponseField>

<ResponseField name="ssnMatchDesc" type="string">
  Description of SSN match result
</ResponseField>

<ResponseField name="dobScore" type="number">
  Date of birth match score (0–1)
</ResponseField>

<ResponseField name="dobMatchDesc" type="string">
  Description of DOB match result
</ResponseField>

<ResponseField name="nameScore" type="number">
  Name match score (0–1)
</ResponseField>

<ResponseField name="nameMatchDesc" type="string">
  Description of name match result (e.g., `"Exact Name Match"`)
</ResponseField>

<ResponseField name="addressScore" type="number">
  Address match score (0–1)
</ResponseField>

<ResponseField name="addresseMatchDesc" type="string">
  Description of address match result
</ResponseField>

<ResponseField name="matchScore" type="number">
  Overall weighted match score (0–1)
</ResponseField>

<ResponseField name="isMatch" type="boolean">
  Whether the match threshold is met. `true` = positive match.
</ResponseField>

<ResponseField name="details" type="string">
  Detailed breakdown of match scores with weights for each component
</ResponseField>

## Code Examples

<Accordion title="Full Request Body (JSON)">
  Copy and modify this JSON payload:

  ```json theme={null}
  {
    "candidateToVerify": {
      "firstName": "EDGAR",
      "middleName": "",
      "lastName": "LINARES",
      "dateOfBirth": "1997-05-05",
      "ssn": "",
      "state": "TX",
      "annualSalary": 55000.0,
      "aliases": [
        { "firstName": "ED", "middleName": "", "lastName": "LINARES" }
      ],
      "addresses": [
        {
          "streetOne": "200 AVANT ST APT C1 DEL RIO, TX 78840",
          "streetTwo": "",
          "city": "DEL RIO",
          "stateOrProvince": "TX",
          "postalCode": "78840",
          "country": "US",
          "addressType": "DOMESTIC",
          "startDate": "2020-01-01",
          "endDate": ""
        }
      ]
    },
    "candidateInRecord": {
      "firstName": "EDGAR",
      "middleName": "",
      "lastName": "LINARES",
      "dateOfBirth": "1997-05-05",
      "ssn": "",
      "state": "TX",
      "annualSalary": null,
      "aliases": [],
      "addresses": [
        {
          "streetOne": "200 AVANT ST APT C1 DEL RIO, TX 78840",
          "streetTwo": "",
          "city": "",
          "stateOrProvince": "",
          "postalCode": "",
          "country": "US",
          "addressType": "DOMESTIC",
          "startDate": "",
          "endDate": ""
        }
      ]
    }
  }
  ```
</Accordion>

<Accordion title="Example Request (cURL / Python / JavaScript)">
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://cra.pr.snh-ai.com/complianceEngine/identity-match" \
      -H "Content-Type: application/json" \
      -d '{
        "candidateToVerify": {
          "firstName": "EDGAR",
          "middleName": "",
          "lastName": "LINARES",
          "dateOfBirth": "1997-05-05",
          "ssn": "",
          "state": "TX",
          "annualSalary": 55000.0,
          "aliases": [
            {
              "firstName": "ED",
              "middleName": "",
              "lastName": "LINARES"
            }
          ],
          "addresses": [
            {
              "streetOne": "200 AVANT ST APT C1 DEL RIO, TX 78840",
              "streetTwo": "",
              "city": "DEL RIO",
              "stateOrProvince": "TX",
              "postalCode": "78840",
              "country": "US",
              "addressType": "DOMESTIC",
              "startDate": "2020-01-01",
              "endDate": ""
            }
          ]
        },
        "candidateInRecord": {
          "firstName": "EDGAR",
          "middleName": "",
          "lastName": "LINARES",
          "dateOfBirth": "1997-05-05",
          "ssn": "",
          "state": "TX",
          "annualSalary": null,
          "aliases": [],
          "addresses": [
            {
              "streetOne": "200 AVANT ST APT C1 DEL RIO, TX 78840",
              "streetTwo": "",
              "city": "",
              "stateOrProvince": "",
              "postalCode": "",
              "country": "US",
              "addressType": "DOMESTIC",
              "startDate": "",
              "endDate": ""
            }
          ]
        }
      }'
    ```

    ```python Python theme={null}
    import requests

    response = requests.post(
        "https://cra.pr.snh-ai.com/complianceEngine/identity-match",
        headers={"Content-Type": "application/json"},
        json={
            "candidateToVerify": {
                "firstName": "EDGAR",
                "lastName": "LINARES",
                "dateOfBirth": "1997-05-05",
                "ssn": "",
                "state": "TX",
                "aliases": [{"firstName": "ED", "lastName": "LINARES"}],
                "addresses": [{
                    "streetOne": "200 AVANT ST APT C1 DEL RIO, TX 78840",
                    "country": "US",
                    "addressType": "DOMESTIC"
                }]
            },
            "candidateInRecord": {
                "firstName": "EDGAR",
                "lastName": "LINARES",
                "dateOfBirth": "1997-05-05",
                "ssn": "",
                "state": "TX",
                "aliases": [],
                "addresses": [{
                    "streetOne": "200 AVANT ST APT C1 DEL RIO, TX 78840",
                    "country": "US",
                    "addressType": "DOMESTIC"
                }]
            }
        }
    )
    print(response.json())
    ```

    ```javascript JavaScript theme={null}
    const response = await fetch("https://cra.pr.snh-ai.com/complianceEngine/identity-match", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        candidateToVerify: {
          firstName: "EDGAR",
          lastName: "LINARES",
          dateOfBirth: "1997-05-05",
          ssn: "",
          state: "TX",
          aliases: [{ firstName: "ED", lastName: "LINARES" }],
          addresses: [{
            streetOne: "200 AVANT ST APT C1 DEL RIO, TX 78840",
            country: "US",
            addressType: "DOMESTIC"
          }]
        },
        candidateInRecord: {
          firstName: "EDGAR",
          lastName: "LINARES",
          dateOfBirth: "1997-05-05",
          ssn: "",
          state: "TX",
          aliases: [],
          addresses: [{
            streetOne: "200 AVANT ST APT C1 DEL RIO, TX 78840",
            country: "US",
            addressType: "DOMESTIC"
          }]
        }
      })
    });
    const data = await response.json();
    console.log(data);
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Example Response — Match Found">
  ```json theme={null}
  {
    "ssnScore": 0,
    "ssnMatchDesc": "Invalid/Empty SSN(s)",
    "dobScore": 1.0,
    "dobMatchDesc": "Exact DOB Match",
    "nameScore": 1.0,
    "nameMatchDesc": "Exact Name Match",
    "addressScore": 1.0,
    "addresseMatchDesc": "Exact Address Match",
    "matchScore": 0.90,
    "isMatch": true,
    "details": "Name/Alias Score: 100 % (Weight: 45 %)\nDOB Score: 100 % (Weight: 40 %)\nSSN Score: 0 % (Weight: 10 %)\nAddress Score: 100 % (Weight: 5 %)\nOverall Score: 90.0 % (Qualify: 85 %)"
  }
  ```
</Accordion>

<Accordion title="Error Responses (400)">
  **Invalid Request Format:**

  ```json theme={null}
  {
    "error": "Invalid request format",
    "message": "Request body must be a JSON object with 'candidateToVerify' and 'candidateInRecord' properties.",
    "code": "INVALID_REQUEST_FORMAT"
  }
  ```

  **Validation Error:**

  ```json theme={null}
  {
    "error": "Validation failed",
    "message": "One or more validation errors occurred",
    "code": "VALIDATION_ERROR",
    "errors": {
      "candidateToVerify.dateOfBirth": [
        "The dateOfBirth field must be in YYYY-MM-DD format (e.g., 1997-08-30). Received: 1997-50-30"
      ]
    }
  }
  ```
</Accordion>

***

## Match Scoring

The identity match algorithm uses a weighted scoring system:

| Component         | Weight | Method                                 |
| ----------------- | ------ | -------------------------------------- |
| **Name/Alias**    | 45%    | Fuzzy matching across name and aliases |
| **Date of Birth** | 40%    | Date comparison                        |
| **SSN**           | 10%    | Exact match when available             |
| **Address**       | 5%     | Standardized address comparison        |

<Note>
  Maximum score is **1.00** when SSN, DOB, name, and address all match exactly: (45% x 1.0) + (40% x 1.0) + (10% x 1.0) + (5% x 1.0) = 1.00. Records with SSN + DOB + exact name typically score 0.95+. Without SSN (most common), the practical maximum is **0.90** (name + DOB + address).
</Note>

## Related

* [Evaluate](/api-reference/endpoints/evaluate) — Main criminal record evaluation endpoint
* [Glossary](/glossary) — Decision values and compliance terminology