Usage Info

The Location entity stores comprehensive information about location, including location type, name, owner details and address details. This entity can be associated with businesses as BusinessLocation or used independently within a Subject Record. Use this method to create a location profile for a subject record or to get a location that gets associated with location.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
subject_record_id	string	Yes	The Subject Record to add this Location to.
location	object	No	The location parameter is defined in the table below.

Location Parameters

Parameter	Type	Required	Description
location_type	enum	No	The type of the location. Must be one of LOCATION_TYPES .
location_name	string	No	The name of a location.
owner_type	enum	No	The type of location owner. Must be one of LOCATION_OWNER_TYPES .
owner_name	string	No	The name of an owner of a location.
address	object	No	The address details for a location. The address parameter is defined in the table below.

Address Parameters

Parameter	Type	Required	Description
line1	string	No	Primary street address information (building number, street name).
line2	string	No	Secondary address information (apartment, suite, unit, etc.)
city	string	No	City or municipality name
state	string	No	Two character code for the state. Must be one of the STATES.
postal_code	string	No	ZIP or postal code for mail delivery
country	string	No	Two character code for the country where the address is located. Must be one of the COUNTRIES.

Example

{
  "subject_record_id": "sr_57WfSCnafMnxDiWMKcy3EW",
  "person": {
    "location_type": "PROPERTY",
    "location_name": "Lake House",
    "owner_type": "BUSINESS",
    "owner_name": "Mark Johnson",
    "address": {
      "line1": "123 Maple Avenue",
      "line2": "Apartment 4B",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97204",
      "country": "US"
    }
  }
}

Response

Data

Parameter	Type	Description
location	object	The location parameter defined in the tables below.

Location Parameters

Parameter	Type	Description
location_id	string	The identifier for the Location just created.

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_3XsPP17u8mU3k29x944ygx",
    "version": "2025-03-24"
  },
  "data": {
    "location": {
      "location_id": "l_4PYsekjAX8VMuAOfmW81C7"
    }
  }
}

Errors

Error Code	HTTP Code	Possible Cause
BAD_REQUEST	400	Required parameters not provided. Enum value provided does not correspond to an available type.
ENTITY_NOT_FOUND	400	The `subject_record_id` provided does not exist.
ACCOUNT_CONFIGURATION_VIOLATION	400	Account configuration rule violations are described below.
SYSTEM_RULE_VIOLATION	400	System rule violations are described below.

System Rule Violations

When a SYSTEM_RULE_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Subject Record	MAX_LOCATION_LIMIT	The maximum number of locations has been reached for this Subject Record.

ACCOUNT_CONFIGURATION_VIOLATION

When a ACCOUNT_CONFIGURATION_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Location	FEATURE_NOT_ENABLED	Location feature is not enabled for this account.