Wunderite

Legal Entities

Legal entities are organizations or entities legally permitted to enter into insurance policy contracts. On this page, we'll dive into the different legal entity endpoints you can use to manage them programmatically.

Legal entity objects represent a single legal entity in a commercial risk profile. They contain the following properties and relationships:

These properties are available only for commercial risk profiles.
  • Name
    first_named_insured
    Type
    bool
    Filterable
    Description

    Whether the organization is the first named insured on the policy

  • Name
    name
    Type
    string
    Filterable
    Sortable
    Description

    The name that appears on all official documents for the related organization

  • Name
    description
    Type
    nullable string
    Sortable
    Description

    A description of the organization and/or its operations

  • Name
    date_of_organization
    Type
    nullable string
    Filterable
    Sortable
    Description

    The date on which the organization was established

  • Name
    state
    Type
    nullable string
    Filterable
    Sortable
    Description

    The U.S. state in which the organization is legally incorporated

  • Name
    website
    Type
    nullable string
    Description

    The web address of the organization

  • Name
    fein
    Type
    nullable string
    Sortable
    Description

    The organization’s employer identification number (EIN) or Tax ID

  • Name
    dot_number
    Type
    nullable string
    Sortable
    Description

    The Department of Transportation number, identifying the organization’s commercial vehicle(s)

  • Name
    annual_sales
    Type
    nullable int
    Filterable
    Sortable
    Description

    The total USD amount of sales in goods services sold by the organization

  • Name
    annual_payroll
    Type
    nullable int
    Filterable
    Sortable
    Description

    The total USD amount of wages paid by the organization to its employees

  • Name
    fiscal_day
    Type
    nullable int
    Filterable
    Sortable
    Description

    The day beginning the organization’s fiscal year

  • Name
    fiscal_month
    Type
    nullable int
    Filterable
    Sortable
    Description

    The month beginning the organization’s fiscal year

  • Name
    business_type
    Type
    nullable enum
    Filterable
    Sortable
    Description

    The type or structure of the organization

    • Name
      C Corporation
      Description
      C Corporation
    • Name
      S Corporation
      Description
      S Corporation
    • Name
      Non-profit
      Description
      Non-profit
    • Name
      General Partnership
      Description
      General Partnership
    • Name
      Limited Liability Company
      Description
      Limited Liability Company
    • Name
      Sole Proprietorship
      Description
      Sole Proprietorship
    • Name
      Limited Liability Partnership
      Description
      Limited Liability Partnership
    • Name
      Limited Partnership
      Description
      Limited Partnership
    • Name
      DBA
      Description
      DBA
    • Name
      Trust
      Description
      Trust
    • Name
      Government
      Description
      Government
    • Name
      Municipality
      Description
      Municipality
  • Name
    notes
    Type
    nullable string
    Description

    Any additional notes or comments about the organization

  • Name
    created
    Type
    timestamp
    Filterable
    Sortable
    Description

    An ISO-8601 timestamp (UTC) indicating when the legal entity was created

  • Name
    updated
    Type
    timestamp
    Filterable
    Sortable
    Description

    An ISO-8601 timestamp (UTC) indicating when the legal entity was last updated

Learn more about including relations.
  • Name
    attachments
    Type
    Attachment[]
  • Name
    attachments.uploader
    Type
    User
    Description

    The user who uploaded the attachment

GET/api/v1/risks/{risk}/data/legal_entities

This endpoint allows you to retrieve a paginated list of all legal entities in the corresponding commercial risk profile.

Parameters

See the legal entity object for a list of all available filters and sorts.

Searchable

You can search for legal entities by providing a search query in the filter[search] parameter. The search query will be matched against a legal entity's name, description, FEIN, or DOT number.

Request

GET
/api/v1/risks/{risk}/data/legal_entities
curl -G https://app.wunderite.com/api/v1/risks/{risk}/data/legal_entities \
-H "Authorization: Bearer {token}" \
-d filter[search]=Location \
-d per_page=50

Response

