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

# Making requests

> Choose your workspace, send JSON, and read employee responses.

## Use the API base URL

The production base URL is:

```text theme={null}
https://api.gowindmill.com/api/v2
```

Append the operation's path, including `/c/{companyId}`. Use HTTPS and `Authorization: Bearer <token>`. Send `Content-Type: application/json` when a request has a JSON body.

## Identify your workspace

The public `{companyId}` path parameter accepts either a stable company ID or a workspace URL slug. Use the **company ID** for durable integration configuration because a workspace slug can change.

* **Workspace slug:** open your workspace in the Dashboard and copy the value after `/s/` in the browser URL. For `/s/example-workspace/config/api-keys`, the slug is `example-workspace`.
* **Company ID:** ask [Windmill support](mailto:support@gowindmill.com) for your workspace's company ID and include the workspace slug. You can start with the slug while obtaining the ID; you don't need an undocumented API call.

Store your chosen value in `WINDMILL_COMPANY_ID`. The name of this environment variable doesn't change which identifiers the server accepts. API keys and OAuth tokens remain restricted to their authorized company.

### Keep identifiers distinct

An employee ID identifies a person in the org chart. A member identifies workspace access, and a user identifies an account. Use employee IDs returned by [employee search](https://help.gowindmill.com/api-reference/employees/search-employee-profiles.md) in employee paths. Treat IDs as opaque strings; don't derive them from names or email addresses.

## Read employee profiles

After [creating a read key](https://help.gowindmill.com/api-reference/authentication.md), set these environment variables locally:

```bash theme={null}
export WINDMILL_API_BASE='https://api.gowindmill.com/api/v2'
export WINDMILL_COMPANY_ID='your-company-id-or-workspace-slug'
# Load the real value from secure storage.
export WINDMILL_API_KEY='your-api-key'

curl --fail-with-body --silent --show-error \
  --request POST \
  --url "$WINDMILL_API_BASE/c/$WINDMILL_COMPANY_ID/employees/search" \
  --header "Authorization: Bearer $WINDMILL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"filter":{"status":"CURRENT"},"page":1,"pageSize":20}'
```

Searches use `POST` to accept structured JSON filters. This operation only reads data. A synthetic successful response is:

```json theme={null}
{
  "employees": [
    {
      "id": "019a1234-5678-7000-8000-000000000001",
      "name": "Avery Chen",
      "avatarUrl": null,
      "jobTitle": "Engineer",
      "managerId": null,
      "primaryEmail": "avery@example.test",
      "phoneNumber": null,
      "firstName": "Avery",
      "preferredName": null,
      "lastName": "Chen",
      "isActiveMember": false
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}
```

The response has no `data` wrapper. `pagination.total` is omitted unless you request `include: { "total": true }`. Use [Get an employee profile](https://help.gowindmill.com/api-reference/employees/get-an-employee-profile.md) when you need the additional fields documented for an individual employee.

## Choose filters and write fields

Employee searches and counts default to `filter.status: "CURRENT"`. Use `"FORMER"` for archived employees or `"ALL"` for both. Each nested `and`/`or` filter also defaults to `CURRENT`; set `status: "ALL"` on nested filters that should include archived employees.

For a [count](https://help.gowindmill.com/api-reference/employees/count-matching-employees.md) without filters, send an explicit JSON object:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST \
  --url "$WINDMILL_API_BASE/c/$WINDMILL_COMPANY_ID/employees/count" \
  --header "Authorization: Bearer $WINDMILL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

For writes, use the exact fields in the operation reference. [Create an employee](https://help.gowindmill.com/api-reference/employees/create-an-employee.md) uses `primaryEmail`. Explicit ownership claims on [profile updates](https://help.gowindmill.com/api-reference/employees/update-an-employee-profile.md) use `claimOwnership`. Field-source requests use public source identifiers such as `bamboo-hr`, `google-workspace`, and `just-works`; discover the allowed sources with [List available employee field sources](https://help.gowindmill.com/api-reference/employee-field-sources/list-available-employee-field-sources.md).

Review [pagination](https://help.gowindmill.com/api-reference/pagination.md), [rate limits](https://help.gowindmill.com/api-reference/rate-limits.md), and [error handling](https://help.gowindmill.com/api-reference/errors.md) before sending recurring or write requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.