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

# Create location

> Create a location for a corporation

Create a location to track where a corporation has physical or legal presence. The address is validated against country-specific requirements.

## Request body

<ParamField body="corporation_id" type="string" required>
  The unique identifier (UUID) for the corporation.
</ParamField>

<ParamField body="address" type="object" required>
  The location address.

  <Expandable title="Address fields">
    <ParamField body="address_line_1" type="string">
      Street address.
    </ParamField>

    <ParamField body="address_line_2" type="string">
      Additional address details.
    </ParamField>

    <ParamField body="address_line_3" type="string">
      Additional address details.
    </ParamField>

    <ParamField body="city" type="string">
      City or locality.
    </ParamField>

    <ParamField body="state" type="string">
      State or province code (2-3 characters). Required for countries like US, CA, AU.
    </ParamField>

    <ParamField body="postal_code" type="string">
      ZIP or postal code.
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code (e.g., `US`, `DE`, `GB`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="location_types" type="array" required>
  Array of location types. At least one type is required.

  Values: `HEADQUARTERS`, `BRANCH_OFFICE`, `RETAIL_LOCATION`, `FACTORY`, `WAREHOUSE`, `NATURAL_RESOURCE_SITE`, `REGISTERED_OFFICE`, `REPRESENTATIVE_OFFICE`, `CONSTRUCTION_SITE`, `THIRD_PARTY_FULFILLMENT`, `REMOTE_EMPLOYEE`, `DEPENDENT_AGENT`, `INDEPENDENT_AGENT`, `REGISTRATION`, `OTHER`
</ParamField>

<ParamField body="is_primary" type="boolean">
  Whether this is the primary location for the corporation.
</ParamField>

<ParamField body="start_date" type="string" required>
  ISO date (YYYY-MM-DD) when the location became active.
</ParamField>

<ParamField body="end_date" type="string">
  ISO date (YYYY-MM-DD) when the location was closed. Leave empty for active locations.
</ParamField>

<ParamField body="is_active" type="boolean">
  Whether the location is currently active. Defaults to `true`.
</ParamField>

<ParamField body="notes" type="string">
  Optional notes about the location.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://transaction-tax.api.in.commenda.io/api/v1/locations' \
    --header 'Authorization: Bearer <your_token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
      "address": {
        "address_line_1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
      },
      "location_types": ["HEADQUARTERS", "REGISTERED_OFFICE"],
      "is_primary": true,
      "start_date": "2024-01-01"
    }'
  ```

  ```json Standard theme={null}
  {
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "address": {
      "address_line_1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "location_types": ["HEADQUARTERS", "REGISTERED_OFFICE"],
    "is_primary": true,
    "start_date": "2024-01-01"
  }
  ```

  ```json EU warehouse theme={null}
  {
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "address": {
      "address_line_1": "Friedrichstraße 100",
      "city": "Berlin",
      "postal_code": "10117",
      "country": "DE"
    },
    "location_types": ["WAREHOUSE"],
    "start_date": "2024-06-01"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Successfully created location.",
    "data": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  }
  ```

  ```json 400 - Invalid location type theme={null}
  {
    "error": {
      "type": "CLIENT_INVALID_REQUEST_BODY",
      "title": "Failed to validate the request body",
      "detail": {
        "description": "invalid location type: INVALID_TYPE"
      },
      "status": 400,
      "instance": "/api/v1/locations"
    }
  }
  ```

  ```json 400 - Missing address fields theme={null}
  {
    "error": {
      "type": "CLIENT_INVALID_REQUEST_BODY",
      "title": "Failed to validate the request body",
      "detail": {
        "description": "state is required for country US"
      },
      "status": 400,
      "instance": "/api/v1/locations"
    }
  }
  ```
</ResponseExample>