> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Perform detailed object search

> This API is used to look up the South African Fraud Prevention Service(SAFPS) database and return any listings that are found against a South African ID Number, contact number, email address or bank account.

    The following listings are returned by SAFPS:

    1. **Protective Registration (PR)** – Indicates that the subject has taken out a PR with SAFPS, and the controller will require their PR number to validate their onboards or applications. This listing identifier is formatted as `PR00088118`.

    2. **Victim** – Indicates that the subject has fallen victim to fraudulent activity. This listing identifier is formatted as `VICTIM00349654`.

    3. **SAFPS Hit (SH)** – Indicates that the subject has been flagged for conducting fraudulent activity on the SAFPS database. This listing identifier is formatted as `SH00349652`.



## OpenAPI

````yaml products/didx-verify/api-reference/v1/openapi.json post /Citizen/SAFPSDetailedObjectSearch
openapi: 3.0.1
info:
  title: SecureCitizen.Citizen.Api
  description: >-
    This is the API documentation for Secure Citizen products. Should you
    require further information please contact us on the email provided.
  contact:
    name: Api Contant Name
    email: support@securecitizen.co.za
  license:
    name: Proprietary
    url: https://www.securecitizen.co.za
  version: v1
  x-logo:
    url: >-
      https://securecitizen.co.za/wp-content/uploads/2022/11/Untitled-design-14.svg
    altText: Secure Citizen
servers:
  - url: https://citizen.uat.securecitizen.cloud
security: []
tags:
  - name: Citizen
    description: This details information we can replace to describe this endpoint
  - name: CitizenV
    description: This details information we can replace to describe this endpoint
  - name: CustomClient
    description: This details information we can replace to describe this endpoint
  - name: Partner
    description: This details information we can replace to describe this endpoint
paths:
  /Citizen/SAFPSDetailedObjectSearch:
    post:
      tags:
        - Citizen
      summary: Perform detailed object search
      description: >-
        This API is used to look up the South African Fraud Prevention
        Service(SAFPS) database and return any listings that are found against a
        South African ID Number, contact number, email address or bank account.

            The following listings are returned by SAFPS:

            1. **Protective Registration (PR)** – Indicates that the subject has taken out a PR with SAFPS, and the controller will require their PR number to validate their onboards or applications. This listing identifier is formatted as `PR00088118`.

            2. **Victim** – Indicates that the subject has fallen victim to fraudulent activity. This listing identifier is formatted as `VICTIM00349654`.

            3. **SAFPS Hit (SH)** – Indicates that the subject has been flagged for conducting fraudulent activity on the SAFPS database. This listing identifier is formatted as `SH00349652`.
      operationId: SAFPSDetailedObjectSearch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SAFPSDetailedObjectSearchRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitizenDetailedObjectSearchResponse'
        '401':
          description: Unauthenticated
        '403':
          description: Unauthorized access to this resource
        '500':
          description: Cat-as-trophy
      security:
        - oauth2:
            - sc-citizen
