Credit Report Request and Response

Credit Report Products

The following products use the standard Credit Report request/response structure:

CR (Credit Report)
PREQUAL (Prequalification Credit Report)
PREAPP (Pre-Approval Credit Report)
PRECLOSE (Pre-Close Credit Report)
ACCTRVW (Account Review Credit Report)
REFUPD (Reference Update Credit Report)
- Request structure follows standard Credit Report, variances exist in the response structure.
- See REFUPD response differences below

All products use identical request and response formats. The only difference is the productCode value, which determines:

How the inquiry is reported to the consumer
The permissible purpose associated with the request
Compliance requirements for your use case

Request Structure

Endpoint: POST /InnovisGateway/orest/grs_v001/request Minimum Required Fields for Credit Report Products:

{
  "customerId": "string",
  "customerTraceNumber": "string",
  "endUserCode": "string",
  "productCode": "string",
  "permissiblePurposeCode": "string",
  "softwareProviderId": "string",
  "applicants": [
    {
      "applicantId": "string",
      "names": [
        {
          "first": "string",
          "last": "string"
        }
      ],
      "ssn": "string",
      "dob": "YYYY-MM-DD",
      "phones": [
        {
          "phoneNumber": "string"
        }
      ],
      "emailAddress": "string",
      "ipAddress": "string",
      "addresses": [
        {
          "addressIdentifier": "string",
          "line1": "string",
          "city": "string",
          "state": "string",
          "zip": "string"
        }
      ]
    }
  ]
}

Field Definitions - Credit Report Request

Field Name	Type	Length	Required	Description
customerId	AN	16	Yes	Your House Number Customer ID assigned by Innovis
customerTraceNumber	AN	30	Yes	Your unique transaction identifier for tracking and troubleshooting
endUserCode	AN	16	Yes	End User Code for the customer on whose behalf you are requesting the report
productCode	AN	10	Yes	Code specifying the Innovis product being requested. ex. CR
permissiblePurposeCode	AN	2	Yes	FCRA permissible purpose code (see Appendix)
softwareProviderId	AN	4	Yes	Your software/company identifier
applicants[]	Array	-	Yes	Array of applicant objects (typically 1-2 for joint applications)
applicants[].applicantId	AN	2	Yes	Unique identifier for this applicant within your system
applicants[].names[]	Array	-	Yes	Array of name objects
applicants[].names[].first	AN	30	Yes	First name
applicants[].names[].middle	AN	30	No	Middle name or initial
applicants[].names[].last	AN	30	Yes	Last name
applicants[].names[].gen	AN	1	No	Generational suffix (Jr, Sr, III, etc.)
applicants[].ssn	N	9	Yes	Social Security Number (9 digits, no dashes)
applicants[].dob	Date	date	Yes	Date of birth in YYYY-MM-DD format
applicants[].phones[]	Array	-	Yes	Array of phone objects
applicants[].phones[].phoneNumber	N	10	Yes	10-digit phone number (no formatting)
applicants[].phones[].phoneType	AN	4	No	Phone type (HOME, MOBL, WORK)
applicants[].emailAddress	AN	80	Yes	Email address
applicants[].ipAddress	AN	45	Yes	IP address of the consumer's device
applicants[].addresses[]	Array	-	Yes	Array of address objects
applicants[].addresses[].addressIdentifier	AN	1	Yes	Address type (C, P)
applicants[].addresses[].line1	AN	40	Yes	Street address line 1
applicants[].addresses[].line2	AN	40	No	Street address line 2 (apt, unit, etc.)
applicants[].addresses[].city	AN	30	Yes	City name
applicants[].addresses[].state	AN	2	Yes	Two-letter state code (see Appendix B)
applicants[].addresses[].zip	AN	5	Yes	ZIP code (5 or 9 digits)
applicants[].addresses[].zip4	AN	4	No	ZIP+4 extension

Example Credit Report Request

{
  "customerId": "1234567890",
  "customerTraceNumber": "TXN-2026-0001-ABC123",
  "endUserCode": "9876543210",
  "productCode": "CR",
  "permissiblePurposeCode": "17",
  "softwareProviderId": "TEST",
  "applicants": [
    {
      "applicantId": "1A",
      "names": [
        {
          "first": "John",
          "middle": "Michael",
          "last": "Smith"
        }
      ],
      "ssn": "900991234",
      "dob": "1985-06-15",
      "phones": [
        {
          "phoneNumber": "5551234567",
          "phoneType": "MOBL"
        }
      ],
      "emailAddress": "[email protected]",
      "ipAddress": "192.168.1.100",
      "addresses": [
        {
          "addressIdentifier": "C",
          "line1": "123 Main Street",
          "line2": "Apt 4B",
          "city": "Springfield",
          "state": "VA",
          "zip": "22150"
        }
      ]
    }
  ]
}

Response Structure

A successful Credit Report response includes:

returnCode: Status code indicating success or error
reportReferenceNumber: Unique Innovis report identifier (STORE THIS for SECONDUSE requests)
applicants[]: Array containing consumer data
- consumerId: Unique Innovis consumer identifier (STORE THIS for SECONDUSE requests)
- consumer: Complete consumer credit report data including:
  - Personal information
  - Credit accounts (tradelines)

Critical Fields to Store

IMPORTANT: You must store these values from the Credit Report response for potential SECONDUSE requests:

reportReferenceNumber (top-level field)
applicants[].consumerId (for each applicant)
Original inquiry date/time (when you made the request)

Example Credit Report Response (Abbreviated)

{
  "returnCode": "Record",
  "reportReferenceNumber": "INNV-2026-001234567",
  "applicants": [
    {
      "consumerId": "9876543210",
      "consumer": {
        "names": [
          {
            "first": "JOHN",
            "middle": "MICHAEL",
            "last": "SMITH"
          }
        ],
        "ssn": "900991234",
        "dob": "1985-06-15",
        "addresses": [
          {
            "line1": "123 MAIN STREET",
            "line2": "APT 4B",
            "city": "SPRINGFIELD",
            "state": "VA",
            "zip": "22150"
          }
        ],
        "accounts": [
          {
            "contributor": "ABC BANK",
            "accountNumber": "****1234",
            "type": "15",
            "opened": "2020-01-15",
            "balance": "5000",
            "creditLimit": "10000",
            "statusCode": "11"
          }
        ]
      }
    }
  ]
}

Key Difference on Response Structure for REFUPD

In addition to the information returned on a standard Credit Report Response, the REFUPD product will return data about the consumer’s identification information reported on each account. These are the additional fields returned. See the Appendix for details.

Fields are located under the Account Cross Reference section:

consumerNameRefId
consumerAddressRefId
consumerSsnRefId
consumerDOBRefId
consumerPhoneNbrRefId
relatedAddressRefId

Example Credit Report Response for REFUPD (Abbreviated)

"names" : [ {
      "first" : "JOHN",
      "last" : "SMITH",
      "firstReportedDate" : "2025-04-13",
      "totalOccurrences" : 2,
      "activeOccurrences" : 2,
      "refId" : 2
        ],
        "accounts": [
          {
            "contributor": "ABC BANK",
            "accountNumber": "****1234",
            "type": "15",
            "opened": "2020-01-15",
            "balance": "5000",
            "creditLimit": "10000",
            "statusCode": "11"
         "accountCrossReference" : {
        "consumerNameRefId" : 2,
        "consumerAddressRefId" : 1,
        "consumerSsnRefId" : 1,
        "consumerDOBRefId" : 1,
        "consumerPhoneNbrRefId" : 0,
        "relatedAddressRefId" : 0
      },
     ]