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

# Work with companies

> List, create, update, archive, and restore companies through Floral's public API.

Use company operations to synchronize approved profile fields while Floral preserves a stable company ID. Creating with a Danish CVR can resolve the canonical company already present in the workspace.

## Prerequisites

You need `contacts:read` to list or retrieve companies and `contacts:write` to create or change them. Metadata, custom fields, archive, and restore also require Work access. Discover available company fields with the custom-field-definition endpoint before writing `customFields`.

Set these values once in your shell before running the examples:

```bash theme={null}
export FLORAL_BASE_URL="https://app.floral.so/api/v1"
export FLORAL_WORKSPACE="your-workspace"
export FLORAL_TOKEN="floral_pat_..."
```

Use a personal access token created for this workspace. The examples use synthetic IDs and values; replace them with values returned by your workspace.

<Warning>
  Keep `FLORAL_TOKEN` in a secret manager outside local development. Never commit it to source control or include it in logs.
</Warning>

## List companies

Company collections use cursor pagination. They default to active companies ordered by most recently updated.

```bash theme={null}
curl --get --fail-with-body \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/companies" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --data-urlencode "status=active" \
  --data-urlencode "lifecycleStage=PROSPECT" \
  --data-urlencode "sort=name-asc" \
  --data-urlencode "limit=20"
```

Pass a non-null `nextCursor` back as `cursor` to fetch the next page. Do not inspect or construct cursor values.

## Create or resolve a company

Create a company with a unique idempotency key. When you include `organizationNumber`, Floral can return the canonical workspace company for that CVR instead of adding a duplicate.

```bash theme={null}
export COMPANY_CREATE_KEY="01J5C2R6X4T7A9N3K8M1Q0V2WP"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/companies" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $COMPANY_CREATE_KEY" \
  --data '{
    "name": "Nordhavn Robotics",
    "organizationNumber": "12345678",
    "website": "https://nordhavn-robotics.example",
    "industry": "Industrial automation",
    "employeeCount": 85,
    "lifecycleStage": "PROSPECT",
    "metadata": {
      "source": "partner_sync"
    },
    "customFields": {
      "account_tier": "growth"
    }
  }'
```

A successful request returns `201`, a `Location` header, an `ETag`, and the complete company response. Save the company `id` and `ETag`.

## Apply a partial update

Fetch the company detail and copy its response `ETag` before changing it:

```bash theme={null}
curl --request GET --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/companies/1842" \
  --header "Authorization: Bearer $FLORAL_TOKEN"
```

Send only fields you intend to change. Omitted fields remain unchanged. An explicit `null` clears a nullable profile field or one custom-field value.

```bash theme={null}
export COMPANY_ETAG='"v1.ZXhhbXBsZS1jb21wYW55"'

curl --request PATCH --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/companies/1842" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "If-Match: $COMPANY_ETAG" \
  --data '{
    "lifecycleStage": "CUSTOMER",
    "employeeCount": 92,
    "phone": null,
    "customFields": {
      "account_tier": "enterprise",
      "former_region": null
    }
  }'
```

The response includes a new `ETag`. Replace your saved value before another update.

## Archive and restore

Archive is a reversible state change. It requires both the latest `ETag` and a unique idempotency key.

```bash theme={null}
export COMPANY_ARCHIVE_KEY="01J5C3A7V8F4Q2N6D9K0M1R5TX"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/companies/1842/archive" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Idempotency-Key: $COMPANY_ARCHIVE_KEY" \
  --header "If-Match: $COMPANY_ETAG"
```

Save the archive response's `ETag`. To restore the same stable company ID, send that value with a new key:

```bash theme={null}
export ARCHIVED_COMPANY_ETAG='"v1.ZXhhbXBsZS1hcmNoaXZlZA"'
export COMPANY_RESTORE_KEY="01J5C3N8P7W2H4Y6B9Q0K1M5DZ"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/companies/1842/restore" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Idempotency-Key: $COMPANY_RESTORE_KEY" \
  --header "If-Match: $ARCHIVED_COMPANY_ETAG"
```

Floral protects writes with two opaque values:

* Send a unique `Idempotency-Key` when an operation requires one. Retrying the identical request with the same key replays its result for 24 hours. Within that operation, reusing the key with different canonical input returns `409 IDEMPOTENCY_CONFLICT`.
* Send the latest strong `ETag` as `If-Match` when an operation changes an existing resource. A stale value returns `412 VERSION_CONFLICT`; a missing value returns `428 PRECONDITION_REQUIRED`.

Keep the quote characters around an `ETag`, and replace your saved value after every successful write. See [Reliability and retries](/developers/api/reliability) for the complete retry rules.