Create a person

cURL

curl --request POST \
  --url 'https://app.floral.so/api/v1/workspaces/acme-nordic/people' \
  --header 'Authorization: Bearer $FLORAL_TOKEN' \
  --header 'Idempotency-Key: createPersonV1-20260816-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "companyId": 42,
  "department": "Operations",
  "email": "ada@acme-nordic.example",
  "lifecycleStage": "PROSPECT",
  "name": "Ada Jensen",
  "title": "Operations director"
}'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({email: 'ada@acme-nordic.example', name: 'Ada Jensen'})
};

fetch('https://app.floral.so/api/v1/workspaces/{workspaceSlug}/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "person": {
    "archivedAt": null,
    "company": {
      "id": 42,
      "name": "Acme Nordic"
    },
    "customFields": {
      "preferred_language": "da"
    },
    "department": "Operations",
    "description": "Leads operational planning across the Nordic region.",
    "email": "ada@acme-nordic.example",
    "id": 84,
    "lastActivityAt": "2026-08-15T09:30:00.000Z",
    "lifecycleStage": "PROSPECT",
    "linkedinUrl": "https://www.linkedin.com/in/ada-jensen",
    "metadata": {
      "source": "event-registration"
    },
    "mobile": "+45 20 11 22 33",
    "name": "Ada Jensen",
    "ownerUserIds": [
      "user_01J5N9CF9QY8T4M2A7W3R6K1P0"
    ],
    "phone": "+45 33 12 34 56",
    "title": "Operations director",
    "updatedAt": "2026-08-15T09:30:00.000Z",
    "version": "v1.eyJpZCI6ODQsInJlc291cmNlIjoicGVyc29uIiwidmVyc2lvbiI6IjIwMjYtMDgtMTVUMDk6MzA6MDAuMDAwWiJ9"
  }
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The request contains invalid values.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "A valid bearer credential is required.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The credential does not grant this operation.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The resource was not found.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested change conflicts with the current resource state.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry shortly.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

POST

https://app.floral.so

api

workspaces

{workspaceSlug}

people

cURL

curl --request POST \
  --url 'https://app.floral.so/api/v1/workspaces/acme-nordic/people' \
  --header 'Authorization: Bearer $FLORAL_TOKEN' \
  --header 'Idempotency-Key: createPersonV1-20260816-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "companyId": 42,
  "department": "Operations",
  "email": "ada@acme-nordic.example",
  "lifecycleStage": "PROSPECT",
  "name": "Ada Jensen",
  "title": "Operations director"
}'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({email: 'ada@acme-nordic.example', name: 'Ada Jensen'})
};

fetch('https://app.floral.so/api/v1/workspaces/{workspaceSlug}/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "person": {
    "archivedAt": null,
    "company": {
      "id": 42,
      "name": "Acme Nordic"
    },
    "customFields": {
      "preferred_language": "da"
    },
    "department": "Operations",
    "description": "Leads operational planning across the Nordic region.",
    "email": "ada@acme-nordic.example",
    "id": 84,
    "lastActivityAt": "2026-08-15T09:30:00.000Z",
    "lifecycleStage": "PROSPECT",
    "linkedinUrl": "https://www.linkedin.com/in/ada-jensen",
    "metadata": {
      "source": "event-registration"
    },
    "mobile": "+45 20 11 22 33",
    "name": "Ada Jensen",
    "ownerUserIds": [
      "user_01J5N9CF9QY8T4M2A7W3R6K1P0"
    ],
    "phone": "+45 33 12 34 56",
    "title": "Operations director",
    "updatedAt": "2026-08-15T09:30:00.000Z",
    "version": "v1.eyJpZCI6ODQsInJlc291cmNlIjoicGVyc29uIiwidmVyc2lvbiI6IjIwMjYtMDgtMTVUMDk6MzA6MDAuMDAwWiJ9"
  }
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The request contains invalid values.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "A valid bearer credential is required.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The credential does not grant this operation.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The resource was not found.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested change conflicts with the current resource state.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry shortly.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

Authenticate with a workspace-pinned Floral personal access token.

Headers

X-Request-ID

string

Optional caller-generated correlation ID. Floral returns the effective value in X-Request-ID.

Required string length: 1 - 128

Idempotency-Key

string

required

Required idempotency key. Exact retries of the same canonical request replay the original status, body, ETag, Location, and request ID for 24 hours.

Required string length: 1 - 255

Path Parameters

workspaceSlug

string

required

Slug of the workspace pinned to the credential.

Required string length: 1 - 100

Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Body

application/json

Stable public profile fields. Owner, address, taxonomy, import, enrichment, and relationship-note controls are not accepted. Maximum 65536 bytes.

string<email>

required

Maximum string length: 320

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

name

string

required

Required string length: 1 - 255

companyId

integer

Required range: x <= 2147483647

customFields

object

Show child attributes

department

string | null

Required string length: 1 - 128

description

string | null

Required string length: 1 - 5000

lifecycleStage

enum<string> | null

Available options:

LEAD,

PROSPECT,

CUSTOMER,

CHURNED

linkedinUrl

string<uri> | null

Maximum string length: 255

metadata

object

Show child attributes

mobile

string | null

Required string length: 1 - 32

phone

string | null

Required string length: 1 - 32

title

string | null

Required string length: 1 - 128

Response

Person created

person

object

required

Show child attributes

⌘I

Search

Company registry

Companies

Custom fields

People

Briefings

Summaries

Authorizations

Headers

Path Parameters

Body

Response