> ## 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.

# Create a person

> Create one person and optionally link an active company in the same workspace. Metadata and custom fields additionally require Work access.



## OpenAPI

````yaml /openapi/public-v1.json post /api/v1/workspaces/{workspaceSlug}/people
openapi: 3.1.0
info:
  description: Stable external API for relationship lookup and meeting intelligence.
  title: Floral Public API
  version: 1.0.0
servers:
  - description: Production
    url: https://app.floral.so
security: []
tags:
  - description: Search across active companies and people.
    name: Search
  - description: Create, list, inspect, update, archive, and restore companies.
    name: Companies
  - description: Create, list, inspect, update, archive, and restore people.
    name: People
  - description: Read active public custom-field definitions.
    name: Custom fields
  - description: Search normalized Danish company-register facts.
    name: Company registry
  - description: Generate, list, and inspect meeting briefings.
    name: Briefings
  - description: List, inspect, annotate, and approve meeting summaries.
    name: Summaries
paths:
  /api/v1/workspaces/{workspaceSlug}/people:
    post:
      tags:
        - People
      summary: Create a person
      description: >-
        Create one person and optionally link an active company in the same
        workspace. Metadata and custom fields additionally require Work access.
      operationId: createPersonV1
      parameters:
        - description: Slug of the workspace pinned to the credential.
          example: acme-nordic
          in: path
          name: workspaceSlug
          required: true
          schema:
            maxLength: 100
            minLength: 1
            pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
            type: string
        - description: >-
            Optional caller-generated correlation ID. Floral returns the
            effective value in X-Request-ID.
          example: 550e8400-e29b-41d4-a716-446655440000
          in: header
          name: X-Request-ID
          required: false
          schema:
            maxLength: 128
            minLength: 1
            type: string
        - description: >-
            Required idempotency key. Exact retries of the same canonical
            request replay the original status, body, ETag, Location, and
            request ID for 24 hours.
          example: createPersonV1-20260816-001
          in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
      requestBody:
        content:
          application/json:
            example:
              companyId: 42
              department: Operations
              email: ada@acme-nordic.example
              lifecycleStage: PROSPECT
              name: Ada Jensen
              title: Operations director
            schema:
              $ref: '#/components/schemas/PersonCreateRequest'
        description: >-
          Stable public profile fields. Owner, address, taxonomy, import,
          enrichment, and relationship-note controls are not accepted. Maximum
          65536 bytes.
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                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
              schema:
                $ref: '#/components/schemas/PersonDetailResponse'
          description: Person created
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
            ETag:
              description: Opaque version for a subsequent If-Match.
              example: >-
                "v1.eyJpZCI6ODQsInJlc291cmNlIjoicGVyc29uIiwidmVyc2lvbiI6IjIwMjYtMDgtMTVUMDk6MzA6MDAuMDAwWiJ9"
              schema:
                pattern: ^"(?:[^"\\]|\\.)*"$
                type: string
            Location:
              description: Canonical path of the created resource.
              example: /api/v1/workspaces/acme-nordic/people/84
              schema:
                format: uri-reference
                type: string
        '400':
          content:
            application/json:
              example:
                error:
                  code: INVALID_INPUT
                  message: The request contains invalid values.
                  requestId: 550e8400-e29b-41d4-a716-446655440000
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorResponse'
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - INVALID_INPUT
                        type: string
                    required:
                      - code
                    type: object
                type: object
          description: 'Stable errors: INVALID_INPUT'
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
        '401':
          content:
            application/json:
              example:
                error:
                  code: UNAUTHENTICATED
                  message: A valid bearer credential is required.
                  requestId: 550e8400-e29b-41d4-a716-446655440000
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorResponse'
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - UNAUTHENTICATED
                        type: string
                    required:
                      - code
                    type: object
                type: object
          description: 'Stable errors: UNAUTHENTICATED'
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
            WWW-Authenticate:
              description: Bearer authentication challenge.
              example: Bearer realm="floral-api"
              schema:
                type: string
        '403':
          content:
            application/json:
              example:
                error:
                  code: FORBIDDEN
                  message: The credential does not grant this operation.
                  requestId: 550e8400-e29b-41d4-a716-446655440000
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorResponse'
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - FORBIDDEN
                        type: string
                    required:
                      - code
                    type: object
                type: object
          description: 'Stable errors: FORBIDDEN'
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
        '404':
          content:
            application/json:
              example:
                error:
                  code: NOT_FOUND
                  message: The resource was not found.
                  requestId: 550e8400-e29b-41d4-a716-446655440000
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorResponse'
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - NOT_FOUND
                          - FEATURE_DISABLED
                        type: string
                    required:
                      - code
                    type: object
                type: object
          description: 'Stable errors: NOT_FOUND, FEATURE_DISABLED'
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
        '409':
          content:
            application/json:
              example:
                error:
                  code: CONFLICT
                  message: >-
                    The requested change conflicts with the current resource
                    state.
                  requestId: 550e8400-e29b-41d4-a716-446655440000
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorResponse'
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - CONFLICT
                          - IDEMPOTENCY_CONFLICT
                        type: string
                    required:
                      - code
                    type: object
                type: object
          description: 'Stable errors: CONFLICT, IDEMPOTENCY_CONFLICT'
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
        '429':
          content:
            application/json:
              example:
                error:
                  code: RATE_LIMITED
                  message: Too many requests. Retry shortly.
                  requestId: 550e8400-e29b-41d4-a716-446655440000
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorResponse'
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - RATE_LIMITED
                        type: string
                    required:
                      - code
                    type: object
                type: object
          description: 'Stable errors: RATE_LIMITED'
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
            Retry-After:
              description: Seconds until the current limit resets.
              schema:
                minimum: 1
                type: integer
        '500':
          content:
            application/json:
              example:
                error:
                  code: INTERNAL_ERROR
                  message: An unexpected error occurred.
                  requestId: 550e8400-e29b-41d4-a716-446655440000
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorResponse'
                properties:
                  error:
                    properties:
                      code:
                        enum:
                          - INTERNAL_ERROR
                        type: string
                    required:
                      - code
                    type: object
                type: object
          description: 'Stable errors: INTERNAL_ERROR'
          headers:
            X-Content-Type-Options:
              description: Always nosniff for JSON API responses.
              schema:
                const: nosniff
                type: string
            X-RateLimit-Limit:
              description: Maximum requests in the current rate-limit window.
              schema:
                minimum: 1
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                minimum: 0
                type: integer
            X-Request-ID:
              description: Stable request or idempotent replay correlation ID.
              schema:
                minLength: 1
                type: string
      security:
        - bearerAuth: []
      x-codeSamples:
        - label: cURL
          lang: Shell
          source: |-
            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"
            }'
