> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/reference/people-events/create-person.md).
# Create Person
## Create a person
> Creates a new person record in your organization. All fields are optional — you can create a person with just an \`external\_id\`, just an \`email\`, or any combination of fields.\
> \
> If \`attribute\_values\` contains relationship attributes (Person-type or Stack-type), those values are automatically normalized to explicit identifier format. For example, a plain string \`"user-002"\` in a Person-type attribute becomes \`{"external\_id": "user-002"}\`.\
> \
> Referenced entities that don't yet exist are \*\*auto-created\*\* so that relationship links are always valid. For enriched references that include additional fields (e.g. \`{"external\_id": "user-002", "first\_name": "John"}\`), those fields are merged onto the newly created or existing entity.\
> \
> Consent fields (\`email\_consent\`, \`sms\_consent\`, \`push\_notification\_consent\`) default to \`false\` if not provided.\
> \
> {% hint style="info" %}\
> All string fields are automatically trimmed of leading and trailing whitespace before processing.\
> {% endhint %}
```json
{"openapi":"3.0.3","info":{"title":"Listener API","version":"1.0.0"},"tags":[{"name":"create-person"}],"servers":[{"url":"https://{domain}/v1","variables":{"domain":{"default":"your-domain","description":"Your deployment domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token with the required scope for the endpoint. Pass via the `Authorization: Bearer ` header.\n"}},"schemas":{"CreatePersonRequest":{"type":"object","description":"Request body for creating a new person. All fields are optional. Consent fields default to `false` if not provided.\n","properties":{"external_id":{"type":"string","description":"External identifier for the person. Must be unique within your organization."},"first_name":{"type":"string","description":"First name."},"last_name":{"type":"string","description":"Last name."},"email":{"type":"string","format":"email","description":"Email address."},"mobile_prefix":{"type":"string","description":"Mobile phone country prefix (e.g. `+1`, `+44`)."},"mobile_number":{"type":"string","description":"Mobile phone number (without country prefix)."},"date_of_birth":{"type":"string","description":"Date of birth."},"language":{"type":"string","description":"Preferred language code."},"email_consent":{"type":"boolean","description":"Email channel consent. Defaults to `false`. This is a summary of the person's consent answers on the email channel: `false` refuses every consent purpose on the channel, `true` grants only the purpose marked as that channel's default and leaves the other purposes on their own defaults.\n","default":false},"sms_consent":{"type":"boolean","description":"SMS channel consent. Defaults to `false`. Behaves like `email_consent` on the SMS channel.\n","default":false},"push_notification_consent":{"type":"boolean","description":"Push notification consent. Defaults to `false`. A plain flag — consent purposes only apply to the `email` and `sms` channels.\n","default":false},"attribute_values":{"type":"object","description":"Custom attribute key-value pairs. Keys must match attribute keys configured on your organization's person attributes. Relationship attributes (Person-type and Stack-type) accept plain values which are automatically normalized to `{\"external_id\": \"...\"}` format.\n","additionalProperties":true}}},"SuccessResponse":{"type":"object","description":"Standard success response envelope.","properties":{"status":{"type":"string","enum":["Success"]},"data":{"type":"boolean"}}},"ErrorResponse":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"string","description":"Machine-readable error type. Use this for programmatic error handling.\n","enum":["operation_failed","failed_binding_json","invalid_json","invalid_parameter","not_found","duplicate_entry","rate_limit_exceeded"]},"errorstack":{"type":"object","nullable":true,"description":"Detailed error stack (only present for server errors)."}}}}},"paths":{"/people":{"post":{"summary":"Create a person","operationId":"createPerson","tags":["create-person"],"description":"Creates a new person record in your organization. All fields are optional — you can create a person with just an `external_id`, just an `email`, or any combination of fields.\n\nIf `attribute_values` contains relationship attributes (Person-type or Stack-type), those values are automatically normalized to explicit identifier format. For example, a plain string `\"user-002\"` in a Person-type attribute becomes `{\"external_id\": \"user-002\"}`.\n\nReferenced entities that don't yet exist are **auto-created** so that relationship links are always valid. For enriched references that include additional fields (e.g. `{\"external_id\": \"user-002\", \"first_name\": \"John\"}`), those fields are merged onto the newly created or existing entity.\n\nConsent fields (`email_consent`, `sms_consent`, `push_notification_consent`) default to `false` if not provided.\n\n{% hint style=\"info\" %}\nAll string fields are automatically trimmed of leading and trailing whitespace before processing.\n{% endhint %}\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonRequest"}}}},"responses":{"201":{"description":"Person created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid request body or validation failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error during person creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```