Occupants

The Occupants action provides information on people which are or were registered in the requested address. The response includes the data sources and years when the person was known to be at that address.

This action can be used to retrieve information about an address occupants by providing an address MatchId and a valid x-investigation-token.

To use this action, you first need to make a Address Match request to retrieve an InvestigationToken and a MatchId for the address you are interested in.

You can then use this address MatchId and x-investigation-token to make additional requests to the Occupants action to retrieve information about the occupants of the requested address.

Service Request

To request for the person Addresses, add OCCUPANTS action to the request body entity AddressesDetailsActionsRequest:

{
    "actions": [
      {
        "action": "OCCUPANTS"
      }
    ],
    "matchId": "A_000000000"
}

	Array of objects (AddressesDetailsAction)
matchId	string (MatchId) Identifier of a matched person, business or address that can then be used to request more details of the match.
tags	Array of strings Free text tags for tracking purposes.

{

• "actions": [

  • {

    • "action": "SUMMARY"

    }

  ],
• "matchId": "P_1955F18491918",
• "tags": [

  • "CASE_NUMBER=123",
  • "IMPORTANT"

  ]

}

A valid x-investigation-token header must be included in the request.

Service Response

The Occupants action returns a JSON object containing information about the occupants of the address included in AddressesDetailsActionsResponse's occupants property.

	object (AddressSummary) Address format used across the Investigate API
	object (AddressOccupants)
	Array of objects (ErroredResponses)
tags	Array of strings Free text tags used for tracking purposes, they will be included in response.
	object (Meta) Metadata describing the response produced.

{

• "summary": {

  • "premise": "128",
  • "building": "string",
  • "subBuilding": "string",
  • "thoroughfare": "Queen Victoria Street",
  • "locality": "London",
  • "postalCode": "EC4V 4BJ",
  • "country": "GBR",
  • "id": "P_1955F18491918",
  • "isOverseas": true,
  • "sources": [

    • {

      • "name": "string",
      • "years": [

        • 2018

        ]

      }

    ],
  • "saleHistory": [

    • {

      • "saleDate": {

        • "day": 31,
        • "month": 12,
        • "year": 1981

        },
      • "salePrice": 0.1

      }

    ]

  },
• "occupants": {

  • "people": [

    • {

      • "firstName": "string",
      • "middleNames": [

        • "James"

        ],
      • "lastNames": [

        • "Smith"

        ],
      • "dateOfBirth": {

        • "day": 31,
        • "month": 12,
        • "year": 1981

        },
      • "id": "P_1955F18491918",
      • "gender": "string",
      • "sources": [

        • {

          • "name": "string",
          • "years": [

            • 2018

            ]

          }

        ],
      • "unfavourableIndicators": [

        • {

          • "indicator": "HAS_INSOLVENCY_RECORD"

          }

        ]

      }

    ]

  },
• "erroredResponses": [

  • {

    • "errors": [

      • {

        • "location": "string",
        • "code": 0,
        • "problem": "string",
        • "action": "string"

        }

      ],
    • "meta": {

      • "traceId": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
      • "timestamp": "2019-01-04T14:38:25Z",
      • "investigationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFjZUlkIjoiMTIzNDU2IiwibWF0Y2hJZHMiOltdLCJleHAiOjE1MTYyMzkwMjJ9.3SZoV56G0HT289QqP04OT5F1ITtsMqRCGkPok2-st50"

      }

    }

  ],
• "tags": [

  • "CASE_NUMBER=123",
  • "IMPORTANT"

  ],
• "meta": {

  • "traceId": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
  • "timestamp": "2019-01-04T14:38:25Z",
  • "investigationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFjZUlkIjoiMTIzNDU2IiwibWF0Y2hJZHMiOltdLCJleHAiOjE1MTYyMzkwMjJ9.3SZoV56G0HT289QqP04OT5F1ITtsMqRCGkPok2-st50"

  }

}

A standard example workflow is detailed in Details Actions page