components:
  schemas:
    SAFPSDetailedObjectSearchRequest:
      required:
        - ConsentReceived
        - idNumber
      type: object
      properties:
        CRef:
          title: Client Reference
          type: string
          description: "Example: \"REF00001\"\r\n\r\nThis is the unique transaction reference number that can be supplied by the controller. This will be provided in response messages related to the transaction and will be required for identifying transactions for support purposes."
          format: string
          nullable: true
        ConsentReceived:
          title: Consent Received
          type: boolean
          description: "Example: true\r\n\r\nThis is an indicator to audit the fact that the controller has obtained consent from the subject to process their personal information and data as per the regulatory requirements pertaining to local and global privacy and data protection legislation."
          format: bool
        bankAccountNumber:
          title: Bank Account Number
          type: string
          description: >-
            Example: “045687123”


            This is the bank account number of the subject. This number will be
            used to perform lookups on the SAFPS database for listings. Results
            may include listings unrelated to the subject in question.
          nullable: true
        contactNumber:
          title: Contact Number
          type: string
          description: >-
            Example: “27821234567”


            This is the contact number of the subject. This number will be used
            to perform lookups on the SAFPS database for listings. Results may
            include listings unrelated to the subject in question.
          nullable: true
        emailAddress:
          title: Email Address
          type: string
          description: >-
            Example: “john.doe@email.com”


            This is the address of the subject. This email address will be used
            to perform lookups on the SAFPS database for listings. Results may
            include listings unrelated to the subject in question.
          nullable: true
        idNumber:
          title: ID Number
          minLength: 1
          type: string
          description: >-
            Example: “8511054170052”


            This is the 13-digit South African Identification Number of the
            subject. This number will be used to perform lookups on the SAFPS
            database for listings.
        requestedBy:
          title: Requested By
          type: string
          description: >-
            Example: “Goliath National Bank”


            This is the name of the controller (Company or business) whom is
            calling the API.
          nullable: true
      additionalProperties: false
    CitizenDetailedObjectSearchResponse:
      type: object
      properties:
        CRef:
          title: Client Reference
          type: string
          description: >-
            This field will return the reference provided by the client to track
            the transaction.
          format: string
          nullable: true
        Status:
          $ref: '#/components/schemas/ExternalStatusEnums'
        Message:
          title: Message
          type: string
          description: >-
            This will return a status of the transaction s well as external
            tracking information.
          format: string
          nullable: true
        results:
          title: Results
          type: array
          items:
            $ref: '#/components/schemas/SAFPSDetailedObjectSearchResponseList'
          description: >-
            Array of results returned by SAFPS. May contain multiple unrelated
            entries due to cross-referencing.
          nullable: true
        trackingNumber:
          title: Tracking Number
          type: string
          description: >-
            The unique tracking nnumber(GUID) generated and supplied for the
            transaction. This is used for audit, billing and support purposes.
          nullable: true
      additionalProperties: false
    ExternalStatusEnums:
      title: Status
      enum:
        - Success
        - Failure
        - Unknown
        - AuthFailure
        - DataDeserializationError
        - EmptyResults
        - ErrorContactSupport
        - FaceDetectionFailure
        - FaceComparisonFailure
        - NoStatusDefined
        - FaceDetectionQualityTooLow
        - FaceDetectionTooManyFaces
        - FaceDetectionNoFacesFound
        - FaceComparisonError
        - FaceComparisonNotSame
        - GoldenSourceImageNull
        - ProvidedImageNull
        - GoldenSourceNoFacesFound
        - ProvidedImageNoFacesFound
        - GoldenSourceHasTooManyFaces
        - ProvidedImageHasTooManyFaces
        - GoldenSourceQualityTooLow
        - ProvidedImageQualityTooLow
        - GoldenSourceGUIDIncorrect
        - ProvidedImageGUIDIncorrect
        - FaceAPIGeneralError
        - FaceAPIPublicUrlInputError
        - FaceBadInput
        - GoldenSourceIncorrectStringFormat
        - ProvidedImageIncorrectStringFormat
        - SAFPSNPROk
        - SAFPSHANISOk
        - SAFPSNIISOk
        - SAFPSNPRSlow
        - SAFPSHANISSlow
        - SAFPSNIISSlow
        - SAFPSFailure
        - SAFPSPossibleFailure
        - SAFPSNPRFailure
        - SAFPSHANISFailure
        - SAFPSNIISFailure
        - FaceTooClose
        - EyesClosed
        - FaceCloseToBorder
        - FaceCropped
        - FaceIsOccluded
        - FaceNotFound
        - TooManyFaces
        - FaceTooSmall
        - AbsoluteFaceTooSmall
        - RelativeFaceTooSmall
        - FaceAngleTooLarge
        - FailedToPredictLandmarks
        - Active
        - CSuccess
        - AsyncCSuccess
        - IdentificationNumberInvalid
        - IdentificationNumberAgeBelow18
        - UnableToVerifyIdentificationNumberOnDocument
        - UnableToVerifyIdentificationNumberAtGoldenSource
        - GoldenSourceUnavailable
        - MandatoryInformationMissing
        - NPRSuccess
        - HANISNotAvailable
        - InvalidIDNCheckDigitTestNotPassed
        - NPRNotAvailableOnlyPhotoIsReturned
        - IDNRIsNotCurrentlyAValidNPRIDNR
        - IDNRIsMarkedForDeletion
      type: string
      description: >-
        Status values (static strings) to be used for external connection
        management
      format: string
    SAFPSDetailedObjectSearchResponseList:
      type: object
      properties:
        subjectSurname:
          type: string
          nullable: true
        subjectName:
          type: string
          nullable: true
        subjectDateOfBirth:
          type: string
          nullable: true
        subjectGender:
          type: string
          nullable: true
        subjectTitle:
          type: string
          nullable: true
        incidents:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSDetailedSearchIncident'
          nullable: true
      additionalProperties: false
    SAFPSDetailedSearchIncident:
      type: object
      properties:
        incidentReference:
          type: string
          nullable: true
        incidentCategory:
          $ref: '#/components/schemas/SAFPSIncidentCategory'
        incidentLogDate:
          type: string
          nullable: true
        incidentDate:
          type: string
          nullable: true
        memberReference:
          type: string
          nullable: true
        member:
          type: string
          nullable: true
        reportedBy:
          type: string
          nullable: true
        savings:
          type: string
          nullable: true
        loss:
          type: string
          nullable: true
        details:
          type: string
          nullable: true
        forensicInformation:
          type: string
          nullable: true
        productAppliedFor:
          type: string
          nullable: true
        degreeOfFraud:
          type: string
          nullable: true
        idDocuments:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSIdDocument'
          nullable: true
        contactNumbers:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSContactNumber'
          nullable: true
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSAddress'
          nullable: true
        emailAddresses:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSEmailAddress'
          nullable: true
        bankAccounts:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSBankAccount'
          nullable: true
        employers:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSEmployer'
          nullable: true
        policeCases:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSPoliceCase'
          nullable: true
        devices:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSDevice'
          nullable: true
        onlineDetails:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSOnlineDetail'
          nullable: true
        cryptoDetails:
          type: array
          items:
            $ref: '#/components/schemas/SAFPSCryptoDetail'
          nullable: true
      additionalProperties: false
    SAFPSIncidentCategory:
      type: object
      properties:
        categoryNumber:
          type: string
          nullable: true
        categoryName:
          type: string
          nullable: true
        subCategoryNumber:
          type: string
          nullable: true
        subCategoryName:
          type: string
          nullable: true
        additionalDetails:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSIdDocument:
      type: object
      properties:
        type:
          type: string
          nullable: true
        number:
          type: string
          nullable: true
        issueDate:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSContactNumber:
      type: object
      properties:
        type:
          type: string
          nullable: true
        number:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSAddress:
      type: object
      properties:
        type:
          type: string
          nullable: true
        province:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        suburb:
          type: string
          nullable: true
        postalCode:
          type: string
          nullable: true
        streetName:
          type: string
          nullable: true
        streetNumber:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSEmailAddress:
      type: object
      properties:
        type:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSBankAccount:
      type: object
      properties:
        bank:
          type: string
          nullable: true
        accountType:
          type: string
          nullable: true
        accountNo:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSEmployer:
      type: object
      properties:
        employerName:
          type: string
          nullable: true
        employerTelNo:
          type: string
          nullable: true
        occupation:
          type: string
          nullable: true
        companyRegisteredName:
          type: string
          nullable: true
        companyRegisteredNumber:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSPoliceCase:
      type: object
      properties:
        policeCaseNumber:
          type: string
          nullable: true
        policeStation:
          type: string
          nullable: true
        policeReportDate:
          type: string
          nullable: true
        officer:
          type: string
          nullable: true
        caseType:
          type: string
          nullable: true
        caseStatus:
          type: string
          nullable: true
        reasonForFiling:
          type: string
          nullable: true
        reasonForExtension:
          type: string
          nullable: true
        policeContactNumber:
          type: string
          nullable: true
        policeEmail:
          type: string
          nullable: true
        policeFax:
          type: string
          nullable: true
        details:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSDevice:
      type: object
      properties:
        deviceType:
          type: string
          nullable: true
        imeiNumber:
          type: string
          nullable: true
        imisNumber:
          type: string
          nullable: true
        ipAddress:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        make:
          type: string
          nullable: true
        network:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        serialNumber:
          type: string
          nullable: true
        deviceBlacklisted:
          type: string
          nullable: true
        numberBlocked:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSOnlineDetail:
      type: object
      properties:
        platformUsername:
          type: string
          nullable: true
        reportedToPlatformURL:
          type: string
          nullable: true
        reportedToPlatformUsername:
          type: string
          nullable: true
        platformURL:
          type: string
          nullable: true
        platformTypeOther:
          type: string
          nullable: true
        websiteURL:
          type: string
          nullable: true
        reportedToPlatform:
          type: string
          nullable: true
        reportedToDomainAdmin:
          type: string
          nullable: true
        domainAdmin:
          type: string
          nullable: true
        platformAccountStatus:
          type: string
          nullable: true
        platformURLStatus:
          type: string
          nullable: true
        platformType:
          type: string
          nullable: true
        platformUsernameStatus:
          type: string
          nullable: true
        websiteURLStatus:
          type: string
          nullable: true
      additionalProperties: false
    SAFPSCryptoDetail:
      type: object
      properties:
        currencyType:
          type: string
          nullable: true
        currencyTypeOther:
          type: string
          nullable: true
        walletAddress:
          type: string
          nullable: true
        cryptoExchange:
          type: string
          nullable: true
        amount:
          type: string
          nullable: true
        exchangeWebsite:
          type: string
          nullable: true
        walletStatus:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sts.uat.securecitizen.cloud/connect/authorize
          tokenUrl: https://sts.uat.securecitizen.cloud/connect/token
          scopes:
            sc-citizen: SecureCitizen.Citizen.Api

````