> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parcha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Associated entity schema

The Associated Entity Schema contains information about entities associated with the main business or individual. It is used for tracking Ultimate Beneficial Owners (UBOs) and other related entities in Parcha's case management system.

<Info>
  This schema is crucial for maintaining accurate records of related entities and ensuring compliance with KYB regulations.
</Info>

## Example

<CodeGroup>
  ```json Example theme={null}
  {
    "id": "parcha-ubo-test-1",
    "self_attested_data": {
      "business_name": "Example Ventures",
      "registered_business_name": "Example Ventures LLC",
      "incorporation_date": "YYYY-MM-DD",
      "is_trust": false,
      "address": {
        "street_1": "123 Business Street",
        "street_2": "Suite 100",
        "city": "Anytown",
        "state": "ST",
        "country_code": "US",
        "postal_code": "12345"
      },
      "industry": "Venture Capital",
      "tin_number": "XX-XXXXXXX",
      "is_business_owner": true,
      "business_ownership_percentage": 10,
      "website": "www.exampleventures.com",
      "description": "Example Ventures is a venture capital firm based in Anytown, State. The firm seeks to invest in companies operating in various technology-based sectors.",
      "relationship": "Investor",
      "skip_validation": false
    }
  }
  ```
</CodeGroup>

## Field Descriptions

### Case ID

<ParamField path="id" type="string" required>
  Unique identifier for the case. Used to tie cases together when running workflows and can be used to link back to internal case management systems.
</ParamField>

### Self Attested Data

<ParamField path="self_attested_data.business_name" type="string" optional>
  The name of the UBO entity
</ParamField>

<ParamField path="self_attested_data.registered_business_name" type="string" optional>
  The registered name of the business
</ParamField>

<ParamField path="self_attested_data.incorporation_date" type="string" optional>
  The incorporation date of the UBO entity, format YYYY-MM-DD
</ParamField>

<ParamField path="self_attested_data.is_trust" type="boolean" optional>
  Whether or not the UBO Entity is a trust
</ParamField>

<ParamField path="self_attested_data.address" type="Address" optional>
  The address of the business
</ParamField>

<ParamField path="self_attested_data.industry" type="string" optional>
  The industry of the UBO entity
</ParamField>

<ParamField path="self_attested_data.tin_number" type="string" optional>
  The tax identification number of the business
</ParamField>

<ParamField path="self_attested_data.is_business_owner" type="boolean" optional>
  Whether or not the UBO entity is a business owner
</ParamField>

<ParamField path="self_attested_data.business_ownership_percentage" type="number" optional>
  The business ownership percentage of the business
</ParamField>

<ParamField path="self_attested_data.website" type="string | string[]" optional>
  The website(s) of the business
</ParamField>

<ParamField path="self_attested_data.description" type="string" optional>
  The description of the business
</ParamField>

<ParamField path="self_attested_data.relationship" type="string" optional>
  The relationship of the business to the main entity
</ParamField>

<ParamField path="self_attested_data.skip_validation" type="boolean" optional>
  Whether or not to skip KYB validation, for cases when it is a well-known company
</ParamField>

## Address Object

<ResponseField name="street_1" type="string" required>
  Primary street address
</ResponseField>

<ResponseField name="street_2" type="string" optional>
  Secondary street address
</ResponseField>

<ResponseField name="city" type="string" required>
  City name
</ResponseField>

<ResponseField name="state" type="string" optional>
  State or province
</ResponseField>

<ResponseField name="postal_code" type="string" required>
  Postal or ZIP code
</ResponseField>

<ResponseField name="country_code" type="string" required>
  Two-letter country code
</ResponseField>

## Validation Rules

<Warning>
  * `incorporation_date`, if provided, must be in the format YYYY-MM-DD.
  * `business_ownership_percentage`, if provided, must be a number between 0 and 100.
  * If `website` is provided, it must be a valid URL or a list of valid URLs.
  * `description` is typically limited to a maximum length (e.g., 512 characters).
</Warning>

## Validation Process

When submitting data for the Associated Entity Schema, the system performs several validation checks:

1. Field formats are validated (e.g., date formats, URL formats).
2. Field values are checked for validity (e.g., ownership percentage range).
3. If `skip_validation` is false, additional KYB (Know Your Business) checks may be performed.

<Note>
  If any validation errors occur, the system will return a `SchemaValidationError` with details about the specific fields that failed validation.
</Note>

## Usage in API

When using this schema in API calls:

1. Provide as much information as available about the associated entity.
2. Follow the specified formats for dates, URLs, and other structured data.
3. Set `skip_validation` to true only for well-known entities where extensive KYB checks are not necessary.
4. Be prepared to handle validation errors and adjust your data accordingly.

<Card title="API Documentation" icon="book-open" href="/api-reference">
  Dive into our comprehensive API documentation to understand all available endpoints and features.
</Card>