openapi: 3.2.0
info:
  description: Identity service for borrower(s) and/or participant information delivers data for the applicant’s Social Security Number (SSN) usage, validation of SSN, identity and identity theft detection. Other names, addresses, employment, and associated dates reported including number of verifying sources.
  version: 1.0.0
  title: Identity Service Request Identity API
servers:
- url: https://api.firstam.io/v1
tags:
- name: RequestIdentity
paths:
  /identity/order/ssnsearch:
    post:
      tags:
      - RequestIdentity
      summary: Place request for Identity Service
      operationId: reqssnsearch
      description: 'Required fields: First name, last name, and full SSN. Alerts and Analytics can be added by setting the "IncludeAnalytics" flag in the request body to true.'
      parameters:
      - in: header
        name: x-app-id
        description: Application ID
        required: true
        schema:
          type: string
      - in: header
        name: x-app-key
        description: Application Key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponseExtra'
            application/xml:
              schema:
                $ref: '#/components/schemas/IdentityResponseExtra'
        '400':
          description: invalid input, object invalid
        '404':
          description: No data found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityRequestSSNSearch'
          application/xml:
            schema:
              $ref: '#/components/schemas/IdentityRequestSSNSearch'
        description: Request for Identity
  /identity/order/ssnverification:
    post:
      tags:
      - RequestIdentity
      summary: Place request for Identity Service
      operationId: reqSsnVerification
      description: 'Identity Verification: Compares consumer input data against multiple databases returning fraud messages, match results, file data, High-risk fraud alerts (HRFA) and fraud model score(s). Required fields: Last name and full SSN, or last 4 of SSN and address. Alerts and Analytics can be added by setting the "IncludeAnalytics" flag in the request body to true.'
      parameters:
      - in: header
        name: x-app-id
        description: Application ID
        required: true
        schema:
          type: string
      - in: header
        name: x-app-key
        description: Application Key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponseBase'
            application/xml:
              schema:
                $ref: '#/components/schemas/IdentityResponseBase'
        '400':
          description: invalid input, object invalid
        '404':
          description: No data found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
        description: Request for Identity
  /identity/order/ssnreport:
    post:
      tags:
      - RequestIdentity
      summary: Place request for Identity Service
      operationId: reqSsnReport
      description: 'Identity Report: Provides alias, employment, date of birth, infile- since-date, phone information, and consumer statements when available. FCRA product. There will be a soft credit inquiry posted in consumer file. Required fields: Last name and full SSN. Alerts and Analytics can be added by setting the "IncludeAnalytics" flag in the request body to true.'
      parameters:
      - in: header
        name: x-app-id
        description: Application ID
        required: true
        schema:
          type: string
      - in: header
        name: x-app-key
        description: Application Key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponseBase'
            application/xml:
              schema:
                $ref: '#/components/schemas/IdentityResponseBase'
        '400':
          description: invalid input, object invalid
        '404':
          description: No data found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
        description: Request for Identity
  /identity/order/ssnreportplus:
    post:
      tags:
      - RequestIdentity
      summary: Place request for Identity Service
      operationId: reqSsnPlus
      description: 'Identity Report Plus: An FCRA report designed for users who do not want the detail supplied by the Credit Report and are primarily interested in summary information that helps to automate decision-making process. Required fields: Last name and full SSN. Alerts and Analytics can be added by setting the "IncludeAnalytics" flag in the request body to true.'
      parameters:
      - in: header
        name: x-app-id
        description: Application ID
        required: true
        schema:
          type: string
      - in: header
        name: x-app-key
        description: Application Key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityResponseBase'
            application/xml:
              schema:
                $ref: '#/components/schemas/IdentityResponseBase'
        '400':
          description: invalid input, object invalid
        '404':
          description: No data found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/IdentityRequest'
        description: Request for Identity
