> ## Documentation Index > Fetch the complete documentation index at: https://docs.herondata.io/llms.txt > Use this file to discover all available pages before exploring further. # Update the company and owner details of an end user > Send `heron_id`, the `hen_` ID that `GET` returns on every entity, to update that entity. Leave it out to add a new owner, address or phone, and the response returns its `heron_id`. A deal has one business, so once it has one, `business` must send its `heron_id`. Owners sent without `business` link to it. Send only the fields that change. A field you leave out keeps its current value. `null` clears the value this account stated, and a list replaces this account's earlier list, so `[]` clears it. Another source's value still shows. ## OpenAPI ````yaml https://app.herondata.io/swagger patch /api/end_users/{end_user_heron_id}/details openapi: 3.0.0 info: contact: email: support@herondata.io name: Support title: Heron Data API version: '2021-07-19' servers: - description: Production url: https://app.herondata.io security: - ApiKeyAuth: - key_XXX externalDocs: description: Read Tutorial url: https://docs.herondata.io/ paths: /api/end_users/{end_user_heron_id}/details: patch: tags: - EndUsers summary: Update the company and owner details of an end user description: > Send `heron_id`, the `hen_` ID that `GET` returns on every entity, to update that entity. Leave it out to add a new owner, address or phone, and the response returns its `heron_id`. A deal has one business, so once it has one, `business` must send its `heron_id`. Owners sent without `business` link to it. Send only the fields that change. A field you leave out keeps its current value. `null` clears the value this account stated, and a list replaces this account's earlier list, so `[]` clears it. Another source's value still shows. parameters: - description: The Heron ID of the end user in: path name: end_user_heron_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DetailsWriteSchema' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/EndUserDetailsResponseSchema' description: OK '400': description: The details stated do not fit this submission '403': description: Editing company details is not enabled for this account '404': description: End user not found '422': description: A body this schema cannot read, such as a key it does not name security: - ApiKeyAuth: [] components: schemas: DetailsWriteSchema: additionalProperties: false description: >- The company and owner details to state for this deal. The response is the same body `GET` returns, so a caller can read back the result of the write. properties: business: allOf: - $ref: '#/components/schemas/DetailsBusinessWrite' nullable: true owners: items: $ref: '#/components/schemas/DetailsOwnerWrite' type: array type: object EndUserDetailsResponseSchema: description: >- Everything the deal's sources found about who the applicant is, with one value for each field and the source it was taken from. When the sources give different values, the value from the highest-ranked source is shown, and the other values are not in this response. Dates use YYYY-MM-DD and amounts are decimal strings. properties: affiliates: description: >- Everyone linked to the applicant or to an owner who is neither of them, in name order. Never the company being underwritten and never a declared owner, which are `business` and `owners`, and never someone only a record names, who is in that record's `relationships`. items: $ref: '#/components/schemas/ResolvedAffiliate' type: array arrests: description: Most recent first. items: $ref: '#/components/schemas/ResolvedArrest' type: array bankruptcies: description: Newest filing first. items: $ref: '#/components/schemas/ResolvedBankruptcy' type: array business: allOf: - $ref: '#/components/schemas/ResolvedBusiness' description: >- The company being underwritten. Null when no source identified one, which happens on a deal with no application form and no company search. nullable: true corporate_filings: description: Newest incorporation first. items: $ref: '#/components/schemas/ResolvedCorporateFiling' type: array criminal_cases: description: Newest filing first. items: $ref: '#/components/schemas/ResolvedCriminalCase' type: array custom_entities: additionalProperties: {} description: >- The fields defined outside the standardised ones, keyed by entity name. A single entity is one object and a list entity is a list of row objects. Each object carries the attribute names as keys with one value each, and `_sources` names the source type each value was taken from. An attribute no source stated is null and absent from `_sources`. Empty when no custom entity is defined. type: object lawsuits: description: Newest filing first. items: $ref: '#/components/schemas/ResolvedLawsuit' type: array liens: description: Newest filing first. items: $ref: '#/components/schemas/ResolvedLienJudgment' type: array owners: description: >- The owners an application form declared, best attested first, so a reader with room for two sees the two that matter. Empty when no form declared one. items: $ref: '#/components/schemas/ResolvedOwner' type: array tax_id_verifications: description: >- Every identifier an authority was asked to check, with the name it was checked against and the answer, in identifier order. items: $ref: '#/components/schemas/ResolvedTaxIdVerification' type: array required: - affiliates - arrests - bankruptcies - business - corporate_filings - criminal_cases - custom_entities - lawsuits - liens - owners - tax_id_verifications type: object DetailsBusinessWrite: additionalProperties: false description: >- The company being underwritten. Only the keys stated are written. A key left out keeps its earlier value. properties: aliases: items: $ref: '#/components/schemas/CompanyAliasWrite' nullable: true type: array billing_address: allOf: - $ref: '#/components/schemas/AddressWrite' nullable: true business_address: allOf: - $ref: '#/components/schemas/AddressWrite' nullable: true business_phone: allOf: - $ref: '#/components/schemas/PhoneWrite' nullable: true emails: items: $ref: '#/components/schemas/EmailWrite' nullable: true type: array heron_id: description: >- The entity this states something about, as `GET /end_users/{id}/details` returned it. Omit it to declare something the deal does not hold yet, and the response names the entity it landed on. nullable: true type: string identifiers: items: $ref: '#/components/schemas/CompanyIdWrite' nullable: true type: array name: allOf: - $ref: '#/components/schemas/LegalNameWrite' nullable: true started_on: allOf: - $ref: '#/components/schemas/PartialDateWrite' nullable: true state_of_incorporation: description: >- A US state or territory name or two-letter code. Null or blank withdraws the manual value. nullable: true type: string type_of_entity: enum: - llc - inc - corp - lp - llp - partnership - sole_proprietor - ltd - plc - co - pc - pllc - unknown - null nullable: true websites: items: $ref: '#/components/schemas/WebsiteWrite' nullable: true type: array type: object DetailsOwnerWrite: additionalProperties: false description: >- One owner of the company. Only the keys stated are written. A key left out keeps its earlier value. properties: aliases: items: $ref: '#/components/schemas/PersonAliasWrite' nullable: true type: array credit_scores: description: >- Credit scores to state for this owner. An item with `heron_id` edits that score and one without adds a score. Scores left out are unchanged; null or omitted changes none. items: $ref: '#/components/schemas/CreditScoreWrite' nullable: true type: array date_of_birth: allOf: - $ref: '#/components/schemas/PartialDateWrite' nullable: true emails: items: $ref: '#/components/schemas/EmailWrite' nullable: true type: array heron_id: description: >- The entity this states something about, as `GET /end_users/{id}/details` returned it. Omit it to declare something the deal does not hold yet, and the response names the entity it landed on. nullable: true type: string home_address: allOf: - $ref: '#/components/schemas/AddressWrite' nullable: true home_phone: allOf: - $ref: '#/components/schemas/PhoneWrite' nullable: true mobile_phone: allOf: - $ref: '#/components/schemas/PhoneWrite' nullable: true name: allOf: - $ref: '#/components/schemas/PersonNameWrite' nullable: true national_ids: items: $ref: '#/components/schemas/NationalIdWrite' nullable: true type: array ownership_percentage: description: The share stated, out of 100. maximum: 100 minimum: 0 nullable: true type: number type: object ResolvedAffiliate: description: >- Someone linked to the company being underwritten or to one of its owners, who is neither of those: an owner no form declared, a company an owner works at, a named contact. Someone a record names and nothing else is not here; the record states them inside the link that reaches them, and an entry here would state the same party a second time. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object billing_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a company is billed. nullable: true business_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a company is. nullable: true business_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: A company's line. nullable: true country_of_residence: description: Country of residence. No source read today states one, so null. nullable: true type: string date_of_birth: allOf: - $ref: '#/components/schemas/PartialDate' description: >- Read as parts, because a source can state a year and a month with no day. Null unless a source stated one. Only the application does today, so in practice only a person the deal applied with carries one. nullable: true deceased_on: description: >- Date of death where a source states one; null under the same limit as above. format: date nullable: true type: string emails: description: Every email address every source stated. items: $ref: '#/components/schemas/SourcedEmail' type: array heron_id: description: >- The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity. nullable: true type: string home_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a person lives. nullable: true home_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: A person's home line. nullable: true identifiers: description: >- Every identifier every source stated, each with the authority's answer on it. items: $ref: '#/components/schemas/SourcedCompanyId' type: array is_deceased: description: >- Whether a source records this person as deceased. Null until the parser surfaces the subject's own profile; it reads the indicator for an associate only. nullable: true type: boolean is_dissolved: description: >- True when no linked filing that states a standing is still active. When no linked filing states one, the highest-precedence source's company-level standing answers instead. A company can be revoked in one state and active in the state that formed it, so one dissolved filing does not dissolve the company. Null when no source states a standing, which is not good standing. nullable: true type: boolean mailing_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a company's post goes. nullable: true mobile_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: A person's mobile line. nullable: true name: description: The one spelling to show for this party. nullable: true type: string national_ids: description: Every identifier every source stated. items: $ref: '#/components/schemas/SourcedNationalId' type: array nationalities: description: Every nationality a source stated. items: $ref: '#/components/schemas/SourcedNationality' type: array registered_office: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: A company's address on the state register. nullable: true relationships: description: >- How this party stands to the company being underwritten, or to one of its owners. items: $ref: '#/components/schemas/ResolvedRelationship' type: array started_on: allOf: - $ref: '#/components/schemas/PartialDate' description: >- When the company started trading, read as parts because a source can state a year alone. Not the date it was formed: a business often trades for years before the entity that applies is registered, and the formation date is `formed_on` on its corporate filing. nullable: true state_of_incorporation: description: >- The state or territory where the company was incorporated. Recognised US state names and codes use one uppercase state name; null when no source states one. nullable: true type: string subject_type: description: >- Which of the submission's own subjects this row is, so you can tell them apart from everything the searches turned up around them. Set differently for the two, because only one of them is certain. `business`: the company being underwritten. A deal has one, and every source is searched for it, so a company row carries this even when no application form named one and however differently a registry or a directory spells the name. `owner`: a person the submission declared as an owner, which only an application form states. A person a report returned is null even when that report searched under an owner, because a relative or a namesake found by that search is a finding and not a declared owner. Several rows can hold `owner`, since a submission names any number of them, and the order the owners are returned in answers which one leads. Null: every other row. For people that is the usual case, covering relatives, court parties and officers of other companies. For a company it means one reached through a finding, such as another company an owner holds an office in. enum: - owner - business - null nullable: true type_of_entity: description: >- The company's legal form: llc, inc, corp, lp, llp, partnership, sole_proprietor, ltd, plc or unknown. The deal's own word for it leads, as it does for the names, so an application form stating one outranks a registry; `reported_by` names what every source said, and each corporate filing states its own `legal_form`. `unknown` when no source states one. enum: - llc - inc - corp - lp - llp - partnership - sole_proprietor - ltd - plc - co - pc - pllc - unknown websites: description: Every website every source stated. items: $ref: '#/components/schemas/SourcedWebsite' type: array type: object ResolvedArrest: description: >- One arrest, with one value for each field, most recent first. Never a conviction. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object actual_release_date: description: Date the person was released from custody. format: date nullable: true type: string additional_fields: description: >- Fields the source reported that have no named home on the record, kept verbatim so nothing it stated is dropped. Rows naming a person, a place or a phone line are dropped rather than carried, because each of those is a thing the arrest links to. items: $ref: '#/components/schemas/LabelledValue' type: array arrest_agency_raw: description: The agency that made the arrest, as the source named it. nullable: true type: string arrest_date: description: Date of the arrest itself. format: date nullable: true type: string arrest_location: description: Where the source places the arrest. nullable: true type: string arrest_time: description: Time of the arrest, in the source's own words. nullable: true type: string bail_amount: description: Bail set, as a decimal string. nullable: true type: number booking_date: description: Date the arrest was booked into custody. format: date nullable: true type: string booking_location: description: Where the booking took place. nullable: true type: string booking_number: description: >- The number the jail booked the arrest under, as the source wrote it. May be absent even when the source states a case number. nullable: true type: string booking_time: description: Time of booking, in the source's own words. nullable: true type: string case_number_raw: description: >- A case number the source states against the arrest, where available. This is the source's reference, not a link to a criminal-case record. An arrest is not a conviction. nullable: true type: string categories: description: >- What kind of offence Heron classifies this as; empty when it maps to none. items: enum: - violent - murder_homicide - domestic_violence - burglary - fraud - sex_offense - child_related - fiduciary - animal_cruelty - drug - dui - other type: array class_of_crime_raw: description: How serious the source called it, in its own words. nullable: true type: string county_of_crime: description: County the offence is recorded in. nullable: true type: string court_raw: description: >- The court the source names against the arrest, where it names one; often absent. nullable: true type: string crime_date: description: Date of the offence, where it differs from the arrest. format: date nullable: true type: string disposition_raw: description: How the arrest ended, in the source's own words. nullable: true type: string grade: description: >- How serious Heron grades it: `felony`, `misdemeanor`, `infraction` or `unknown`. Null when no source stated one, which is not the same as `unknown`. enum: - felony - misdemeanor - petty_misdemeanor - infraction - unknown - null nullable: true is_dismissed: description: >- True when Heron reads the disposition as a dismissal; null when none was stated. nullable: true type: boolean mugshot_record_id: description: >- Identifies the mugshot the source holds for this arrest. The image itself is served by its own authenticated route; only the identifier travels here. nullable: true type: string number_of_counts: description: How many counts the source states. nullable: true type: integer offense_raw: description: The offence, in the source's own words. nullable: true type: string record_state: description: The state the arrest was recorded in. nullable: true type: string relationships: description: Everyone and everything this record names, and in what capacity. items: $ref: '#/components/schemas/ResolvedRelationship' type: array reported_by: description: >- Every source that reported this record, so a reader can tell one two sources found from one only a single search returned. items: type: string type: array risk: description: >- Risk tier of this record: none, low, medium or high; null when no source stated one. enum: - none - low - medium - high - null nullable: true source_document_guid: description: The source's identifier for the document behind this record. nullable: true type: string source_name: description: >- Which body's records reported the arrest, such as HENNEPIN COUNTY JAIL. nullable: true type: string statute: description: The statute the source says was violated. nullable: true type: string type: object ResolvedBankruptcy: description: One bankruptcy, with one value for each field, newest filing first. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object additional_fields: description: >- Fields the source reported that have no named home on the record, kept verbatim so nothing it stated is dropped. Identity and demographic rows are dropped rather than carried. items: $ref: '#/components/schemas/LabelledValue' type: array case_details: description: Free text the filing carries about the case. nullable: true type: string case_link: description: Link to the case on the court's own system. nullable: true type: string case_title: description: The case name as the court records it. nullable: true type: string category: description: >- How the source files the case among its own case types; null when it states none. nullable: true type: string chapter: description: Bankruptcy chapter number; null when unavailable. nullable: true type: integer chapter_kind: description: >- Bankruptcy chapter classification: chapter_7, chapter_11, chapter_12, chapter_13, other, or unknown. enum: - chapter_7 - chapter_11 - chapter_12 - chapter_13 - other - unknown court: description: The court holding the case. nullable: true type: string court_location: description: The courthouse named on the case. nullable: true type: string court_state: description: The state the court sits in. nullable: true type: string date_closed: description: Date the case closed; null while it is open. format: date nullable: true type: string date_discharged: description: Date the debts were discharged; null when not. format: date nullable: true type: string docket_entries: description: >- The case docket, oldest entry first. Empty unless a source read the docket, for the same reason as the creditors' meeting. items: $ref: '#/components/schemas/DocketEntry' type: array document_id: description: Court docket reference; null when unavailable. nullable: true type: string filed_date: description: Case filing date; null when unavailable. format: date nullable: true type: string filing_office: description: >- The filing office from the docket number, which is the district's own division code. nullable: true type: string is_open: description: True when status_kind is neither discharged nor dismissed. type: boolean judge: description: The judge assigned to the case. nullable: true type: string meeting_341: allOf: - $ref: '#/components/schemas/Meeting341' description: >- The creditors' meeting. Null unless a source read the case docket, because a case search returns the case and not its docket. nullable: true nature_of_suit: description: The nature of suit the filing states. nullable: true type: string relationships: description: Everyone and everything this record names, and in what capacity. items: $ref: '#/components/schemas/ResolvedRelationship' type: array reported_by: description: >- Every source that reported this record, so a reader can tell one two sources found from one only a single search returned. items: type: string type: array source_document_guid: description: >- The source's own identifier for the document behind this record, so a reader can quote it back to the source. Null when the source states none. nullable: true type: string source_name: description: >- The source's own name for the collection this record came from, kept verbatim. nullable: true type: string status: description: Bankruptcy status value matching status_kind. nullable: true type: string status_kind: description: >- Bankruptcy status classification: filed, discharged, dismissed, or unknown. Discharged and dismissed are closed; filed and unknown are open. enum: - filed - discharged - dismissed - unknown total_assets: description: >- Total scheduled assets as a decimal string; null when the filing does not record them. nullable: true type: number total_liabilities: description: >- Total scheduled liabilities as a decimal string; null when the filing does not record them. nullable: true type: number type: object ResolvedBusiness: description: >- One business the deal's sources named. Where the sources spelled the name differently, this is the spelling to show: the deal's own leads when it stated one. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object aliases: description: >- Every other name a source stated for this company, in precedence order: a trading name, a former name, a registry's spelling. `name` is the one to show. Empty when they agreed. items: $ref: '#/components/schemas/CompanyName' type: array billing_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: >- Where the company is billed, stated apart from where it is. Null when none was reported. nullable: true business_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: The company's premises. Null when no source placed it anywhere. nullable: true business_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: The company's line; null when no source reported one. nullable: true emails: description: Every email address every source stated. items: $ref: '#/components/schemas/SourcedEmail' type: array heron_id: description: >- The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity. nullable: true type: string identifiers: description: >- Every identifier every source stated, each with the authority's answer on it. items: $ref: '#/components/schemas/SourcedCompanyId' type: array is_dissolved: description: >- True when no linked filing that states a standing is still active. When no linked filing states one, the highest-precedence source's company-level standing answers instead. A company can be revoked in one state and active in the state that formed it, so one dissolved filing does not dissolve the company. Null when no source states a standing, which is not good standing. nullable: true type: boolean mailing_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: >- Where the post goes, where that is not the premises. Null when no source stated one. nullable: true name: allOf: - $ref: '#/components/schemas/CompanyName' description: The one name to show, with its type. Null when no source stated one. nullable: true other_addresses: description: >- Every other place a source put this party, which the named address fields chose one of. No span is stated, so this is where a subject has been read, not when. Empty when every place a source stated is already named above. items: $ref: '#/components/schemas/ResolvedAddress' type: array registered_office: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: >- The address on the state register, which a company filed in one state while it trades in another holds apart from its premises. Null when no registry stated one. nullable: true started_on: allOf: - $ref: '#/components/schemas/PartialDate' description: >- When the company started trading, read as parts because a source can state a year alone. Not the date it was formed: a business often trades for years before the entity that applies is registered, and the formation date is `formed_on` on its corporate filing. nullable: true state_of_incorporation: description: >- The state or territory where the company was incorporated. Recognised US state names and codes use one uppercase state name; null when no source states one. nullable: true type: string subject_type: description: >- Which of the submission's own subjects this row is, so you can tell them apart from everything the searches turned up around them. Set differently for the two, because only one of them is certain. `business`: the company being underwritten. A deal has one, and every source is searched for it, so a company row carries this even when no application form named one and however differently a registry or a directory spells the name. `owner`: a person the submission declared as an owner, which only an application form states. A person a report returned is null even when that report searched under an owner, because a relative or a namesake found by that search is a finding and not a declared owner. Several rows can hold `owner`, since a submission names any number of them, and the order the owners are returned in answers which one leads. Null: every other row. For people that is the usual case, covering relatives, court parties and officers of other companies. For a company it means one reached through a finding, such as another company an owner holds an office in. enum: - owner - business - null nullable: true type_of_entity: description: >- The company's legal form: llc, inc, corp, lp, llp, partnership, sole_proprietor, ltd, plc or unknown. The deal's own word for it leads, as it does for the names, so an application form stating one outranks a registry; `reported_by` names what every source said, and each corporate filing states its own `legal_form`. `unknown` when no source states one. enum: - llc - inc - corp - lp - llp - partnership - sole_proprietor - ltd - plc - co - pc - pllc - unknown websites: description: Every website every source stated. items: $ref: '#/components/schemas/SourcedWebsite' type: array type: object ResolvedCorporateFiling: description: One registration of a company with one registry, newest formation first. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object annual_report_file_date: description: Date of the most recent annual report. format: date nullable: true type: string dissolved_on: description: >- Date the company dissolved. Only a dissolved filing has one, because a registry states the date its status last changed rather than a date of dissolution. format: date nullable: true type: string filing_date: description: Date this filing was made. format: date nullable: true type: string filing_office_name: description: The registry office named on the filing. nullable: true type: string formed_on: description: Date the company was formed. format: date nullable: true type: string jurisdiction: description: >- The registry that holds the filing, as a country and a subdivision, such as US-CA. Null when the source names no state, and null when it names one that is not a US state. nullable: true type: string legal_form: description: >- The company's legal form: llc, inc, corp, lp, llp, partnership, sole_proprietor, ltd, plc or unknown. Registries word the same form several ways, so this classifies legal_form_raw. enum: - llc - inc - corp - lp - llp - partnership - sole_proprietor - ltd - plc - co - pc - pllc - unknown number: description: >- The registry's identifier for this filing, as the registry writes it. Null when the registry states none, and a filing without a number is never joined to another filing. nullable: true type: string relationships: description: Everyone and everything this record names, and in what capacity. items: $ref: '#/components/schemas/ResolvedRelationship' type: array reported_by: description: >- Every source that reported this record, so a reader can tell one two sources found from one only a single search returned. items: type: string type: array state_of_incorporation: description: >- Where the company was formed, which differs from the jurisdiction of this filing when a company registers to trade outside its home state. nullable: true type: string status: description: >- The standing of this filing: active, inactive, dissolved, revoked or unknown. `revoked` also covers forfeited, suspended and administratively dissolved. A company can be revoked in one state and active in the state that formed it. enum: - active - inactive - dissolved - revoked - unknown status_date: description: Date the registry recorded the current status. format: date nullable: true type: string status_effective_date: description: Date the current status took effect. format: date nullable: true type: string type: object ResolvedCriminalCase: description: One criminal case, with one value for each field, newest filing first. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object actual_release_date: description: Date the subject was released. format: date nullable: true type: string additional_fields: description: >- Fields the source reported that have no named home on the record, kept verbatim so nothing it stated is dropped. Identity and demographic rows are dropped rather than carried, so a defendant's date of birth or sex never appears here. items: $ref: '#/components/schemas/LabelledValue' type: array arrest_agency: description: The agency that made the arrest. nullable: true type: string arrest_date: description: Date of the arrest that led to the case. format: date nullable: true type: string bail_set_amount: description: Bail set as a decimal string; null when none was set. nullable: true type: number booking_number: description: The booking number, which links toward an arrest. nullable: true type: string case_link: description: A link to the case on the court's own system. nullable: true type: string case_number_raw: description: The number the court filed the case under, as the source wrote it. nullable: true type: string case_status_date: description: Date that standing was recorded. format: date nullable: true type: string case_status_raw: description: Where the case stands, in the court's own words. nullable: true type: string case_title: description: >- How the court captioned the case, such as STATE OF ARIZONA VS PORFIRIO NINO. nullable: true type: string categories: description: >- What kind of offending this is, classified by Heron. A case can fall into several. items: enum: - violent - murder_homicide - domestic_violence - burglary - fraud - sex_offense - child_related - fiduciary - animal_cruelty - drug - dui - other type: array category: description: >- `criminal`, `traffic` where the offence is a traffic matter, or `unknown`. Traffic is a criminal case and is kept here, labelled so a policy can set it aside. enum: - criminal - traffic - unknown charges: description: >- Every count charged, each with its own plea, verdict, sentence and outcome. A case that convicts on one count and dismisses another says so here and nowhere else: there is no case-level sentence or plea, because a single value could disagree with this list. items: $ref: '#/components/schemas/CriminalCharge' type: array citation_number: description: The citation number, on traffic matters. nullable: true type: string court_county: description: County of the court that heard the case. nullable: true type: string court_raw: description: The court that heard the case, as the source named it. nullable: true type: string crime_date: description: Date the offence was committed. format: date nullable: true type: string disposition_date: description: Date the case was disposed of. format: date nullable: true type: string disposition_raw: description: >- How the case as a whole ended, in the court's own words. Each count carries its own outcome under `charges`, and they can differ. nullable: true type: string docket_entries: description: The proceedings timeline, where the source reports one. items: $ref: '#/components/schemas/DocketEntry' type: array docket_number: description: >- A second number some courts assign; null where the court assigns none. nullable: true type: string filed_date: description: Date the case was filed with the court. format: date nullable: true type: string general_category: description: >- A broader grouping the source states, such as TRAFFIC OFFENSE or BAD CHECKS. nullable: true type: string grade: description: >- How serious the case is, graded by Heron from what the source stated. Null where only the courts vendor reported the case, because a docket states no offence to grade. enum: - felony - misdemeanor - petty_misdemeanor - infraction - unknown - null nullable: true is_dismissed: description: >- True when the case ended without a conviction on any count; null where no source stated an outcome, which is not the same as a case still open. nullable: true type: boolean is_felony: description: >- True when Heron graded any count of the case a felony; null where nothing graded it. nullable: true type: boolean is_felony_charge: description: >- True when a felony was charged; null when the source states neither way. nullable: true type: boolean is_felony_conviction: description: >- True when a felony was convicted. Charged and convicted are separate facts and neither implies the other, so both are kept. nullable: true type: boolean is_misdemeanor_charge: description: >- True when a misdemeanor was charged; null when the source states neither way. nullable: true type: boolean is_misdemeanor_conviction: description: >- True when a misdemeanor was convicted; null when the source states neither way. nullable: true type: boolean is_unclassified: description: >- True when the offence text was not recognised, so `grade` and `categories` say little. Null where there was no offence text to recognise. nullable: true type: boolean mugshot_record_id: description: >- The source's reference for a booking photograph, which the mugshot route serves. The reference travels; the image never does. nullable: true type: string offense_location: description: Where the offence was committed. nullable: true type: string parole_status: description: Parole standing recorded on the case. nullable: true type: string probation_end_date: description: Date probation ends. format: date nullable: true type: string probation_violation: description: Any probation violation recorded on the case. nullable: true type: string projected_release_date: description: Date the subject is due to be released. format: date nullable: true type: string publication_date: description: Date the source published the record. format: date nullable: true type: string relationships: description: Everyone and everything this record names, and in what capacity. items: $ref: '#/components/schemas/ResolvedRelationship' type: array reported_by: description: >- Every source that reported this record, so a reader can tell one two sources found from one only a single search returned. items: type: string type: array risk: description: >- Risk tier of this record: none, low, medium or high. Null where nothing graded it, which `none` would misreport as graded and found harmless. enum: - none - low - medium - high - null nullable: true severity_raw: description: How serious the source graded the case, in its own words. nullable: true type: string source_document_guid: description: The source's identifier for the document behind this record. nullable: true type: string source_name: description: Which body's records reported the case, such as DISTRICT COURTS. nullable: true type: string source_state: description: >- The state whose records named the case. Written as a two-letter code by the background check and as the court location's full name by the courts vendor. nullable: true type: string type: object ResolvedLawsuit: description: One civil case, with one value for each field, newest filing first. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object additional_fields: description: >- Fields the source reported that have no named home on the record, kept verbatim so nothing it stated is dropped. Rows naming a person, a place or a phone line are dropped rather than carried, because each of those is a thing the case links to. items: $ref: '#/components/schemas/LabelledValue' type: array case_category_raw: description: The broad half of the source's own taxonomy, such as CIVIL. nullable: true type: string case_link: description: A link to the case on the court's own system. nullable: true type: string case_number_raw: description: The number the court filed the case under, as the source wrote it. nullable: true type: string case_sub_category_raw: description: The narrow half of it, such as DEBT COLLECTION. nullable: true type: string case_title: description: >- How the court captioned the case, such as SMITH JOHN VS ACME HOLDINGS LLC. nullable: true type: string case_type_raw: description: What kind of case it is, in the source's own words. nullable: true type: string category: description: >- What kind of claim it is, classified by Heron: `debt_collection`, `contract`, `eviction`, `employment` and the rest. `other` means the source stated a kind that maps to none of them, and `unknown` that it stated none. enum: - contract - debt_collection - eviction - small_claims - personal_injury - real_property - tax - employment - family - probate - other - unknown court_branch: description: Which courthouse of that court heard it, where the source names one. nullable: true type: string court_county: description: County of the court that heard the case. nullable: true type: string court_raw: description: The court that heard the case, as the source named it. nullable: true type: string court_state: description: >- The state the case was filed in. Written as a two-letter code by the background check and as the court location's full name by the courts vendor. nullable: true type: string demand_amount: description: What the claim asked for, as a decimal string. nullable: true type: number disposition_date: description: Date the case was disposed of. format: date nullable: true type: string disposition_raw: description: How the case ended, in the court's own words. nullable: true type: string division: description: The court's own division, such as CIVIL or PROBATE. nullable: true type: string docket_entries: description: The proceedings timeline, where the source reports one. items: $ref: '#/components/schemas/DocketEntry' type: array filed_date: description: Date the case was filed with the court. format: date nullable: true type: string filing_office_name: description: The office that holds the filing, where the source names one. nullable: true type: string is_active: description: True when Heron reads the case as still live. nullable: true type: boolean is_mca: description: >- True when the claimant is a merchant cash advance funder Heron recognises. nullable: true type: boolean judgment_amount: description: >- What the court awarded, as a decimal string. Two fields rather than one amount and a type, because a case can state both what was asked for and what was granted. nullable: true type: number nature_of_suit_code: description: >- The federal courts' controlled nature-of-suit code. Stated by the background check only; the courts vendor writes the same fact as text into `nature_of_suit_raw`. nullable: true type: string nature_of_suit_raw: description: 'The nature of suit as the source wrote it, such as CONTRACT: OTHER.' nullable: true type: string relationships: description: Everyone and everything this record names, and in what capacity. items: $ref: '#/components/schemas/ResolvedRelationship' type: array reported_by: description: >- Every source that reported this record, so a reader can tell one two sources found from one only a single search returned. items: type: string type: array risk: description: >- Risk tier of this record: none, low, medium or high. Null on a case only the courts vendor reports, which Heron grades no tier for. enum: - none - low - medium - high - null nullable: true satisfaction_date: description: Date the judgment was satisfied. format: date nullable: true type: string source_document_guid: description: The source's identifier for the document behind this record. nullable: true type: string source_name: description: Which body's records reported the case, such as CIVIL COURTS. nullable: true type: string status: description: >- Where the case stands, classified by Heron: `open`, `closed`, `judgment`, `dismissed` or `unknown`. A dismissal outranks the court's own open/closed field, which routinely still reads open on a dismissed case. `unknown` is the honest answer for every case the courts vendor reports from the federal docket, which states no status at all. enum: - open - closed - judgment - dismissed - unknown status_date: description: Date that standing was recorded. format: date nullable: true type: string vendor_case_id: description: >- The courts vendor's own identifier for the case; null on any other source. nullable: true type: string venue: description: The venue the source states for the case. nullable: true type: string type: object ResolvedLienJudgment: description: One recorded debt, with one value for each field, newest filing first. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object additional_fields: description: >- Fields the source reported that have no named home on the record, kept verbatim so nothing it stated is dropped. Where a partial SSN appears it carries the first five digits only; the full SSN is never persisted or surfaced. items: $ref: '#/components/schemas/LabelledValue' type: array amount: description: >- The debt as a decimal string, counted once: an original and its release state one debt between them, never two. Null when no filing states an amount. nullable: true type: number amount_band: description: >- Amount band: none, small under $10,000, medium from $10,000 to $49,999.99, or large at $50,000 or more. enum: - none - small - medium - large amount_source_raw: description: >- Which part of the filing the amount was read from; null when no amount. nullable: true type: string case_status: description: >- Where the debt stands once every filing recording it is read together: open, released, vacated or closed. Anything but open means it is no longer outstanding. Null on records where the source does not state a net disposition. enum: - open - released - vacated - closed - null nullable: true certificate_number: description: >- A further number the office issued for the same filing. Present where the office numbers certificates separately, and null otherwise. nullable: true type: string control_number: description: A county control number; stated only by New York records. nullable: true type: string court_code: description: >- The source's own code for the office. Written three different ways depending on which record shape carried the filing, so read `filing_office_name` and `filing_county` instead of comparing two of these. nullable: true type: string creditor_count: description: >- How many creditors the filing names. Above one it is a bulk court-index filing bundling unrelated debts, so the creditor named cannot be taken as this subject's. type: integer creditor_level_raw: description: >- Which level of government the creditor is, where the source states one. nullable: true type: string expiration_date: description: Date the filing lapses, where the recorder states one. format: date nullable: true type: string file_date: description: Date the filing was recorded; null when unavailable. format: date nullable: true type: string filing_county: description: County of the recording office. nullable: true type: string filing_number_raw: description: >- The number the office recorded the filing under, as the source wrote it. nullable: true type: string filing_office_name: description: >- The office that recorded the filing, such as a county recorder or a Secretary of State. A lien is recorded rather than tried, so this is often not a court. nullable: true type: string filing_relationship: description: >- How this filing relates to the one it is paired with: `release_of` or `vacate_of` on the filing that ends the debt, `released_by` or `vacated_by` on the original. Null when unpaired. nullable: true type: string filing_state: description: State of the recording office. nullable: true type: string hidden_filing_number: description: >- An internal number the source holds for the filing; null when it states none. nullable: true type: string irs_serial_number: description: >- The IRS serial number of a federal tax lien; null on any other filing. nullable: true type: string is_mca_creditor: description: >- True when the creditor is a known merchant cash advance funder; null where no filing stated anything to match a funder against. nullable: true type: boolean is_open_federal_tax_lien: description: >- True when the filing is a federal tax lien and is still outstanding; null where no filing stated it. nullable: true type: boolean is_open_judgment: description: >- True when the filing is a judgment and is still outstanding; null where no filing stated it. nullable: true type: boolean is_open_state_tax_lien: description: >- True when the filing is a state tax lien and is still outstanding. Each of these four reads false once the filing is released, so read `type_of_filing_raw` for what it was, and null where no filing stated it, which false would report as a settled question. nullable: true type: boolean is_open_tax_lien: description: >- True when the filing is any tax lien and is still outstanding; null where no filing stated it. nullable: true type: boolean is_released: description: >- True when the source no longer shows the debt as outstanding. Vacated and closed filings are included, not only released ones. Null where no filing stated a status, which false would misreport as still outstanding. nullable: true type: boolean kind_of_claim: description: >- What the filing is at heart: `lien`, `judgment`, `release` where the filing ends an earlier one, or `unknown`. A tax warrant reads as a lien, because it is a state's way of recording one. enum: - lien - judgment - release - unknown original_filing_number: description: >- The filing this one amends or releases, as the source wrote it. Usually null on a filing that has been released, because the pairing is stated on `related_filing_number` instead. nullable: true type: string perfected_date: description: Date the lien was perfected, where the recorder states one. format: date nullable: true type: string record_shape: description: Which of the source's record shapes carried this filing. nullable: true type: string related_filing_number: description: >- The filing this one is paired with, whether it releases this one or is released by it. Null when the filing stands alone. nullable: true type: string relationships: description: Everyone and everything this record names, and in what capacity. items: $ref: '#/components/schemas/ResolvedRelationship' type: array release_date: description: Date the lien was released; null when unreleased. format: date nullable: true type: string reported_by: description: >- Every source that reported this record, so a reader can tell one two sources found from one only a single search returned. items: type: string type: array risk: description: >- Risk tier of this record: none, low, medium or high. Null where nothing graded it, which `none` would misreport as graded and found harmless. enum: - none - low - medium - high - null nullable: true satisfaction_date: description: Date the debt was satisfied as recorded; null when unavailable. format: date nullable: true type: string source_document_guid: description: >- The source's own identifier for the document behind this record, so a reader can quote it back to the source. Null when the source states none. nullable: true type: string status: description: >- The standing the recorder wrote on the filing itself: open, released, satisfied, vacated, void, terminated, withdrawn or unknown. It cannot see a later filing that ends the debt, so `open` here is not a claim that the debt is still outstanding; `case_status` is. enum: - open - released - satisfied - vacated - void - terminated - withdrawn - unknown status_date: description: Date that standing was recorded; null when unavailable. format: date nullable: true type: string type_of_action_raw: description: The action the filing records, in the recorder's words. nullable: true type: string type_of_filing_raw: description: >- What was filed, in the recorder's words, such as JUDGMENT LIEN or FEDERAL TAX LIEN. nullable: true type: string type_of_satisfaction_raw: description: How the debt was satisfied, in the recorder's words. nullable: true type: string type_of_tax_raw: description: Which tax a tax lien secures, in the recorder's words. nullable: true type: string vacate_date: description: Date a judgment was vacated; null when it was not. format: date nullable: true type: string type: object ResolvedOwner: description: >- An owner an application form declared, best attested first: an owner a report also found leads one only a form named, then the largest stated share. Only an application form declares an owner, so a person a report returned under an owner's search is not one. Where the sources spelled the name differently, `name` is the spelling to show: the deal's own leads when it stated one. The other spellings are not in this response. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object aliases: description: >- Every other spelling a source stated for this person, in precedence order. `name` is the one to show; these are the ones it was chosen over. Empty when the sources agreed. items: $ref: '#/components/schemas/PersonName' type: array country_of_residence: description: Country of residence. No source read today states one, so null. nullable: true type: string credit_scores: description: >- One score per `score_model`, in the order `fico`, `vantagescore`, `unknown`: the score whose newest statement came last, from any source. An edit counts as a new statement. Older scores of the same model, and a model no source scored, are absent. items: $ref: '#/components/schemas/ResolvedCreditScore' type: array date_of_birth: allOf: - $ref: '#/components/schemas/PartialDate' description: >- Read as parts, because a source can state a year and a month with no day. Null unless a source stated one. Only the application does today, so in practice only a person the deal applied with carries one. nullable: true deceased_on: description: >- Date of death where a source states one; null under the same limit as above. format: date nullable: true type: string emails: description: Every email address every source stated. items: $ref: '#/components/schemas/SourcedEmail' type: array heron_id: description: >- The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity. nullable: true type: string home_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where they live; null when no source placed them. nullable: true home_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: A number a source called a home number; null when none did. nullable: true is_deceased: description: >- Whether a source records this person as deceased. Null until the parser surfaces the subject's own profile; it reads the indicator for an associate only. nullable: true type: boolean mobile_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: >- The line a reviewer would ring: every number a source did not call a home number, including one stated with no kind at all. Null when no source reported one. nullable: true name: allOf: - $ref: '#/components/schemas/PersonName' description: >- The one name to show, broken into its parts. Null when no source stated one. nullable: true national_ids: description: Every identifier every source stated. items: $ref: '#/components/schemas/SourcedNationalId' type: array nationalities: description: Every nationality a source stated. items: $ref: '#/components/schemas/SourcedNationality' type: array other_addresses: description: >- Every other place a source put this party, which the named address fields chose one of. No span is stated, so this is where a subject has been read, not when. Empty when every place a source stated is already named above. items: $ref: '#/components/schemas/ResolvedAddress' type: array ownership_percentage: description: The share the form stated, out of 100. Null when it stated none. nullable: true type: number slot: description: >- The owner position on the application form: `owner_1` or `owner_2`. Null when no form stated one. One person can be owner 1 on one form and owner 2 on another. nullable: true type: string subject_type: description: >- Which of the submission's own subjects this row is, so you can tell them apart from everything the searches turned up around them. Set differently for the two, because only one of them is certain. `business`: the company being underwritten. A deal has one, and every source is searched for it, so a company row carries this even when no application form named one and however differently a registry or a directory spells the name. `owner`: a person the submission declared as an owner, which only an application form states. A person a report returned is null even when that report searched under an owner, because a relative or a namesake found by that search is a finding and not a declared owner. Several rows can hold `owner`, since a submission names any number of them, and the order the owners are returned in answers which one leads. Null: every other row. For people that is the usual case, covering relatives, court parties and officers of other companies. For a company it means one reached through a finding, such as another company an owner holds an office in. enum: - owner - business - null nullable: true type: object ResolvedTaxIdVerification: description: >- One check of one identifier against one name, and the authority's answer. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object checked_on: description: When the check was made; null when the source states no date. format: date nullable: true type: string identifier: allOf: - $ref: '#/components/schemas/CompanyId' description: >- The identifier that was checked, as it was sent. Its own `verified` is always null here. name_checked: description: The business name the identifier was checked under, as sent. type: string outcome: description: >- `matched` when the authority confirms the identifier belongs to a business of that name, `not_matched` when it does not. A call that returned an error is not a row. enum: - matched - not_matched relationships: description: Everyone and everything this record names, and in what capacity. items: $ref: '#/components/schemas/ResolvedRelationship' type: array reported_by: description: >- Every source that reported this record, so a reader can tell one two sources found from one only a single search returned. items: type: string type: array type: object CompanyAliasWrite: additionalProperties: false description: Any name but the legal one, which is `name`. properties: effective_from: description: Date the name started, when a source states one. format: date nullable: true type: string effective_to: description: Date the name ended, when a source states one. format: date nullable: true type: string raw: description: The name exactly as the source wrote it, including its legal form. type: string type: description: >- What type of name it is: `legal` is the name a source answers with, `former` a name a registry held before the current one, `dba` a name the company trades under, and `trade` a name a report lists as an alternate. enum: - legal - dba - former - trade type: object AddressWrite: additionalProperties: false properties: city: description: Town or city; null when the address could not be split. nullable: true type: string country: description: Country of the address; null when no state was read. nullable: true type: string heron_id: description: >- The address or phone this states something about, as `GET /end_users/{id}/details` returned it. Omit it to declare a new one. nullable: true type: string line_1: description: Street and building number; null when unavailable. nullable: true type: string line_2: description: Flat, unit or suite; null when none was stated. nullable: true type: string postcode: description: ZIP code, with its four-digit extension when stated. nullable: true type: string region: description: State, province or county; null when unavailable. nullable: true type: string type: object PhoneWrite: additionalProperties: false properties: heron_id: description: >- The address or phone this states something about, as `GET /end_users/{id}/details` returned it. Omit it to declare a new one. nullable: true type: string raw: description: The number exactly as the source wrote it. type: string type: object EmailWrite: additionalProperties: false properties: email_address: description: The address as the source states it. type: string type: object CompanyIdWrite: additionalProperties: false properties: country: description: >- The country that issues this type of identifier, as a two-letter code. Null when the identifier belongs to no one country: a DUNS number is issued worldwide by one agency, so it says nothing about where the company is. nullable: true type: string type: description: >- Which identifier it is: `us_ein`, `duns`, `uk_company_number` or `vat`. enum: - us_ein - us_taxpayer_number - duns - uk_company_number - vat value: description: The identifier as the source states it. type: string type: object LegalNameWrite: additionalProperties: false properties: effective_from: description: Date the name started, when a source states one. format: date nullable: true type: string effective_to: description: Date the name ended, when a source states one. format: date nullable: true type: string raw: description: The name exactly as the source wrote it, including its legal form. type: string type: object PartialDateWrite: additionalProperties: false properties: day: description: Day of the month; null when the source states none. nullable: true type: integer month: description: Month, 1 to 12; null when the source states none. nullable: true type: integer year: description: Four-digit year; null when the source states none. nullable: true type: integer type: object WebsiteWrite: additionalProperties: false properties: website: description: The address as the source states it. type: string type: object PersonAliasWrite: additionalProperties: false description: Any name but the legal one, which is `name`. properties: given: description: Given name; null when the name could not be split. nullable: true type: string middle: description: Middle name or initial; null when none was stated. nullable: true type: string prefix: description: Title such as Dr; null when none was stated. nullable: true type: string suffix: description: Generational suffix such as Jr or III; null when none. nullable: true type: string surname: description: Surname; null when the name could not be split. nullable: true type: string type: description: >- What type of name it is: `legal` is the name a source answers with, and `aka` a further spelling the same source holds for the person. `maiden` and `former` are not stated by any source read today. enum: - legal - aka - maiden - former type: object CreditScoreWrite: additionalProperties: false properties: bureau: description: The bureau that produced the score; null or omitted when unknown. enum: - equifax - experian - transunion - unknown - null nullable: true heron_id: description: >- The credit score entity returned by GET. Omit it to declare a new score. nullable: true type: string score: description: The numeric score to state for this owner. type: integer score_model: description: The scoring model family; null or omitted when unknown. enum: - fico - vantagescore - unknown - null nullable: true score_version_raw: description: >- The scoring model version, such as `8`; null or omitted when unknown. nullable: true type: string scored_on: description: >- The date the score was calculated, in ISO 8601 format; null or omitted when unknown. format: date nullable: true type: string required: - score type: object PersonNameWrite: additionalProperties: false properties: given: description: Given name; null when the name could not be split. nullable: true type: string middle: description: Middle name or initial; null when none was stated. nullable: true type: string prefix: description: Title such as Dr; null when none was stated. nullable: true type: string suffix: description: Generational suffix such as Jr or III; null when none. nullable: true type: string surname: description: Surname; null when the name could not be split. nullable: true type: string type: object NationalIdWrite: additionalProperties: false properties: country: description: ISO country code of the issuer. type: string expires_on: description: Expiry, where the source states one. format: date nullable: true type: string state: description: Issuing state, for a driving licence; null otherwise. nullable: true type: string type: description: >- Which identifier this is: `us_ssn`, `ca_sin`, `uk_nino`, `driving_licence` or `passport`. enum: - us_ssn - ca_sin - uk_nino - driving_licence - passport value: description: The identifier as stated. type: string type: object ResolvedAddress: description: >- One place, with the source of each of its own fields. Which place it is, the field name says. One place read by two parties reads the same for both, so its sources are its own. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object city: description: Town or city; null when the address could not be split. nullable: true type: string country: description: Country of the address; null when no state was read. nullable: true type: string heron_id: description: >- The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity. nullable: true type: string is_po_box: description: True when the address names a PO box rather than a building. type: boolean line_1: description: Street and building number; null when unavailable. nullable: true type: string line_2: description: Flat, unit or suite; null when none was stated. nullable: true type: string postcode: description: ZIP code, with its four-digit extension when stated. nullable: true type: string raw: description: The address exactly as the source wrote it, in one line. type: string region: description: State, province or county; null when unavailable. nullable: true type: string type: object ResolvedPhone: description: >- One line, with the source of each of its own fields. Which line it is, the field name says. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object country_code: description: >- Dialling code without the plus. `1` for every source read today, all of which are American. Null when the source stated nothing readable as a number. nullable: true type: string heron_id: description: >- The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity. nullable: true type: string is_valid: description: >- False when the digits form no number the plan allows. Such a line resolves against nothing, so a number read against the wrong country never joins a real one. type: boolean line_type: description: >- What kind of line the numbering plan says this is, such as `mobile` or `fixed_line`. A fact about the number, unlike the relationship's type, which is one party's use of it. enum: - fixed_line - mobile - fixed_line_or_mobile - toll_free - premium_rate - shared_cost - voip - personal_number - pager - universal_access_number - voicemail - unknown national_destination_code: description: >- The area code a caller dials to reach this number's area. Its length is set by each country's numbering plan, so it is read from that plan rather than from the digits. Null when the plan does not recognise the number. nullable: true type: string normalized: description: >- The one canonical form of this number, its E.164 form, as `+17635550143`. Two records are the same line when this matches, so unlike an address nothing is scored. Never includes an extension: E.164 addresses the switchboard, and the extension is on the relationship. Null when the source stated nothing readable as a number. nullable: true type: string raw: description: The number exactly as the source wrote it. type: string subscriber_number: description: The line itself, after the country code and the area code. nullable: true type: string type: object PartialDate: properties: day: description: Day of the month; null when the source states none. nullable: true type: integer month: description: Month, 1 to 12; null when the source states none. nullable: true type: integer year: description: Four-digit year; null when the source states none. nullable: true type: integer type: object SourcedEmail: description: One email address, and the source that stated it. properties: email_address: description: The address as the source states it. type: string source: description: >- The source this value was taken from. A list unions what every source stated, so the source sits on the value rather than on the field. nullable: true type: string type: object SourcedCompanyId: description: >- One identifier, the authority's answer on it, and the source that stated it. properties: country: description: >- The country that issues this type of identifier, as a two-letter code. Null when the identifier belongs to no one country: a DUNS number is issued worldwide by one agency, so it says nothing about where the company is. nullable: true type: string source: description: >- The source this value was taken from. A list unions what every source stated, so the source sits on the value rather than on the field. nullable: true type: string type: description: >- Which identifier it is: `us_ein`, `duns`, `uk_company_number` or `vat`. enum: - us_ein - us_taxpayer_number - duns - uk_company_number - vat value: description: The identifier as the source states it. type: string verified: description: >- What an authority said when asked about this identifier under this business's name: `matched` or `not_matched`. Null when no check was run for it, and always null on the identifier inside a `tax_id_verifications` row, which is the check itself. enum: - matched - not_matched - null nullable: true type: object SourcedNationalId: description: One national identifier, and the source that stated it. properties: country: description: ISO country code of the issuer. type: string expires_on: description: Expiry, where the source states one. format: date nullable: true type: string source: description: >- The source this value was taken from. A list unions what every source stated, so the source sits on the value rather than on the field. nullable: true type: string state: description: Issuing state, for a driving licence; null otherwise. nullable: true type: string type: description: >- Which identifier this is: `us_ssn`, `ca_sin`, `uk_nino`, `driving_licence` or `passport`. enum: - us_ssn - ca_sin - uk_nino - driving_licence - passport value: description: The identifier as stated. type: string type: object SourcedNationality: description: One nationality, and the source that stated it. properties: nationality: description: The nationality as the source states it. type: string source: description: >- The source this value was taken from. A list unions what every source stated, so the source sits on the value rather than on the field. nullable: true type: string type: object ResolvedRelationship: description: >- One thing standing in a named capacity to another, with the party on the other end stated inside it: a debtor on a lien, an officer on a filing, the company a filing registers. properties: entity: allOf: - $ref: '#/components/schemas/ResolvedParty' description: >- The party on the other end of the link, in full. It has no `relationships` of its own, because each link already shows from both ends. filed_as: description: >- On a `filed` link, the company name as the registry wrote it on this filing. The party on the other end may lead with another of its names, so this is where to read what was registered. Null on any other capacity. nullable: true type: string first_reported: description: >- Earliest date a source placed this party here; null unless the relationship is to an address and a source stated one. format: date nullable: true type: string last_reported: description: >- Latest date a source placed this party here; null when none was stated. format: date nullable: true type: string match_confidence: description: >- Heron's confidence that the party this record names is the deal's subject: `high`, `medium` or `low`, scored from how well the names agree. Null unless the link is from a party to a `court` record. nullable: true type: string owed_amount: description: >- What this record says this party owes on it, as a decimal string. A lien can name many debtors and give each their own share, so this is that party's share and not the total on the record. Null on any other capacity, and on a debtor the record gave no share. nullable: true type: number ownership_percentage: description: >- The share the application states for an owner; null on other relationships. nullable: true type: number reported_date: description: Date the relationship was recorded on the record. format: date nullable: true type: string slot: description: >- The owner box the application form wrote this owner in, `owner_1` or `owner_2`. One person can sit in different boxes on different forms, so it describes this relationship rather than the person. Null on any other capacity. nullable: true type: string title: description: >- The office an officer holds, in the registry's own words, such as President or Managing Member. Null on any other capacity, and on an officer the registry gave no office. nullable: true type: string type: description: >- The capacity, such as `debtor`, `trustee` or `officer`. Always lower case with words joined by underscores, whoever stated it. `registered_agent` accepts legal papers for the company. `filed` joins a company to a filing it made. A link to an address says what the place is used for: `physical`, `mailing`, `home`, `billing`, `previous`, `registered_office`, `service_of_process` where a registered agent accepts service, or `filing_office` where a record was recorded. `has_address` when a source states a place for a party and no use for it. Null when a source names the party but not the capacity. nullable: true type: string type: object SourcedWebsite: description: One website, and the source that stated it. properties: source: description: >- The source this value was taken from. A list unions what every source stated, so the source sits on the value rather than on the field. nullable: true type: string website: description: The address as the source states it. type: string type: object LabelledValue: properties: label: description: The source's own name for the field, kept verbatim. type: string source: description: The source that stated this. type: string value: description: The value the source reported. nullable: true type: string type: object DocketEntry: properties: date_filed: description: Date the entry was filed; null when unavailable. format: date nullable: true type: string description: description: The entry text as the court recorded it. nullable: true type: string entry_number: description: The entry's number on the docket. nullable: true type: string source: description: The source that stated this. type: string type: object Meeting341: properties: date_held: description: Date of the meeting; null when unavailable. format: date nullable: true type: string location: description: Where the meeting is held. nullable: true type: string source: description: The source that stated this. type: string time: description: Time of the meeting as the source wrote it. nullable: true type: string type: object CompanyName: properties: effective_from: description: Date the name started, when a source states one. format: date nullable: true type: string effective_to: description: Date the name ended, when a source states one. format: date nullable: true type: string raw: description: The name exactly as the source wrote it, including its legal form. type: string type: description: >- What type of name it is: `legal` is the name a source answers with, `former` a name a registry held before the current one, `dba` a name the company trades under, and `trade` a name a report lists as an alternate. enum: - legal - dba - former - trade type: object CriminalCharge: properties: additional_fields: description: >- Fields the source reported about this count that have no named home on it, kept verbatim. Identity and demographic rows never appear here. items: $ref: '#/components/schemas/LabelledValue' type: array counts: description: How many counts of this offence were charged. nullable: true type: integer disposition_date: description: Date this count was disposed of. format: date nullable: true type: string disposition_raw: description: How this count ended, in the court's own words. nullable: true type: string fee_amount: description: Court fees on this count as a decimal string. nullable: true type: number fine_amount: description: Fine imposed on this count as a decimal string. nullable: true type: number is_duplicate_report: description: >- True when the source published this same count twice, which happens where a district and a circuit both report one docket. Counting it once is the reader's decision to make, so both are shown and the second is flagged. type: boolean max_sentence_months: description: The maximum sentence in months, where the court states one. nullable: true type: integer offense_raw: description: What was charged, in the court's own words. nullable: true type: string parole_status: description: Parole standing recorded against this count. nullable: true type: string plea_date: description: Date the plea was entered. format: date nullable: true type: string plea_raw: description: The plea entered on this count, in the court's own words. nullable: true type: string probation_months: description: Months of probation ordered, where the court states a term. nullable: true type: integer probation_violation: description: Any probation violation recorded against this count. nullable: true type: string sentence_description: description: The sentence passed on this count, in the court's own words. nullable: true type: string sequence: description: >- The count's ordinal within the case, as the court numbered it. It is what tells three counts of one offence apart when every other field on them reads the same. nullable: true type: string severity_raw: description: How serious the court graded this count, in its own words. nullable: true type: string source: description: The source that stated this count. type: string source_entry_id: description: >- The source's own reference for this count. Numbered within one search, so the same reference under a different subject is a different count. nullable: true type: string statute: description: The statute said to have been violated. nullable: true type: string verdict_raw: description: The verdict on this count, in the court's own words. nullable: true type: string warrant_date: description: Date a warrant issued on this count. format: date nullable: true type: string type: object PersonName: properties: given: description: Given name; null when the name could not be split. nullable: true type: string middle: description: Middle name or initial; null when none was stated. nullable: true type: string prefix: description: Title such as Dr; null when none was stated. nullable: true type: string raw: description: The name exactly as the source wrote it. type: string suffix: description: Generational suffix such as Jr or III; null when none. nullable: true type: string surname: description: Surname; null when the name could not be split. nullable: true type: string type: description: >- What type of name it is: `legal` is the name a source answers with, and `aka` a further spelling the same source holds for the person. `maiden` and `former` are not stated by any source read today. enum: - legal - aka - maiden - former type: object ResolvedCreditScore: description: One credit score of this owner, with the source of each field. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object bureau: description: >- The bureau that produced the score; `unknown` when the source did not identify one. enum: - equifax - experian - transunion - unknown heron_id: description: >- The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity. nullable: true type: string score: description: The numeric score the source reported. type: integer score_model: description: >- The scoring model family; `unknown` when the source did not name one. enum: - fico - vantagescore - unknown score_model_raw: description: >- The scoring model as the source named it; null when the source did not identify one. nullable: true type: string score_version_raw: description: >- The scoring model version as the source stated it, such as `8`; null when it gave none. nullable: true type: string scored_on: description: >- The date the score was calculated, in ISO 8601 format; null when the source did not report one. format: date nullable: true type: string required: - score type: object CompanyId: properties: country: description: >- The country that issues this type of identifier, as a two-letter code. Null when the identifier belongs to no one country: a DUNS number is issued worldwide by one agency, so it says nothing about where the company is. nullable: true type: string type: description: >- Which identifier it is: `us_ein`, `duns`, `uk_company_number` or `vat`. enum: - us_ein - us_taxpayer_number - duns - uk_company_number - vat value: description: The identifier as the source states it. type: string verified: description: >- What an authority said when asked about this identifier under this business's name: `matched` or `not_matched`. Null when no check was run for it, and always null on the identifier inside a `tax_id_verifications` row, which is the check itself. enum: - matched - not_matched - null nullable: true type: object ResolvedParty: description: >- One person or company a link reaches. A party the sources named and said nothing else about states its name and where that name came from, and nothing more, which is how a filing's officers and agents and a lien's creditors arrive. properties: _sources: additionalProperties: type: string description: >- Which source each single-valued field was taken from, keyed by the field name. A field several sources stated names only the source whose value is shown, and a field no source stated is absent. A list field is not here: it unions what every source stated, so each of its values names its own source. An address or a phone is not here either, because each has its own `_sources`. type: object billing_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a company is billed. nullable: true business_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a company is. nullable: true business_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: A company's line. nullable: true country_of_residence: description: Country of residence. No source read today states one, so null. nullable: true type: string date_of_birth: allOf: - $ref: '#/components/schemas/PartialDate' description: >- Read as parts, because a source can state a year and a month with no day. Null unless a source stated one. Only the application does today, so in practice only a person the deal applied with carries one. nullable: true deceased_on: description: >- Date of death where a source states one; null under the same limit as above. format: date nullable: true type: string emails: description: Every email address every source stated. items: $ref: '#/components/schemas/SourcedEmail' type: array heron_id: description: >- The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity. nullable: true type: string home_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a person lives. nullable: true home_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: A person's home line. nullable: true identifiers: description: >- Every identifier every source stated, each with the authority's answer on it. items: $ref: '#/components/schemas/SourcedCompanyId' type: array is_deceased: description: >- Whether a source records this person as deceased. Null until the parser surfaces the subject's own profile; it reads the indicator for an associate only. nullable: true type: boolean is_dissolved: description: >- True when no linked filing that states a standing is still active. When no linked filing states one, the highest-precedence source's company-level standing answers instead. A company can be revoked in one state and active in the state that formed it, so one dissolved filing does not dissolve the company. Null when no source states a standing, which is not good standing. nullable: true type: boolean mailing_address: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: Where a company's post goes. nullable: true mobile_phone: allOf: - $ref: '#/components/schemas/ResolvedPhone' description: A person's mobile line. nullable: true name: description: The one spelling to show for this party. nullable: true type: string national_ids: description: Every identifier every source stated. items: $ref: '#/components/schemas/SourcedNationalId' type: array nationalities: description: Every nationality a source stated. items: $ref: '#/components/schemas/SourcedNationality' type: array registered_office: allOf: - $ref: '#/components/schemas/ResolvedAddress' description: A company's address on the state register. nullable: true started_on: allOf: - $ref: '#/components/schemas/PartialDate' description: >- When the company started trading, read as parts because a source can state a year alone. Not the date it was formed: a business often trades for years before the entity that applies is registered, and the formation date is `formed_on` on its corporate filing. nullable: true state_of_incorporation: description: >- The state or territory where the company was incorporated. Recognised US state names and codes use one uppercase state name; null when no source states one. nullable: true type: string subject_type: description: >- Which of the submission's own subjects this row is, so you can tell them apart from everything the searches turned up around them. Set differently for the two, because only one of them is certain. `business`: the company being underwritten. A deal has one, and every source is searched for it, so a company row carries this even when no application form named one and however differently a registry or a directory spells the name. `owner`: a person the submission declared as an owner, which only an application form states. A person a report returned is null even when that report searched under an owner, because a relative or a namesake found by that search is a finding and not a declared owner. Several rows can hold `owner`, since a submission names any number of them, and the order the owners are returned in answers which one leads. Null: every other row. For people that is the usual case, covering relatives, court parties and officers of other companies. For a company it means one reached through a finding, such as another company an owner holds an office in. enum: - owner - business - null nullable: true type_of_entity: description: >- The company's legal form: llc, inc, corp, lp, llp, partnership, sole_proprietor, ltd, plc or unknown. The deal's own word for it leads, as it does for the names, so an application form stating one outranks a registry; `reported_by` names what every source said, and each corporate filing states its own `legal_form`. `unknown` when no source states one. enum: - llc - inc - corp - lp - llp - partnership - sole_proprietor - ltd - plc - co - pc - pllc - unknown websites: description: Every website every source stated. items: $ref: '#/components/schemas/SourcedWebsite' type: array type: object securitySchemes: ApiKeyAuth: in: header name: x-api-key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.