---
title: "Update the business and owner details of an end user"
method: PATCH
path: "/api/end_users/{end_user_heron_id}/details"
tags: ["EndUsers"]
---

# Update the business and owner details of an end user

`PATCH /api/end_users/{end_user_heron_id}/details`

## Request

- Base URL: `https://app.herondata.io`
- URL: `https://app.herondata.io/api/end_users/{end_user_heron_id}/details`
- Auth: API key in header `x-api-key`

Send only the fields that change. Fields you do not send stay as they are.

Each business, owner, address, phone and credit score in `GET /end_users/{id}/details` has a `heron_id`. To change one of them, send its `heron_id` with the fields you want to change. To add a new one, send it without a `heron_id`. The business must always include its `heron_id`, if the deal already has a business.

To remove a value you set, send `null`. For a list, `[]` removes the whole list. To remove one item from a list, send the full list again without that item, because a list replaces the previous one.

## Path parameters

- `end_user_heron_id` string, required

## Request body

- DetailsWriteSchema: Updates the business and owner details. Fields you do not send stay as they are. To remove a value you set, send `null`. The response is the same as `GET /end_users/{id}/details`.
  - `business` DetailsBusinessWrite: Business details to update.
    - `billing_address` AddressWrite
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The `heron_id` of the address or phone from `GET`. Leave it out to add a new one.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `state_province` string, nullable: State, province or county.
    - `dba` string, nullable: Trading name (DBA) of the business.
    - `emails` EmailWrite[], nullable: Email addresses of the business. Replaces the emails you sent before.
      - `email_address` string: The email address.
    - `entity_type` unknown
    - `heron_id` string, nullable: The business's `heron_id` from `GET /end_users/{id}/details`. Required if the deal already has a business.
    - `identifiers` CompanyIdWrite[], nullable: Business identifiers, such as the EIN. Replaces the identifiers you sent before.
      - `country` string, nullable: Issuing country, as a two-letter code.
      - `type` 'us_ein' | 'us_taxpayer_number' | 'duns' | 'uk_company_number' | 'vat': Type of business identifier. The prefix is the issuing country: `us_ein` (US Employer Identification Number), `us_taxpayer_number` (US state taxpayer number), `uk_company_number` (UK Companies House number), `duns` (D-U-N-S number, worldwide) or `vat` (VAT number).
      - `value` string: The identifier.
    - `legal_name` string, nullable: Legal name of the business.
    - `phone_number` PhoneWrite
      - `heron_id` string, nullable: The `heron_id` of the address or phone from `GET`. Leave it out to add a new one.
      - `raw` string: The phone number as provided.
    - `physical_address` AddressWrite
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The `heron_id` of the address or phone from `GET`. Leave it out to add a new one.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `state_province` string, nullable: State, province or county.
    - `started_on` PartialDateWrite
      - `day` integer, nullable: Day (1-31).
      - `month` integer, nullable: Month (1-12).
      - `year` integer, nullable: Year.
    - `state_of_incorporation` string, nullable: State where the business is incorporated, as a name or a two-letter code.
    - `website` string, nullable: Website of the business.
  - `owners` DetailsOwnerWrite[]: Owners to update or add. Use `heron_id` to update an existing owner. Leave it out to add a new one.
    - `aliases` PersonAliasWrite[], nullable: Other names of the owner.
      - `given` string, nullable: First name.
      - `middle` string, nullable: Middle name or initial.
      - `prefix` string, nullable: Title, for example `Dr`.
      - `suffix` string, nullable: Suffix, for example `Jr` or `III`.
      - `surname` string, nullable: Last name.
      - `type` 'legal' | 'aka' | 'maiden' | 'former': Type of name, for example `legal` or `aka`.
    - `credit_scores` CreditScoreWrite[], nullable: Credit scores of the owner. Use `heron_id` to update a score. Leave it out to add a new one.
      - `bureau` unknown
      - `heron_id` string, nullable: The `heron_id` of the score from `GET`. Leave it out to add a new one.
      - `score` integer, required: The score.
      - `score_model` unknown
      - `score_version_raw` string, nullable: Scoring model version, for example `8`.
      - `scored_on` string, date, nullable: Date of the score.
    - `date_of_birth` PartialDateWrite
      - `day` integer, nullable: Day (1-31).
      - `month` integer, nullable: Month (1-12).
      - `year` integer, nullable: Year.
    - `emails` EmailWrite[], nullable: Email addresses of the owner. Replaces the emails you sent before.
      - `email_address` string: The email address.
    - `heron_id` string, nullable: The owner's `heron_id` from `GET /end_users/{id}/details`. Leave it out to add a new owner.
    - `home_address` AddressWrite
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The `heron_id` of the address or phone from `GET`. Leave it out to add a new one.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `state_province` string, nullable: State, province or county.
    - `home_phone_number` PhoneWrite
      - `heron_id` string, nullable: The `heron_id` of the address or phone from `GET`. Leave it out to add a new one.
      - `raw` string: The phone number as provided.
    - `mobile_phone_number` PhoneWrite
      - `heron_id` string, nullable: The `heron_id` of the address or phone from `GET`. Leave it out to add a new one.
      - `raw` string: The phone number as provided.
    - `name` PersonNameWrite
      - `given` string, nullable: First name.
      - `middle` string, nullable: Middle name or initial.
      - `prefix` string, nullable: Title, for example `Dr`.
      - `suffix` string, nullable: Suffix, for example `Jr` or `III`.
      - `surname` string, nullable: Last name.
    - `national_ids` NationalIdWrite[], nullable: National identifiers, such as the SSN. Replaces the identifiers you sent before.
      - `country` string: Issuing country.
      - `expires_on` string, date, nullable: Expiry date.
      - `state` string, nullable: Issuing state, for a driving licence.
      - `type` 'us_ssn' | 'ca_sin' | 'uk_nino' | 'driving_licence' | 'passport': Type of personal identifier. The prefix is the issuing country: `us_ssn` (US Social Security Number), `ca_sin` (Canadian Social Insurance Number), `uk_nino` (UK National Insurance number), `driving_licence` or `passport`.
      - `value` string: The identifier.
    - `ownership_percentage` number, nullable: Percentage of the business the owner owns, from 0 to 100.