{
    "data": [
        {
            "object": "legal_entity",
            "uuid": "83eae6d0-5c59-4289-9736-a2393c4b5ae9",
            "data": {
                "first_named_insured": true,
                "name": "Pied Piper",
                "description": "Pied Piper is a cutting-edge tech startup specializing in data compression and decentralized internet protocols. Founded by Richard Hendricks and his team of brilliant engineers, Pied Piper aims to revolutionize the way data is stored, transferred, and accessed on the internet.",
                "date_of_organization": "2014-04-01",
                "state": "CA",
                "website": "https:\/\/www.pidpiper.com",
                "fein": "458692037",
                "dot_number": null,
                "annual_sales": 13040020,
                "annual_payroll": 11067020,
                "fiscal_day": 1,
                "fiscal_month": 1,
                "business_type": "C Corporation",
                "notes": null
            },
            "meta": {
                "created": "2024-04-18T18:06:17+00:00",
                "updated": "2025-02-03T19:12:48+00:00"
            }
        },
        {
            "object": "legal_entity",
            "uuid": "f5b8ca66-9315-4cd2-b2bf-67eb8fd584aa",
            "data": {
                "first_named_insured": false,
                "name": "Pied Piper, Inc.",
                "description": "Pied Piper, Inc. is the official corporate entity behind the innovative tech startup Pied Piper. With a focus on product development and market expansion, Pied Piper, Inc. drives the company's strategic vision forward.",
                "date_of_organization": "2015-02-12",
                "state": "CA",
                "website": "https:\/\/www.pidpiperinc.com",
                "fein": "783049256",
                "dot_number": null,
                "annual_sales": 75000000,
                "annual_payroll": 65000000,
                "fiscal_day": 12,
                "fiscal_month": 3,
                "business_type": "DBA",
                "notes": null
            },
            "meta": {
                "created": "2024-04-18T18:06:17+00:00",
                "updated": "2025-02-03T19:13:00+00:00"
            }
        }
    ],
    "path": "https:\/\/app.wunderite.com\/api\/v1\/risks\/d10e34bb-4420-47de-ba9f-42a4a3f34b0e\/data\/legal_entities",
    "per_page": 50,
    "next_cursor": null,
    "next_page_url": null,
    "prev_cursor": null,
    "prev_page_url": null
}
POST/api/v1/risks/{risk}/data/legal_entities

This endpoint allows you to create new legal entities in the corresponding commercial risk profile.

At least one legal entity object must be provided in the request body.

Required properties

See all available properties in the properties section.

  • Name
    name
    Type
    string
    Description

    The name that appears on all official documents for the related organization

Caveats

First Named Insured

  • Only one legal entity can have first_named_insured set to true in a risk profile.
  • If a risk profile has no first named insured, we will automatically assign the first legal entity as the first named insured if first_named_insured is false or has no value.
  • Creating a legal entity with first_named_insured set to true will automatically set the previous first_named_insured entity to false, if it exists.
  • Attempting to create many legal entities with first_named_insured set to true in the same request will result in a validation error.

Request

POST
/api/v1/risks/{risk}/data/legal_entities
curl -X POST "https://app.wunderite.com/api/v1/risks/{risk}/data/legal_entities" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \ 
-d '{
"data": [
    {
        "object": "legal_entity",
        "data": {
            "first_named_insured": true,
            "name": "EZ Holding",
            "description": "Property Holding Company for Acme",
            "date_of_organization": "2020-01-01",
            "state": "RI",
            "website": "https:\/\/ezholding.com",
            "fein": "84-1234567",
            "business_type": "S Corporation"
        }
    }
]
}'

Response

{
    "data": [
        {
            "object": "legal_entity",
            "uuid": "75b12c61-1962-4533-bc9f-f77ddd060bfa",
            "data": {
                "first_named_insured": true,
                "name": "EZ Holding",
                "description": "Property Holding Company for Acme",
                "date_of_organization": "2020-01-01",
                "state": "RI",
                "website": "https:\/\/ezholding.com",
                "fein": "84-1234567",
                "dot_number": null,
                "annual_sales": null,
                "annual_payroll": null,
                "fiscal_day": null,
                "fiscal_month": null,
                "business_type": "S Corporation",
                "notes": null
            },
            "meta": {
                "created": "2024-01-01T00:00:00+00:00",
                "updated": "2024-01-01T00:00:00+00:00"
            }
        }
    ]
}
PATCH/api/v1/risks/{risk}/data