components:
  schemas:
    ParsedDate:
      type: object
      properties:
        Year:
          type: integer
          example: 2017
        Month:
          type: integer
          example: 12
        Day:
          type: integer
          example: 21
    Employer:
      type: object
      properties:
        Name:
          $ref: '#/components/schemas/ConsumerName'
        DateFirstReported:
          $ref: '#/components/schemas/ParsedDate'
        DateLastReported:
          $ref: '#/components/schemas/ParsedDate'
        DateHired:
          $ref: '#/components/schemas/ParsedDate'
        DateTerminated:
          $ref: '#/components/schemas/ParsedDate'
        Address:
          $ref: '#/components/schemas/ConsumerAddress'
        Addresses:
          type: array
          items:
            $ref: '#/components/schemas/ConsumerAddress'
          xml:
            wrapped: true
        Positions:
          type: array
          items:
            $ref: '#/components/schemas/Position'
          xml:
            wrapped: true
        CompanyNames:
          type: array
          items:
            type: string
            xml:
              name: CompanyName
          xml:
            wrapped: true
        FEINs:
          type: array
          items:
            type: string
            xml:
              name: FEIN
          xml:
            wrapped: true
      xml:
        name: Employer
    IdentityRequestSSNSearch:
      type: object
      required:
      - RequestorID
      - Person
      properties:
        RequestorID:
          example: loannumber1234
          type: string
          minLength: 1
          maxLength: 100
          description: LoanNumber or TransactionID
        Person:
          $ref: '#/components/schemas/PersonSSNSearch'
        IncludeHighRiskAlerts:
          type: boolean
          example: false
        IncludeAnalytics:
          type: boolean
          example: false
          description: Option to run analytics on data set.
        AnalyticsInput:
          description: Optional dictionary for alert analytics (dependent on alert).
          $ref: '#/components/schemas/AnalyticsInputType'
    AssociatedConsumerIdentity:
      allOf:
      - $ref: '#/components/schemas/ConsumerIdentity'
      - properties:
          SharedSSNs:
            type: array
            items:
              $ref: '#/components/schemas/SSNInfo'
            xml:
              wrapped: true
          InferredAssociation:
            type: string
            example: Parent
      xml:
        name: AssociatedIdentity
    EvidenceType:
      type: object
      example:
        Key: Value
    AssociatedConsumerAddress:
      allOf:
      - $ref: '#/components/schemas/ConsumerAddress'
      - properties:
          Residents:
            type: array
            items:
              $ref: '#/components/schemas/AssociatedConsumerIdentity'
            xml:
              wrapped: true
      xml:
        name: AssociatedAddress
    License:
      type: object
      required:
      - State
      properties:
        LicenseState:
          example: CA
          type: string
          minLength: 0
          maxLength: 2
          pattern: '[A-Za-z]+'
        LicenseNumber:
          example: ABC1234
          type: string
          minLength: 0
          maxLength: 21
          pattern: '[A-Za-z0-9@#\*\+\s]+'
        ExpirationDate:
          $ref: '#/components/schemas/ParsedDate'
        IssuedDate:
          $ref: '#/components/schemas/ParsedDate'
    ConsumerName:
      allOf:
      - $ref: '#/components/schemas/Name'
      - type: object
        properties:
          Suffix:
            type: string
            example: Mr
          Prefix:
            type: string
            example: Jr
          FullName:
            type: string
            example: Mark Marsupial
          Qualifier:
            type: string
            example: alsoKnownAs
          DateFirstReported:
            $ref: '#/components/schemas/ParsedDate'
          DateLastReported:
            $ref: '#/components/schemas/ParsedDate'
      xml:
        name: Name
    NameSSNSearch:
      required:
      - First
      - Last
      properties:
        First:
          example: Mark
          type: string
          maxLength: 32
        Middle:
          type: string
          example: M
          maxLength: 32
        Last:
          type: string
          example: Marsupial
          maxLength: 65
    ConsumerAddress:
      allOf:
      - $ref: '#/components/schemas/Address'
      - type: object
        properties:
          County:
            type: string
            example: Ventura
          StreetAddress1:
            type: string
            example: 108 W 2nd St
          StreetAddress2:
            type: string
            example: Apt. 801
          FirstReportedDate:
            $ref: '#/components/schemas/ParsedDate'
          LastReportedDate:
            $ref: '#/components/schemas/ParsedDate'
          ResidenceDuration:
            type: integer
            example: 1
          ResidenceStatus:
            type: string
            example: own
          VerifyingSources:
            type: integer
            example: 2
            description: Number of verifying sources
          TypesOfSources:
            type: array
            items:
              type: string
              description: Verifying sources
              xml:
                name: Source
            xml:
              wrapped: true
            example:
            - file
            - vendor
          HighRiskIndicators:
            type: array
            items:
              $ref: '#/components/schemas/RiskIndicator'
            xml:
              wrapped: true
      xml:
        name: Address
    ConsumerStatement:
      type: object
      properties:
        Type:
          type: string
          example: regular
        Text:
          type: string
      xml:
        name: ConsumerStatement
    ConsumerIdentity:
      type: object
      properties:
        FileSummary:
          $ref: '#/components/schemas/FileSummary'
        Name:
          $ref: '#/components/schemas/ConsumerName'
        SSNInfo:
          $ref: '#/components/schemas/SSNInfo'
        Age:
          type: integer
          example: 34
        DateOfBirth:
          $ref: '#/components/schemas/ParsedDate'
        DateOfDeath:
          $ref: '#/components/schemas/ParsedDate'
        DeceasedInfo:
          $ref: '#/components/schemas/DeceasedInfo'
        DriversLicense:
          $ref: '#/components/schemas/License'
        Addresses:
          type: array
          items:
            $ref: '#/components/schemas/ConsumerAddress'
          xml:
            wrapped: true
        Employers:
          type: array
          items:
            $ref: '#/components/schemas/Employer'
          xml:
            wrapped: true
        OtherNames:
          type: array
          items:
            $ref: '#/components/schemas/ConsumerName'
          xml:
            wrapped: true
        ConsumerStatements:
          type: array
          items:
            $ref: '#/components/schemas/ConsumerStatement'
          xml:
            wrapped: true
        DateFirstReported:
          $ref: '#/components/schemas/ParsedDate'
        DateLastReported:
          $ref: '#/components/schemas/ParsedDate'
        TypesOfSources:
          type: array
          items:
            type: string
            description: Verifying sources
            xml:
              name: Source
          xml:
            wrapped: true
          example:
          - file
          - vendor
        VerifyingSources:
          type: integer
          example: 2
          description: Number of verifying sources
        HighRiskIndicators:
          type: array
          items:
            $ref: '#/components/schemas/RiskIndicator'
          xml:
            wrapped: true
    CreditDataStatus:
      type: object
      properties:
        CreditDataSuppressed:
          type: boolean
          example: 'true'
        Freeze:
          $ref: '#/components/schemas/Freeze'
        DoNotPromote:
          $ref: '#/components/schemas/DoNotPromote'
    AlertType:
      type: object
      properties:
        Code:
          example: AlertCode
          type: string
        Description:
          example: ALERT - This is an alert description.
          type: string
        Status:
          example: Fired
          type: string
        Evidence:
          description: Collection of evidence fields that caused the alert to fire.
          type: array
          items:
            $ref: '#/components/schemas/EvidenceType'
    AnalyticsInputType:
      type: object
      example:
        Key: Value
    Address:
      type: object
      properties:
        StreetNumber:
          type: string
          example: '108'
        StreetPreDirection:
          type: string
          example: W
        StreetName:
          type: string
          example: 2nd St
        StreetSuffix:
          type: string
          example: A
        StreetPostDirection:
          type: string
          example: South
        UnitDesignation:
          type: string
          example: Apt
        UnitNumber:
          type: string
          example: '801'
        StreetAddress1:
          type: string
          example: ''
        StreetAddress2:
          type: string
          example: ''
        City:
          type: string
          example: St. Louis
        State:
          type: string
          example: MO
        ZipCode:
          type: string
          example: '63101'
        ZipFour:
          type: string
          example: '1423'
        StateCityZip:
          type: string
          example: ''
        FullAddress:
          type: string
          example: ''
    Person:
      type: object
      required:
      - SSN
      properties:
        Name:
          $ref: '#/components/schemas/Name'
        Address:
          $ref: '#/components/schemas/Address'
        Age:
          type: integer
          example: 25
        SSN:
          type: string
          example: '999991234'
          pattern: ([0-9]{9})?
          description: Individual SSN
        DOB:
          $ref: '#/components/schemas/ParsedDate'
    FileSummary:
      type: object
      properties:
        FileHitIndicator:
          type: string
        FileMatchIndicator:
          type: string
        SSNMatchIndicator:
          type: string
        InFileSinceDate:
          $ref: '#/components/schemas/ParsedDate'
        CreditDataStatus:
          $ref: '#/components/schemas/CreditDataStatus'
    Freeze:
      type: object
      properties:
        FreezeIndicator:
          type: boolean
          example: true
        FreezeType:
          type: string
          example: exempt
    PersonSSNSearch:
      type: object
      required:
      - SSN
      properties:
        Name:
          $ref: '#/components/schemas/NameSSNSearch'
        Address:
          $ref: '#/components/schemas/Address'
        Age:
          type: integer
          example: 25
        SSN:
          type: string
          example: '999991234'
          pattern: ([0-9]{9})?
          description: Individual SSN
        DOB:
          $ref: '#/components/schemas/ParsedDate'
    SSNInfo:
      type: object
      xml:
        name: SSNInfo
      properties:
        SSN:
          type: string
          example: 999-99-9990
          description: Individual's SSN
        IdentificationType:
          type: string
          example: ssn
          description: Identifies the type of identification returned.
        AgeObtainedRangeStart:
          type: integer
          example: 1980
          description: Identifies the beginning year of the age range in which the SSN was issued
        AgeObtainedRangeEnd:
          type: integer
          example: 1990
          description: Identifies the endining year of the age range in which the SSN was issued
        IssuanceAlertCode:
          type: string
          example: '5503'
        FirstPossibleIssuanceYear:
          type: string
          example: 1974
          description: Year of first issuance of SSN
        LastPossibleIssuanceYear:
          type: string
          example: 1980
          description: Year of the last issuance of SSN
        IssuanceExpirationDate:
          $ref: '#/components/schemas/ParsedDate'
        IssuanceStatus:
          type: string
          example: clear
        IssuanceYearsCovered:
          type: integer
          example: 2
          description: Specifies the number of years covered by this transaction
        IssuedStartDate:
          $ref: '#/components/schemas/ParsedDate'
        IssuedEndDate:
          $ref: '#/components/schemas/ParsedDate'
        StateOfIssuance:
          type: string
          example: MO
          description: State of SSN issuance
        DateFirstReported:
          $ref: '#/components/schemas/ParsedDate'
        DateLastReported:
          $ref: '#/components/schemas/ParsedDate'
        Valid:
          type: string
    DeceasedInfo:
      type: object
      properties:
        Name:
          $ref: '#/components/schemas/ConsumerName'
        LastResidency:
          $ref: '#/components/schemas/ConsumerAddress'
        DateOfBirth:
          $ref: '#/components/schemas/ParsedDate'
        DateOfDeath:
          $ref: '#/components/schemas/ParsedDate'
        AgeAtDeath:
          type: integer
          example: 72
        DeathLocation:
          $ref: '#/components/schemas/ConsumerAddress'
    Position:
      type: object
      properties:
        Title:
          type: string
          example: Engineer
        Department:
          type: string
          example: Tech
        DateFirstReported:
          $ref: '#/components/schemas/ParsedDate'
        DateLastReported:
          $ref: '#/components/schemas/ParsedDate'
      xml:
        name: Position
    IdentityRequest:
      type: object
      required:
      - RequestorID
      - Person
      properties:
        RequestorID:
          example: loannumber1234
          type: string
          minLength: 1
          maxLength: 100
          description: LoanNumber or TransactionID
        Person:
          $ref: '#/components/schemas/Person'
        IncludeHighRiskAlerts:
          type: boolean
          example: false
        IncludeAnalytics:
          type: boolean
          example: false
          description: Option to run analytics on data set.
        AnalyticsInput:
          description: Optional dictionary for alert analytics (dependent on alert).
          $ref: '#/components/schemas/AnalyticsInputType'
    Name:
      required:
      - Last
      properties:
        First:
          example: Mark
          type: string
          maxLength: 32
        Middle:
          type: string
          example: M
          maxLength: 32
        Last:
          type: string
          example: Marsupial
          maxLength: 65
    DoNotPromote:
      type: object
      properties:
        PromotionIndicator:
          type: boolean
          example: true
        PromotionDateOfExpiration:
          $ref: '#/components/schemas/ParsedDate'
    IdentityResponseExtra:
      type: object
      properties:
        RequestorID:
          example: loannumber1234
          type: string
          minLength: 1
          maxLength: 100
          description: LoanNumber or TransactionID
        TransactionID:
          example: 82d9762b-70c3-4801-bd4b-8ffc8d358f77
          type: string
          description: TransactionID can be used to fetch data at later stage
        PrimaryIdentity:
          $ref: '#/components/schemas/ConsumerIdentity'
        AssociatedIdentities:
          type: array
          items:
            $ref: '#/components/schemas/AssociatedConsumerIdentity'
          xml:
            wrapped: true
        AssociatedAddresses:
          type: array
          items:
            $ref: '#/components/schemas/AssociatedConsumerAddress'
          xml:
            wrapped: true
        Alerts:
          type: array
          items:
            $ref: '#/components/schemas/AlertType'
    IdentityResponseBase:
      type: object
      properties:
        RequestorID:
          example: loannumber1234
          type: string
          minLength: 1
          maxLength: 100
          description: LoanNumber or TransactionID
        TransactionID:
          example: 82d9762b-70c3-4801-bd4b-8ffc8d358f77
          type: string
          description: TransactionID can be used to fetch data at later stage
        PrimaryIdentity:
          $ref: '#/components/schemas/ConsumerIdentity'
        Alerts:
          type: array
          items:
            $ref: '#/components/schemas/AlertType'
    RiskIndicator:
      type: object
      properties:
        RiskCode:
          type: string
          example: 1111
        RiskMessage:
          type: string
          example: Risk found
      xml:
        name: RiskIndicator