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

# Create a workforce calculation

> Calculate projected headcount and cost for future positions.

Use this endpoint to calculate future workforce cost without creating a worker.
Create a calculation from either a saved workforce plan or inline position
input. Calculations are immutable snapshots.

### Parameters

<ParamField body="plan" type="string">
  Workforce plan ID. When provided, Plane calculates the current positions in
  the plan using the plan's period and currency unless overridden.
</ParamField>

<ParamField body="positions" type="array">
  Inline positions to calculate.

  <Expandable title="child attributes">
    <ParamField body="positions.job" type="string">
      ID of the job catalog entry for the position.
    </ParamField>

    <ParamField body="positions.location" type="object" required>
      Position location.
    </ParamField>

    <ParamField body="positions.location.country" type="string" required>
      Two-letter country code.
    </ParamField>

    <ParamField body="positions.location.subdivision" type="string">
      State, province, or subdivision code.
    </ParamField>

    <ParamField body="positions.employer" type="object" required>
      Employer model for the position. Supported types are `employee` and
      `contractor`.
    </ParamField>

    <ParamField body="positions.starts" type="string" required>
      Position start date.
    </ParamField>

    <ParamField body="positions.ends" type="string">
      Position end date.
    </ParamField>

    <ParamField body="positions.compensation" type="object" required>
      Compensation used to calculate position cost.
    </ParamField>

    <ParamField body="positions.compensation.amount" type="string" required>
      Compensation amount in decimal format.
    </ParamField>

    <ParamField body="positions.compensation.currency" type="string" required>
      Three-letter ISO currency code.
    </ParamField>

    <ParamField body="positions.compensation.unit" type="string" required>
      Compensation unit, such as `month` or `year`.
    </ParamField>

    <ParamField body="positions.compensation.basis" type="string">
      Whether the amount is `gross` pay or `regular` pay. Use `gross` when the
      amount already includes mandatory worker earnings. Use `regular` when
      mandatory worker earnings should be calculated on top.
    </ParamField>

    <ParamField body="positions.compensation.frequency" type="string">
      Pay frequency, such as `monthly`.
    </ParamField>

    <ParamField body="positions.compensation.source" type="object">
      Source for the compensation amount. Use `{ "type": "manual" }` for manual inputs.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="period" type="object">
  Calculation period. Required when using inline `positions`; optional when
  calculating from a `plan`.

  <Expandable title="child attributes">
    <ParamField body="period.starts" type="string" required>
      Start date of the calculation period.
    </ParamField>

    <ParamField body="period.ends" type="string" required>
      End date of the calculation period.
    </ParamField>

    <ParamField body="period.frequency" type="string" required>
      Period frequency. Currently `monthly`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="currency" type="string">
  Three-letter ISO currency code for calculation totals. When omitted, Plane uses
  the first position's compensation currency.
</ParamField>

<ParamField body="metadata" type="object">
  Set of key-value pairs attached to the calculation.
</ParamField>

### Returns

Returns the created [Workforce calculation object](/reference/workforce-calculations/object).

Provide either `plan` or `positions`, but not both.

<ResponseExample>
  ```json Request theme={null}
  {
    "plan": "wfp_R8mK2pQ9xL4s"
  }
  ```

  ```json Response theme={null}
  {
    "id": "wfc_V6nP3qR9tY2m",
    "object": "workforce.calculation",
    "status": "calculated",
    "plan": "wfp_R8mK2pQ9xL4s",
    "currency": "USD",
    "period": {
      "starts": "2026-09-01",
      "ends": "2026-10-31",
      "frequency": "monthly"
    },
    "headcount": "1.0",
    "cost": {
      "total": "26400.00",
      "cash": "26400.00",
      "accrual": "0.00"
    },
    "periods": [
      {
        "period": "2026-09",
        "headcount": "1.0",
        "cost": "13200.00",
        "line_items": []
      }
    ],
    "created": "2026-05-27T12:00:00Z"
  }
  ```
</ResponseExample>