Work with companies

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:

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.

Keep FLORAL_TOKEN in a secret manager outside local development. Never commit it to source control or include it in logs.

List companies

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

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.

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:

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.

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.

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:

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 for the complete retry rules.

Get started

Work with resources

API concepts

Prerequisites

List companies

Create or resolve a company

Apply a partial update

Archive and restore

​Prerequisites

​List companies

​Create or resolve a company

​Apply a partial update

​Archive and restore

Prerequisites

List companies

Create or resolve a company

Apply a partial update

Archive and restore