components:
  schemas:
    PersonCreateRequest:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        companyId:
          type: integer
          exclusiveMinimum: 0
          maximum: 2147483647
        customFields:
          maxProperties: 50
          type: object
          propertyNames:
            type: string
            pattern: ^[a-z][a-z0-9_]{0,62}$
          additionalProperties:
            anyOf:
              - anyOf:
                  - type: string
                    maxLength: 5000
                  - type: number
                  - type: boolean
                  - maxItems: 50
                    type: array
                    items:
                      type: string
                      maxLength: 255
              - type: 'null'
        department:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
        description:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 5000
            - type: 'null'
        email:
          type: string
          maxLength: 320
          format: email
          pattern: >-
            ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
        lifecycleStage:
          anyOf:
            - type: string
              enum:
                - LEAD
                - PROSPECT
                - CUSTOMER
                - CHURNED
            - type: 'null'
        linkedinUrl:
          anyOf:
            - type: string
              maxLength: 255
              format: uri
            - type: 'null'
        metadata:
          maxProperties: 50
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 40
          additionalProperties:
            type: string
            maxLength: 500
        mobile:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 32
            - type: 'null'
        name:
          type: string
          minLength: 1
          maxLength: 255
        phone:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 32
            - type: 'null'
        title:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
      required:
        - email
        - name
      additionalProperties: false
    PersonDetailResponse:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        person:
          type: object
          properties:
            archivedAt:
              anyOf:
                - type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                - type: 'null'
            company:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: integer
                      exclusiveMinimum: 0
                      maximum: 9007199254740991
                    name:
                      type: string
                  required:
                    - id
                    - name
                  additionalProperties: false
                - type: 'null'
            customFields:
              maxProperties: 50
              type: object
              propertyNames:
                type: string
                pattern: ^[a-z][a-z0-9_]{0,62}$
              additionalProperties:
                anyOf:
                  - type: string
                    maxLength: 5000
                  - type: number
                  - type: boolean
                  - maxItems: 50
                    type: array
                    items:
                      type: string
                      maxLength: 255
            department:
              anyOf:
                - type: string
                - type: 'null'
            description:
              anyOf:
                - type: string
                - type: 'null'
            email:
              type: string
            id:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            lastActivityAt:
              anyOf:
                - type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                - type: 'null'
            lifecycleStage:
              anyOf:
                - type: string
                  enum:
                    - LEAD
                    - PROSPECT
                    - CUSTOMER
                    - CHURNED
                - type: 'null'
            linkedinUrl:
              anyOf:
                - type: string
                - type: 'null'
            metadata:
              maxProperties: 50
              type: object
              propertyNames:
                type: string
                minLength: 1
                maxLength: 40
              additionalProperties:
                type: string
                maxLength: 500
            mobile:
              anyOf:
                - type: string
                - type: 'null'
            name:
              type: string
            ownerUserIds:
              maxItems: 50
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 255
            phone:
              anyOf:
                - type: string
                - type: 'null'
            title:
              anyOf:
                - type: string
                - type: 'null'
            updatedAt:
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            version:
              type: string
              minLength: 1
              maxLength: 512
          required:
            - archivedAt
            - company
            - customFields
            - department
            - description
            - email
            - id
            - lastActivityAt
            - lifecycleStage
            - linkedinUrl
            - metadata
            - mobile
            - name
            - ownerUserIds
            - phone
            - title
            - updatedAt
            - version
          additionalProperties: false
      required:
        - person
      additionalProperties: false
    ApiErrorResponse:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              enum:
                - CONFLICT
                - FEATURE_DISABLED
                - FORBIDDEN
                - IDEMPOTENCY_CONFLICT
                - INTERNAL_ERROR
                - INVALID_INPUT
                - INVALID_STATE
                - NOT_FOUND
                - PRECONDITION_REQUIRED
                - RATE_LIMITED
                - UNAUTHENTICATED
                - VERSION_CONFLICT
              type: string
            message:
              minLength: 1
              type: string
            requestId:
              maxLength: 128
              minLength: 1
              type: string
          required:
            - code
            - message
            - requestId
          type: object
      required:
        - error
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: Floral PAT
      description: Authenticate with a workspace-pinned Floral personal access token.
      scheme: bearer
      type: http

````