This endpoint allows you to perform bulk updates on legal entities.

  • At least one legal entity object must be provided in the request body. Each object must contain at least one property from the legal entity properties section.
  • Properties that are not provided will not be updated.
  • To clear a property, provide a null value.

Caveats

First Named Insured

  • Only one legal entity can have first_named_insured set to true in a risk profile.
  • Updating a legal entity with first_named_insured set to true will automatically set the previous first_named_insured entity to false, if it exists.
  • Attempting to update many legal entities with first_named_insured set to true in the same request will result in a validation error.

Attempting to update a legal entity's first_named_insured to false will throw a validation error.

To remove the first_named_insured flag from an entity, you must first update the other entity intended to have first_named_insured set to true.

Request

PATCH
/api/v1/risks/{risk}/data
curl -X PATCH "https://app.wunderite.com/api/v1/risks/{risk}/data" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \ 
-d '{
"data": [
    {
        "object": "legal_entity",
        "uuid": "83eae6d0-5c59-4289-9736-a2393c4b5ae9",
        "data": {
            "first_named_insured": true,
            "name": "Pied Piper",
            "description": "Pied Piper is a cutting-edge tech startup specializing in data compression and decentralized internet protocols. Founded by Richard Hendricks and his team of brilliant engineers, Pied Piper aims to revolutionize the way data is stored, transferred, and accessed on the internet.",
            "date_of_organization": "2014-04-01",
            "state": "CA",
            "website": "https:\/\/www.pidpiper.com",
            "fein": "458692037",
            "dot_number": null,
            "annual_sales": 13040020,
            "annual_payroll": 11067020,
            "fiscal_day": 1,
            "fiscal_month": 1,
            "business_type": "C Corporation",
            "notes": null
        }
    }
]
}'

Response

{
    "data": [
        {
            "object": "legal_entity",
            "uuid": "83eae6d0-5c59-4289-9736-a2393c4b5ae9",
            "data": {
                "first_named_insured": true,
                "name": "Pied Piper",
                "description": "Pied Piper is a cutting-edge tech startup specializing in data compression and decentralized internet protocols. Founded by Richard Hendricks and his team of brilliant engineers, Pied Piper aims to revolutionize the way data is stored, transferred, and accessed on the internet.",
                "date_of_organization": "2014-04-01",
                "state": "CA",
                "website": "https:\/\/www.pidpiper.com",
                "fein": "458692037",
                "dot_number": null,
                "annual_sales": 13040020,
                "annual_payroll": 11067020,
                "fiscal_day": 1,
                "fiscal_month": 1,
                "business_type": "C Corporation",
                "notes": null
            },
            "profile_type": "commercial"
        }
    ]
}
DELETE/api/v1/risks/{risk}/data

This endpoint allows you to bulk delete risk data, including legal entities.

At least one legal entity object must be provided in the request body to delete the corresponding legal entity.

Deleting a legal entity will also disassociate the entity from any vehicles that reference it. Deleting the first named insured legal entity will automatically assign the oldest legal entity as the first named insured.

Required properties

  • Name
    object
    Type
    string
    Description

    The object type of the data to delete. Must be legal_entity in this case.

  • Name
    uuid
    Type
    string
    Description

    The UUID of the legal entity to delete

Request

DELETE
/api/v1/risks/{risk}/data
curl -X DELETE "https://app.wunderite.com/api/v1/risks/{risk}/data" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \ 
-d '{
"data": [
    {
        "object": "legal_entity",
        "uuid": "83eae6d0-5c59-4289-9736-a2393c4b5ae9"
    }
]
}'

Response

{
    "data": [
        {
            "object": "legal_entity",
            "uuid": "83eae6d0-5c59-4289-9736-a2393c4b5ae9",
            "profile_type": "commercial"
        }
    ]
}