# flow2act · Create a person

Create a directory profile. Optional links default to null.

identityId explicitly links an existing active flow2act member, never automatically by email. Administrators list eligible members with GET /v1/organization/members.

## POST /v1/organization/people

Authentication: restricted integration key (scope: organization:write) or flow2act sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- displayName (string, required): min length 1 · max length 120
- email (string, optional): email · max length 254
- jobTitle (string, optional): max length 120 · default ""
- externalId (string, optional): min length 1 · max length 120 · default null
- unitId (string, optional): uuid · default null
- managerId (string, optional): uuid · default null
- hrPersonId (string, optional): uuid · default null
- identityId (string, optional): uuid · default null
- active (boolean, optional): default true

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flow2act.com/v1/organization/people" \
  -H "authorization: Bearer $FLOW2ACT_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-create-person-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "displayName": "Alex Example",
  "email": null,
  "jobTitle": "Engineer",
  "externalId": "employee-example",
  "unitId": null,
  "managerId": null,
  "hrPersonId": null,
  "identityId": null,
  "active": true
}'
```

## Response excerpt

```json
{
  "people": [
    {
      "displayName": "Alex Example",
      "email": null,
      "jobTitle": "Engineer",
      "externalId": "employee-example",
      "unitId": null,
      "managerId": null,
      "hrPersonId": null,
      "identityId": null,
      "active": true,
      "id": "10000000-0000-4000-8000-000000000006",
      "revision": 1
    }
  ]
}
```

Source: /docs/create-person
Full schemas: /docs/openapi.json