- Docs
- API reference
- Endpoints and schemas
- KYB API
- Response
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.
{ "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"]}The address object
Section titled “The address object”street_address1Street number, street name and directionals in USPS standard form, for example
245 5TH AVE.street_address2Suite, unit or floor, with USPS abbreviations, for example
FL 17.nullwhen the address has none.cityCity, for example
NEW YORK.stateTwo-letter abbreviation of the U.S. state or territory, for example
NY.postal_codeFive-digit ZIP code, for example
10016.typeRegistration addresses, and task source addresses that match oneHow the address is listed on the Secretary of State filing. See Address types.
deliverableWhether USPS can deliver to the address. See
deliverablevalues.virtualWhether the address is a mailbox or virtual office. See
virtualvalues.delivery_typeHow USPS delivers mail to the address. See
delivery_typevalues.rdiWhether USPS classes the address as residential or commercial. See
rdivalues.urlsRegistration and registered entity addresses onlyThe source URLs of the records that list this address for the registered entity, sorted.
[]when none are available.full_addressRegistered person addresses onlyThe 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.
Missing and null fields
Section titled “Missing and null fields”- 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 fivenull. typeis present on registration addresses and can benull.- The four deliverability fields (
deliverable,virtual,delivery_type,rdi) arenullwhen 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 ornulldoes not mean the address failed a check; handle both. - In an attribute-only request
(
products), registration addresses carry only the five street fields andtype.
Address types
Section titled “Address types”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. |
Deliverability fields
Section titled “Deliverability fields”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.
deliverable values
Section titled “deliverable values”| 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. |
virtual values
Section titled “virtual values”| 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. |
delivery_type values
Section titled “delivery_type values”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 values
Section titled “rdi values”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. |
Where addresses appear
Section titled “Where addresses appear”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 |
Registration addresses
Section titled “Registration addresses”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.
{ "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"] } ]}Registered entity addresses
Section titled “Registered entity addresses”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.
{ "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"] } ]}Operating location addresses
Section titled “Operating location addresses”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.
{ "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" } ]}Registered person addresses
Section titled “Registered person addresses”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.
{ "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": [] } ]}Addresses in task sources
Section titled “Addresses in task sources”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.
addressThe address on record that your address matched. It has the five street fields, plus
typeand the deliverability fields when the matched address has them. It never hasurls.match_relationship_typeWhat kind of address matched. See the values below. Absent when the match is a registered person address.
urlsaddress_verificationonlyThe source URLs of the matched record.
The two tasks compare against different addresses:
address_verificationcompares your addresses with registration addresses, registered entity addresses, operating location addresses and, with theperson_addressesadd-on, registered person addresses.sos_address_verificationcompares 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.
{ "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"] } ]}Related
Section titled “Related”- Registered entities: registrations, registered persons and registered entity addresses.
- Brands: operating locations and their addresses.
- Name and address checks: how the address tasks compare your addresses with these.
- Run a KYB check: the address fields you send.
- Add-ons: the
person_addressesadd-on.