Skip to content
Console(opens in a new tab)

Addresses

The address object used across registrations, registered persons, registered entities and operating locations, with its USPS deliverability fields.

Every address in a KYB response uses one address object. In the response object, addresses sit on registrations, registered persons, registered entities and operating locations inside data, and in the sources of the address tasks. The addresses in data belong to the registered entities and brands that matching chose for your input.

The fields present depend on where the address appears; see Where addresses appear. This page documents the object and the values of its type and USPS deliverability fields. The addresses you send use the same five street fields. See Address fields on the request page.

A headquarters address on a New York registration has every field a registration address can carry, as in the full example under Registration addresses.

Registration address
{
"street_address1": "245 5TH AVE",
"street_address2": "FL 17",
"city": "NEW YORK",
"state": "NY",
"postal_code": "10016",
"type": "headquarters",
"deliverable": "deliverable",
"virtual": "not_virtual",
"delivery_type": "multi-tenant building",
"rdi": "commercial",
"urls": ["https://example.com/records/ny-5012345"]
}
street_address1string or null

Street number, street name and directionals in USPS standard form, for example 245 5TH AVE.

street_address2string or null

Suite, unit or floor, with USPS abbreviations, for example FL 17. null when the address has none.

citystring or null

City, for example NEW YORK.

statestring or null

Two-letter abbreviation of the U.S. state or territory, for example NY.

postal_codestring or null

Five-digit ZIP code, for example 10016.

typestring or nullRegistration addresses, and task source addresses that match one

How the address is listed on the Secretary of State filing. See Address types.

deliverablestring or null

Whether USPS can deliver to the address. See deliverable values.

virtualstring or null

Whether the address is a mailbox or virtual office. See virtual values.

delivery_typestring or null

How USPS delivers mail to the address. See delivery_type values.

rdistring or null

Whether USPS classes the address as residential or commercial. See rdi values.

urlsarray of stringRegistration and registered entity addresses only

The source URLs of the records that list this address for the registered entity, sorted. [] when none are available.

full_addressstring or nullRegistered person addresses only

The schema defines it as the whole address in one string, in place of the five street fields. Responses return the five street fields instead. See Registered person addresses.

  • The five street fields are always present. A street field with no value is null. A registered person address whose record has no parsed parts comes back with all five null.
  • type is present on registration addresses and can be null.
  • The four deliverability fields (deliverable, virtual, delivery_type, rdi) are null when USPS has not classified the address. The keys can also be missing entirely, for example on a registered person address with no USPS record. A missing key or null does not mean the address failed a check; handle both.
  • In an attribute-only request (products), registration addresses carry only the five street fields and type.

type says how the Secretary of State filing lists a registration address. A task source address keeps it when the matched address is a registration address.

Show the 7 values
Value Meaning
headquarters The principal place of business. The most useful type for confirming where a business operates.
registered The address the filing lists as the business’s registered address. It can differ from where the business operates.
registered_agent The address of the registered agent, a third party that receives legal notices for the business.
officer The personal address of an officer or director named on the filing.
mailing A mailing address for the business. Can be a P.O. box or a forwarding address.
site A physical location of the business, as listed on the filing.
null The filing gives no standard type for the address.

The four deliverability fields describe the address as USPS classifies it. They describe the address, not the business. A residential address, for example, can belong to a business that operates from a home.

Value Meaning
deliverable USPS confirms the address as a delivery point.
not_deliverable USPS cannot deliver to the address as given.
vacant A known delivery point that USPS reports as unoccupied.
no_stat A known address that is not currently receiving USPS delivery.
null USPS has not classified the address.
Value Meaning
virtual A Commercial Mail Receiving Agency (CMRA) address: a mailbox or virtual office.
not_virtual Not a CMRA address.
null USPS has not classified the address.
Show the 7 values
Value Meaning
street Door delivery at a street address.
multi-tenant building A building with several units. Expect a street_address2.
firm A delivery point for a single organization.
post office box A P.O. box at a postal facility.
general delivery Mail held at a post office for pickup, with no fixed delivery address.
rural route or highway contract route Delivery along a rural or highway contract route, not to a city-style street address.
null USPS has not classified the address.

rdi is the USPS residential delivery indicator: whether USPS classes the delivery point as residential or commercial.

Value Meaning
residential USPS classes the delivery point as residential. The business may operate from a home.
commercial USPS classes the delivery point as commercial.
null USPS has not classified the address.

This table shows which fields each kind of address can carry beyond the five street fields. Each section below ends with an illustrative example, trimmed to the object that holds the addresses.

Address type Deliverability fields urls
Registration Yes Yes Yes
Registered entity No Yes Yes
Operating location No Yes No
Registered person No Yes No
In task sources When matched When matched No

Found at data.registered_entities[].registrations[].addresses[].

The addresses on a Secretary of State registration. Each registration returns up to 10. Addresses that match an address you sent come first: exact matches, then other matches.

A headquarters address on a New York registration. It has every field a registration address can carry.

