Work with people

Use person operations to synchronize stable profile fields and an optional active company link. List and detail responses are bounded to the public person contract.

Prerequisites

You need contacts:read to list or retrieve people and contacts:write to create or change them. Metadata, custom fields, lifecycle changes, archive, and restore also require Work access. 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 people

Filter by lifecycle stage, archive status, or active company. Collections use opaque cursor pagination.

curl --get --fail-with-body \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/people" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --data-urlencode "companyId=1842" \
  --data-urlencode "status=active" \
  --data-urlencode "sort=name-asc" \
  --data-urlencode "limit=20"

Pass a non-null nextCursor back as cursor for the next page. Use status=archived to find a person before restoring them.

Create a person

Creating a person requires a unique idempotency key. companyId must identify an active company in the same workspace.

export PERSON_CREATE_KEY="01J5C4B8R3W7N2M9Q0H6K1V5TX"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/people" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $PERSON_CREATE_KEY" \
  --data '{
    "name": "Ada Nielsen",
    "email": "ada.nielsen@example.com",
    "title": "Operations Director",
    "department": "Operations",
    "companyId": 1842,
    "lifecycleStage": "PROSPECT",
    "metadata": {
      "source": "partner_sync"
    },
    "customFields": {
      "preferred_language": "da"
    }
  }'

A successful request returns 201, a canonical Location, and the new person’s ETag.

Apply a partial update

Retrieve the person first and copy the response ETag:

curl --request GET --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/people/731" \
  --header "Authorization: Bearer $FLORAL_TOKEN"

Send only changed fields with that ETag. Set companyId to null to detach the current company. A customFields object is a typed merge patch; a null entry removes that value.

export PERSON_ETAG='"v1.ZXhhbXBsZS1wZXJzb24"'

curl --request PATCH --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/people/731" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "If-Match: $PERSON_ETAG" \
  --data '{
    "title": "VP of Operations",
    "lifecycleStage": "CUSTOMER",
    "customFields": {
      "preferred_language": "en",
      "former_region": null
    }
  }'

Replace the saved ETag with the value returned by the update.

Archive and restore

Archive a person with the current ETag and a unique idempotency key:

export PERSON_ARCHIVE_KEY="01J5C4Q9D8F2R6N3M7K0W1V5TY"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/people/731/archive" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Idempotency-Key: $PERSON_ARCHIVE_KEY" \
  --header "If-Match: $PERSON_ETAG"

Restore the same ID with the archive response’s ETag and a new key:

export ARCHIVED_PERSON_ETAG='"v1.ZXhhbXBsZS1hcmNoaXZlZA"'
export PERSON_RESTORE_KEY="01J5C4Z0M6T3Q8N2D7K1R5V9WX"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/people/731/restore" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Idempotency-Key: $PERSON_RESTORE_KEY" \
  --header "If-Match: $ARCHIVED_PERSON_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 people

Create a person

Apply a partial update

Archive and restore

​Prerequisites

​List people

​Create a person

​Apply a partial update

​Archive and restore

Prerequisites

List people

Create a person

Apply a partial update

Archive and restore