## Response `200`

OK

- EndUserDetailsResponseSchema: The business, its owners and the funding it applied for, with one value per field.
  - `business` ResolvedBusiness, required: The applicant's business.
    - `_sources` object: The source of each field, keyed by field name.
    - `billing_address` ResolvedAddress: An address.
      - `_sources` object: The source of each field, keyed by field name.
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_po_box` boolean: Whether the address is a PO box.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `raw` string: The full address in one line.
      - `state_province` string, nullable: State, province or county. A US state is its two-letter code.
    - `dba` string, nullable: Trading name (DBA) of the business.
    - `emails` SourcedEmail[]: Email addresses of the business.
      - `_source` string, nullable: Where this value came from.
      - `email_address` string: The email address.
    - `entity_type` unknown
    - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
    - `identifiers` SourcedCompanyId[]: Business identifiers, such as the EIN.
      - `_source` string, nullable: Where this value came from.
      - `country` string, nullable: Issuing country, as a two-letter code.
      - `type` 'us_ein' | 'us_taxpayer_number' | 'duns' | 'uk_company_number' | 'vat': Type of business identifier. The prefix is the issuing country: `us_ein` (US Employer Identification Number), `us_taxpayer_number` (US state taxpayer number), `uk_company_number` (UK Companies House number), `duns` (D-U-N-S number, worldwide) or `vat` (VAT number).
      - `value` string: The identifier.
    - `industry` ResolvedIndustry: Main industry of the business.
      - `_sources` object: The source of each field, keyed by field name.
      - `code` string, nullable: Industry code, for example `722511`.
      - `description` string, nullable: Industry name, for example `Full-Service Restaurants`.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `scheme` 'naics' | 'sic' | 'free_text': Classification system: `naics`, `sic` or `free_text`.
    - `legal_name` string, nullable: Legal name of the business.
    - `other_addresses` ResolvedAddress[]: Other addresses found for the business.
      - `_sources` object: The source of each field, keyed by field name.
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_po_box` boolean: Whether the address is a PO box.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `raw` string: The full address in one line.
      - `state_province` string, nullable: State, province or county. A US state is its two-letter code.
    - `phone_number` ResolvedPhone: A phone number.
      - `_sources` object: The source of each field, keyed by field name.
      - `country_code` string, nullable: Country calling code, without the `+`.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_valid` boolean: Whether the number is valid.
      - `line_type` 'fixed_line' | 'mobile' | 'fixed_line_or_mobile' | 'toll_free' | 'premium_rate' | 'shared_cost' | 'voip' | 'personal_number' | 'pager' | 'universal_access_number' | 'voicemail' | 'unknown': Type of line, for example `mobile` or `fixed_line`.
      - `national_destination_code` string, nullable: Area code.
      - `normalized` string, nullable: The number in international format, for example `+17635550143`.
      - `raw` string: The phone number as provided.
      - `subscriber_number` string, nullable: The number without the country and area codes.
    - `physical_address` ResolvedAddress: An address.
      - `_sources` object: The source of each field, keyed by field name.
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_po_box` boolean: Whether the address is a PO box.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `raw` string: The full address in one line.
      - `state_province` string, nullable: State, province or county. A US state is its two-letter code.
    - `social_media` BusinessSocialMedia: Social media profiles of the business.
      - `facebook` ResolvedSocialProfile: A social media profile.
        - `_sources` object: The source of each field, keyed by field name.
        - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
        - `url` string: Link to the profile.
      - `instagram` ResolvedSocialProfile: A social media profile.
        - `_sources` object: The source of each field, keyed by field name.
        - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
        - `url` string: Link to the profile.
      - `linkedin` ResolvedSocialProfile: A social media profile.
        - `_sources` object: The source of each field, keyed by field name.
        - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
        - `url` string: Link to the profile.
    - `standing` 'good' | 'not_stated' | 'not_good' | 'pending_end' | 'null', nullable: How the winning filing reads on filings and fees, null when that filing states none.
    - `started_on` PartialDate
      - `day` integer, nullable: Day (1-31).
      - `month` integer, nullable: Month (1-12).
      - `year` integer, nullable: Year.
    - `state_of_incorporation` string, nullable: State where the business is incorporated. A US state is its two-letter code.
    - `status` 'active' | 'inactive' | 'null', nullable: The company's status across its filings: `active` or `inactive`, null when no source states one.
    - `status_raw` string, nullable: The winning filing's status in the registry's own words, null when none was stated.
    - `website` string, nullable: Website of the business.
  - `custom_entities` object, required: Your custom fields, grouped by entity name. Each entity has its values and a `_sources` object with the source of each value.
  - `funding_applications` ResolvedFundingApplication[], required: The funding the business applied for, newest `received_at` first and those with none last. Each uploaded application form is one entry, and so is each set of values you or your broker sent.
    - `_sources` object: The source of each field, keyed by field name.
    - `amount_requested` number, nullable: The amount the business asked for.
    - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
    - `loan_purpose` string, nullable: What the business will use the funds for.
    - `received_at` string, date-time, nullable: When Heron received the application. Null if we do not know.
  - `owners` ResolvedOwner[], required: The business owners. Owners named by more sources come first, then the largest ownership percentage, then the order on the application.
    - `_sources` object: The source of each field, keyed by field name.
    - `aliases` PersonName[]: Other names or spellings found for the owner.
      - `given` string, nullable: First name.
      - `middle` string, nullable: Middle name or initial.
      - `prefix` string, nullable: Title, for example `Dr`.
      - `raw` string: The full name.
      - `suffix` string, nullable: Suffix, for example `Jr` or `III`.
      - `surname` string, nullable: Last name.
      - `type` 'legal' | 'aka' | 'maiden' | 'former': Type of name, for example `legal` or `aka`.
    - `country_of_residence` string, nullable: Country where the owner lives.
    - `credit_scores` ResolvedCreditScore[]: The latest credit score for each scoring model.
      - `_sources` object: The source of each field, keyed by field name.
      - `bureau` 'equifax' | 'experian' | 'transunion' | 'unknown': Credit bureau that produced the score, or `unknown`.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `score` integer, required: The score.
      - `score_model` 'fico' | 'vantagescore' | 'unknown': Scoring model, for example `fico`, or `unknown`.
      - `score_model_raw` string, nullable: Scoring model name as provided.
      - `score_version_raw` string, nullable: Scoring model version, for example `8`.
      - `scored_on` string, date, nullable: Date of the score.
    - `date_of_birth` PartialDate
      - `day` integer, nullable: Day (1-31).
      - `month` integer, nullable: Month (1-12).
      - `year` integer, nullable: Year.
    - `deceased_on` string, date, nullable: Date of death, if a source provides one.
    - `emails` SourcedEmail[]: Email addresses of the owner.
      - `_source` string, nullable: Where this value came from.
      - `email_address` string: The email address.
    - `has_signed` boolean, nullable: Whether the owner signed the application. True if they signed any of the application forms. False if the forms say they did not sign. Null if the forms do not say.
    - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
    - `home_address` ResolvedAddress: An address.
      - `_sources` object: The source of each field, keyed by field name.
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_po_box` boolean: Whether the address is a PO box.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `raw` string: The full address in one line.
      - `state_province` string, nullable: State, province or county. A US state is its two-letter code.
    - `home_phone_number` ResolvedPhone: A phone number.
      - `_sources` object: The source of each field, keyed by field name.
      - `country_code` string, nullable: Country calling code, without the `+`.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_valid` boolean: Whether the number is valid.
      - `line_type` 'fixed_line' | 'mobile' | 'fixed_line_or_mobile' | 'toll_free' | 'premium_rate' | 'shared_cost' | 'voip' | 'personal_number' | 'pager' | 'universal_access_number' | 'voicemail' | 'unknown': Type of line, for example `mobile` or `fixed_line`.
      - `national_destination_code` string, nullable: Area code.
      - `normalized` string, nullable: The number in international format, for example `+17635550143`.
      - `raw` string: The phone number as provided.
      - `subscriber_number` string, nullable: The number without the country and area codes.
    - `is_deceased` boolean, nullable: Whether the owner is recorded as deceased.
    - `mobile_phone_number` ResolvedPhone: A phone number.
      - `_sources` object: The source of each field, keyed by field name.
      - `country_code` string, nullable: Country calling code, without the `+`.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_valid` boolean: Whether the number is valid.
      - `line_type` 'fixed_line' | 'mobile' | 'fixed_line_or_mobile' | 'toll_free' | 'premium_rate' | 'shared_cost' | 'voip' | 'personal_number' | 'pager' | 'universal_access_number' | 'voicemail' | 'unknown': Type of line, for example `mobile` or `fixed_line`.
      - `national_destination_code` string, nullable: Area code.
      - `normalized` string, nullable: The number in international format, for example `+17635550143`.
      - `raw` string: The phone number as provided.
      - `subscriber_number` string, nullable: The number without the country and area codes.
    - `name` PersonName
      - `given` string, nullable: First name.
      - `middle` string, nullable: Middle name or initial.
      - `prefix` string, nullable: Title, for example `Dr`.
      - `raw` string: The full name.
      - `suffix` string, nullable: Suffix, for example `Jr` or `III`.
      - `surname` string, nullable: Last name.
      - `type` 'legal' | 'aka' | 'maiden' | 'former': Type of name, for example `legal` or `aka`.
    - `national_ids` SourcedNationalId[]: National identifiers, such as the SSN.
      - `_source` string, nullable: Where this value came from.
      - `country` string: Issuing country.
      - `expires_on` string, date, nullable: Expiry date.
      - `state` string, nullable: Issuing state, for a driving licence.
      - `type` 'us_ssn' | 'ca_sin' | 'uk_nino' | 'driving_licence' | 'passport': Type of personal identifier. The prefix is the issuing country: `us_ssn` (US Social Security Number), `ca_sin` (Canadian Social Insurance Number), `uk_nino` (UK National Insurance number), `driving_licence` or `passport`.
      - `value` string: The identifier.
    - `other_addresses` ResolvedAddress[]: Other addresses found for the owner.
      - `_sources` object: The source of each field, keyed by field name.
      - `city` string, nullable: City or town.
      - `country` string, nullable: Country.
      - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
      - `is_po_box` boolean: Whether the address is a PO box.
      - `line_1` string, nullable: Street and building number.
      - `line_2` string, nullable: Apartment, unit or suite.
      - `postal_code` string, nullable: ZIP or postal code.
      - `raw` string: The full address in one line.
      - `state_province` string, nullable: State, province or county. A US state is its two-letter code.
    - `ownership_percentage` number, nullable: Percentage of the business the owner owns, from 0 to 100.
    - `signed_date` string, date, nullable: The date the owner signed the application. If they signed more than one form, this is the most recent date. A date on a form that says they did not sign is ignored. Null if there is no date.
    - `social_media` OwnerSocialMedia: Social media profiles of the owner.
      - `facebook` ResolvedSocialProfile: A social media profile.
        - `_sources` object: The source of each field, keyed by field name.
        - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
        - `url` string: Link to the profile.
      - `instagram` ResolvedSocialProfile: A social media profile.
        - `_sources` object: The source of each field, keyed by field name.
        - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
        - `url` string: Link to the profile.
      - `linkedin` ResolvedSocialProfile: A social media profile.
        - `_sources` object: The source of each field, keyed by field name.
        - `heron_id` string, nullable: The Heron ID of this entity. Send it in `PATCH /end_users/{id}/details` to update the entity.
        - `url` string: Link to the profile.

## Other responses

- `400`: The details stated do not fit this submission
- `403`: Editing company details is not enabled for this account
- `404`: End user not found
- `422`: A body this schema cannot read, such as a key it does not name

## Changes

- **2026-11-03** `bd8008e49534`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/herondata/apis/heron-data-api/changes/api/end_users/:end_user_heron_id/details/patch.md)

---

[API](https://skmtc.dev/herondata/apis/heron-data-api.md) - [All operations](https://skmtc.dev/herondata/apis/heron-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/herondata/apis/heron-data-api/revisions/1ec936e17fef?raw)