Registration addresses
{
"addresses": [
{
"street_address1": "245 5TH AVE",
"street_address2": "FL 17",
"city": "NEW YORK",
"state": "NY",
"postal_code": "10016",
"type": "headquarters",
"deliverable": "deliverable",
"virtual": "not_virtual",
"delivery_type": "multi-tenant building",
"rdi": "commercial",
"urls": ["https://example.com/records/ny-5012345"]
}
]
}

Found at data.registered_entities[].addresses[].

Mailing addresses held for the registered entity. An address that one of the entity’s registrations already lists, with any type, is not repeated here. The array is present on every identify and verify response that matches a registered entity, and is [] when there are none. It is not returned for an attribute-only request.

A mailing address held for the registered entity. It has urls but no type, and USPS has not classified it.

Registered entity addresses
{
"id": "4dccd7a5-790c-c4d1-0000-108000000000",
"addresses": [
{
"street_address1": "PO BOX 1234",
"street_address2": null,
"city": "NEW YORK",
"state": "NY",
"postal_code": "10016",
"deliverable": null,
"virtual": null,
"delivery_type": null,
"rdi": null,
"urls": ["https://example.com/records/ny-5012345"]
}
]
}

Found at data.brands[].operating_locations[].addresses[].

The addresses of a brand’s operating location. Each operating location returns up to 10. Addresses that match an address you sent come first.

The same street address on an operating location. There is no type and no urls.

Operating location addresses
{
"id": "20e8d448-f6c7-4854-9855-f8367b97b097",
"names": [
{ "name": "ENIGMA TECHNOLOGIES" }
],
"addresses": [
{
"street_address1": "245 5TH AVE",
"street_address2": "FL 17",
"city": "NEW YORK",
"state": "NY",
"postal_code": "10016",
"deliverable": "deliverable",
"virtual": "not_virtual",
"delivery_type": "multi-tenant building",
"rdi": "commercial"
}
]
}

Found at data.registered_entities[].registrations[].persons[].addresses[].

The addresses linked to a registered person. Registered persons carry addresses only when you request the person_addresses add-on attribute (attrs=person_addresses). Without it, the addresses key is absent. A registered person that is an organization, such as a registered agent service, has an empty addresses array.

A registered person address has the five street fields, any of which can be null, plus the deliverability fields when Enigma has them. When the record has no parsed parts, all five street fields are null. The schema also defines a full_address key that carries the whole address in place of the street fields. Responses do not return it, but code that reads person addresses can accept it as a precaution.

A registered person with the person_addresses add-on. The registered agent is an organization, so its addresses array is empty.

Registered person addresses
{
"persons": [
{
"name": "JANE SMITH",
"titles": ["chief executive officer"],
"addresses": [
{
"street_address1": "100 MAIN ST",
"street_address2": "APT 4",
"city": "BROOKLYN",
"state": "NY",
"postal_code": "11201",
"deliverable": "deliverable",
"virtual": "not_virtual",
"delivery_type": "multi-tenant building",
"rdi": "residential"
}
]
},
{
"name": "EXAMPLE REGISTERED AGENTS INC",
"titles": ["registered agent"],
"addresses": []
}
]
}

Each source of address_verification and sos_address_verification describes the address on record that your address matched. These are the source fields that concern addresses. See Sources for the full source object.

addressobject

The address on record that your address matched. It has the five street fields, plus type and the deliverability fields when the matched address has them. It never has urls.

match_relationship_typestring

What kind of address matched. See the values below. Absent when the match is a registered person address.

urlsarray of stringaddress_verification only

The source URLs of the matched record.

The two tasks compare against different addresses:

  • address_verification compares your addresses with registration addresses, registered entity addresses, operating location addresses and, with the person_addresses add-on, registered person addresses.
  • sos_address_verification compares them with registration addresses only.

match_relationship_type takes one of the values in match_relationship_type values.

On address_verification, Enigma compares your addresses with all of the registered entity’s addresses, including those left out of registered_entities[].addresses because a registration already lists them. One address can therefore come from both a registration and the registered entity. When a registration lists it with type mailing, or no registration lists it, the source reports mailing_address. Otherwise, including when the registration’s type is null, it reports registration_address.

An address_verification source. The matched address is the headquarters address on a registration, so it keeps its type, and match_relationship_type is registration_address.

Address task source
{
"task_name": "address_verification",
"status": "success",
"result": "address_match",
"reason": "An input address matches an address in any of Enigma's records",
"sources": [
{
"address": {
"street_address1": "245 5TH AVE",
"street_address2": "FL 17",
"city": "NEW YORK",
"state": "NY",
"postal_code": "10016",
"type": "headquarters",
"deliverable": "deliverable",
"virtual": "not_virtual",
"delivery_type": "multi-tenant building",
"rdi": "commercial"
},
"match_entity_type": "registered_entity",
"match_relationship_type": "registration_address",
"urls": ["https://example.com/records/ny-5012345"]
}
]
}