> ## Documentation Index > Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Person > Create a new person record with optional emails, phone numbers, company relationships, and social links. If a person with the same name and primary email already exists, returns the existing person instead of creating a duplicate. ## OpenAPI ````yaml POST /v1/people openapi: 3.1.0 info: title: Well Document API version: 1.0.0 description: API for uploading and managing financial documents in the Well platform servers: - url: https://api.wellapp.ai security: [] paths: /v1/people: post: summary: Create a new person description: >- Create a new person record with optional emails, phone numbers, company relationships, and social links. If a person with the same name and primary email already exists, returns the existing person instead of creating a duplicate. parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Person' examples: complete_person_request: summary: Create person with all optional fields description: >- Example showing how to create a person with emails, phone numbers, company relationships, and social links. Note: 'label' defaults to 'work' for both emails and phones if not specified. 'is_primary' defaults to 'false', but becomes 'true' automatically if no other email/phone is marked as primary. Only one email and one phone can be marked as primary per person. value: type: people attributes: first_name: Sophie last_name: Martin relationships: emails: data: - type: email id: temp-email-1 - type: email id: temp-email-2 phones: data: - type: phone id: temp-phone-1 social_links: data: - type: social_link id: temp-social-1 companies: data: - type: company id: temp-company-1 meta: relationship_type: employee included: - type: email id: temp-email-1 attributes: value: sophie.martin@example.com label: work is_primary: true - type: email id: temp-email-2 attributes: value: sophie@personal.com label: personal is_primary: false - type: phone id: temp-phone-1 attributes: e164_number: '+33123456789' label: mobile is_primary: true - type: social_link id: temp-social-1 attributes: url: https://linkedin.com/in/sophie-martin platform: linkedin - type: company id: temp-company-1 attributes: name: Example Corp description: Tech company workspace_id: 550e8400-e29b-41d4-a716-446655440001 responses: '201': description: Person created successfully content: application/json: schema: $ref: '#/components/schemas/PeopleResponse' examples: complete_person: summary: Person with all optional fields value: data: type: people id: 3e29b483-e8a0-4871-906e-5ddfc9b7ed6b attributes: first_name: Sophie last_name: Martin full_name: Sophie Martin created_at: '2025-09-15T14:09:40.942Z' relationships: emails: data: - type: email id: 471604cd-8de8-4576-97f7-7c4656d7b6b4 - type: email id: 9cbefca9-32bb-48d0-aeee-c07fa84ad0b8 phones: data: - type: phone id: 11175a7a-df1a-4f9d-bb2a-9d6023f15bf8 - type: phone id: ae72063c-861f-489e-973d-83e31cef24f8 social_links: data: - type: social_link id: c401d53e-ca36-47e7-a861-83443599eb4c companies: data: - type: company id: b6c22e98-c8d0-485e-9d3d-caa2bbaff77a included: - type: email id: 471604cd-8de8-4576-97f7-7c4656d7b6b4 attributes: value: sophie.perso@gmail.com label: personal is_primary: false created_at: '2025-09-15T14:09:40.963Z' - type: email id: 9cbefca9-32bb-48d0-aeee-c07fa84ad0b8 attributes: value: sophie.martin@company.com label: work is_primary: true created_at: '2025-09-15T14:09:40.953Z' - type: phone id: 11175a7a-df1a-4f9d-bb2a-9d6023f15bf8 attributes: e164_number: '+33646020535' country_code: 33 national_number: '646020535' is_primary: true is_verify: false label: mobile created_at: '2025-09-15T14:09:40.973Z' - type: phone id: ae72063c-861f-489e-973d-83e31cef24f8 attributes: e164_number: '+33142356789' country_code: 33 national_number: '142356789' is_primary: false is_verify: false label: work created_at: '2025-09-15T14:09:40.981Z' - type: social_link id: c401d53e-ca36-47e7-a861-83443599eb4c attributes: url: https://linkedin.com/in/sophie-martin platform: linkedin created_at: '2025-09-15T14:09:40.990Z' - type: company id: b6c22e98-c8d0-485e-9d3d-caa2bbaff77a attributes: name: TechCorp Solutions description: Leading technology consulting company workspace_id: 550e8400-e29b-41d4-a716-446655440000 created_at: '2025-09-15T14:09:40.995Z' '400': description: Bad request - validation error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Unauthorized - invalid API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' components: parameters: AuthorizationHeader: name: Authorization in: header required: true schema: type: string description: Bearer token for authentication schemas: Person: type: object description: >- Central entity representing individuals with comprehensive contact information properties: id: type: string format: uuid description: Unique person identifier (UUID v4) example: 550e8400-e29b-41d4-a716-446655440000 type: type: string const: people description: JSON:API resource type identifier attributes: $ref: '#/components/schemas/PersonAttributes' relationships: $ref: '#/components/schemas/PersonRelationships' included: $ref: '#/components/schemas/PeopleIncludedPost' required: - id - type - attributes PeopleResponse: type: object properties: data: type: object properties: type: type: string example: people id: type: string format: uuid attributes: type: object properties: first_name: type: string description: Person's first name example: John last_name: type: string description: Person's last name example: Doe full_name: type: string description: Person's full name (first + last) example: John Doe created_at: type: string format: date-time description: Timestamp when the person was created example: '2024-01-15T10:30:00Z' updated_at: type: string format: date-time description: Timestamp when the person was last updated example: '2024-01-20T14:45:00Z' relationships: $ref: '#/components/schemas/PeopleResponseRelationships' included: $ref: '#/components/schemas/PeopleResponseIncluded' BadRequestError: type: object properties: code: type: string example: SCHEMA_VALIDATION_ERROR description: Error code identifier status: type: integer example: 400 description: HTTP status code title: type: string example: Validation Error description: Error title message: type: string example: The request is invalid description: Detailed error message details: type: array items: type: object properties: instancePath: type: string description: Path to the invalid field in the request schemaPath: type: string description: Path to the validation rule in the schema keyword: type: string description: Validation keyword that failed params: type: object description: Parameters related to the validation failure message: type: string description: Human-readable validation error message description: Array of detailed validation errors meta: type: object properties: log_id: type: string format: uuid example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b description: Unique identifier for tracking this error in logs required: - log_id required: - code - status - title - message - meta UnauthorizedError: type: object properties: code: type: string example: UNAUTHORIZED description: Error code identifier status: type: integer example: 401 description: HTTP status code title: type: string example: Unauthorized description: Error title message: type: string example: You are not authorized to access this resource description: Detailed error message meta: type: object properties: log_id: type: string format: uuid example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b description: Unique identifier for tracking this error in logs required: - log_id required: - code - status - title - message - meta PersonAttributes: type: object description: Person attribute data properties: first_name: type: string description: Person's first name example: Marie minLength: 1 maxLength: 100 last_name: type: string description: Person's last name example: Dubois minLength: 1 maxLength: 100 full_name: type: string description: Auto-computed full name (first + last) example: Marie Dubois readOnly: true created_at: type: string format: date-time description: Person creation timestamp (UTC) example: '2024-01-15T10:30:00Z' readOnly: true updated_at: type: - string - 'null' format: date-time description: Last modification timestamp (UTC) example: '2024-01-16T14:20:00Z' readOnly: true required: - first_name - last_name - created_at PersonRelationships: type: object description: Person relationship references properties: emails: type: object description: Email addresses associated with this person properties: data: type: array items: type: object properties: type: type: string const: email id: type: string description: >- UUID of an existing email or temp-id that references an email defined in the included array required: - type - id phones: type: object description: Phone numbers associated with this person properties: data: type: array items: type: object properties: type: type: string const: phone id: type: string description: >- UUID of an existing phone or temp-id that references a phone defined in the included array required: - type - id web_links: type: object description: Social media profiles associated with this person properties: data: type: array items: type: object properties: type: type: string const: social_link id: type: string description: >- UUID of an existing web link or temp-id that references a web link defined in the included array required: - type - id companies: type: object description: Companies associated with this person properties: data: type: array items: type: object properties: type: type: string const: company id: type: string description: >- UUID of an existing company or temp-id that references a company defined in the included array required: - type - id workspaces: type: object description: Workspaces this person belongs to properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string description: >- UUID of an existing workspace or temp-id that references a workspace defined in the included array required: - type - id documents: type: object description: Documents associated with this person properties: data: type: array items: type: object properties: type: type: string const: document id: type: string description: >- UUID of an existing document or temp-id that references a document defined in the included array required: - type - id memberships: type: object description: Workspace memberships with roles and permissions properties: data: type: array items: type: object properties: type: type: string const: membership id: type: string description: >- UUID of an existing membership or temp-id that references a membership defined in the included array required: - type - id medias: type: object description: medias of the person properties: data: type: array items: type: object properties: type: type: string const: media id: type: string description: >- UUID of an existing media or temp-id that references a media defined in the included array required: - type - id PeopleIncludedPost: type: object properties: emails: type: object properties: data: type: array items: type: object properties: type: type: string const: email id: type: string attributes: $ref: '#/components/schemas/EmailAttributes' required: - type - id - attributes phones: type: object properties: data: type: array items: type: object properties: type: type: string const: phone id: type: string description: >- temp-id that references a phones defined in the included array attributes: $ref: '#/components/schemas/PhoneCreateAttributes' required: - type - id - attributes web_links: type: object description: Web links associated with this company properties: data: type: array items: type: object properties: type: type: string const: web_link id: type: string description: >- temp-id that references a web links defined in the included array attributes: $ref: '#/components/schemas/WebLinkCreateAttributes' required: - type - id - attributes companies: type: object properties: data: type: array items: type: object properties: type: type: string const: company id: type: string description: >- temp-id that references a companies defined in the included array attributes: $ref: '#/components/schemas/CompanyCreateAttributes' required: - type - id - attributes workspaces: type: object description: Workspaces associated with this company properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string description: >- temp-id that references a workspaces defined in the included array attributes: $ref: '#/components/schemas/WorkspaceCreateAttributes' required: - type - id - attributes documents: type: object description: Documents associated with this company properties: data: type: array items: type: object properties: type: type: string const: document id: type: string description: >- temp-id that references a documents defined in the included array attributes: $ref: '#/components/schemas/DocumentCreateAttributes' memberships: type: object description: membership associated with this person properties: data: type: array items: type: object properties: type: type: string const: membership id: type: string description: >- temp-id that references a memberships defined in the included array attributes: $ref: '#/components/schemas/MembershipCreateAttributes' medias: type: object description: Media associated with this person properties: data: type: array items: type: object properties: type: type: string const: membership id: type: string description: >- temp-id that references a medias defined in the included array attributes: $ref: '#/components/schemas/MediaCreateAttributes' PeopleResponseRelationships: type: object properties: emails: type: object properties: data: type: array items: type: object properties: type: type: string const: email id: type: string format: uuid phones: type: object properties: data: type: array items: type: object properties: type: type: string const: phone id: type: string format: uuid web_links: type: object properties: data: type: array items: type: object properties: type: type: string const: web_link id: type: string format: uuid companies: type: object properties: data: type: array items: type: object properties: type: type: string const: company id: type: string format: uuid meta: type: object properties: relationship_type: type: string enum: - contact - employee - owner - other description: Relationship type of the person in the company example: employee required: - relationship_type required: - type - id - meta medias: type: object properties: data: type: array items: type: object properties: type: type: string const: media id: type: string format: uuid description: UUID of the media file example: 550e8400-e29b-41d4-a716-446655440002 required: - type - id - meta workspaces: type: object properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string format: uuid description: UUID of the workspace example: 632860b5-48b7-49eb-9dd1-8bddc634f387 memberships: type: object properties: data: type: array items: type: object properties: type: type: string const: memberships id: type: string format: uuid description: UUID of the memberships example: 632860b5-48b7-49eb-9dd1-8bddc634f387 documents: type: object properties: data: type: array items: type: object properties: type: type: string const: document id: type: string format: uuid description: UUID of the document example: 550e8400-e29b-41d4-a716-446655440009 PeopleResponseIncluded: type: object properties: emails: type: array items: type: object properties: type: type: string const: email description: Type of the included email resource id: type: string format: uuid description: UUID of the email attributes: $ref: '#/components/schemas/EmailAttributes' additionalProperties: false phones: type: array items: type: object properties: type: type: string const: phone description: Type of the included phone resource id: type: string format: uuid description: UUID of the phone attributes: $ref: '#/components/schemas/PhoneAttributes' additionalProperties: false web_links: type: array items: type: object properties: type: type: string const: social_links description: Type of the included social link resource id: type: string format: uuid description: UUID of the social link attributes: $ref: '#/components/schemas/WebLinkAttributes' additionalProperties: false companies: type: array items: type: object properties: type: type: string const: company description: Type of the included company resource id: type: string format: uuid description: UUID of the company attributes: $ref: '#/components/schemas/CompanyAttributes' additionalProperties: false workspaces: type: object description: Workspaces associated with this company properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string format: uuid description: UUID of the workspace attributes: $ref: '#/components/schemas/WorkspaceCreateAttributes' medias: type: object description: Media files associated with this person properties: data: type: array items: type: object properties: type: type: string const: media id: type: string format: uuid description: UUID of the media attributes: $ref: '#/components/schemas/MediaAttributes' memberships: type: object description: membership to a workspace properties: data: type: array items: type: object properties: type: type: string const: media id: type: string format: uuid description: UUID of the media attributes: $ref: '#/components/schemas/MembershipAttributes' documents: type: object description: Documents associated with this company properties: data: type: array items: type: object properties: type: type: string const: document id: type: string format: uuid description: UUID of the document attributes: $ref: '#/components/schemas/DocumentAttributes' description: Included resources grouped by type EmailAttributes: type: object properties: value: type: string format: email description: Email address value example: sarah.wilson@techcorp.com is_primary: type: boolean default: true description: >- Whether this is the primary email address. Defaults to 'false', unless no other email is marked as primary (in which case it becomes 'true'). Only one email can be marked as primary per person/company. example: true label: type: string enum: - work - personal - other - ... description: >- Email label type. See [all available labels](/enums/label) for complete list. default: work example: work created_at: type: string format: date-time description: Timestamp when the email was created example: '2023-06-15T10:30:00Z' updated_at: type: string format: date-time description: Timestamp when the email was last updated example: '2023-06-15T10:30:00Z' PhoneCreateAttributes: type: object properties: number: type: string pattern: ^\+[1-9]\d{1,14}$ description: Phone number in E164 format example: '+14155552671' is_primary: type: boolean description: Whether this is the primary phone number default: true label: type: string enum: - work - personal - other - ... description: >- Phone label type. See [all available labels](/enums/label) for complete list. default: work required: - number WebLinkCreateAttributes: type: object properties: platform: type: string enum: - website - linkedin - x - github description: Web platform type url: type: string minLength: 1 maxLength: 500 description: Full profile URL required: - url CompanyCreateAttributes: type: object properties: locale: type: string pattern: ^[a-z]{2}(-[A-Z]{2})?$ description: >- Language settings.That’s the locale for the business relationship. Emails or documents can be used to identify the locale. Default EN. example: en-US domain_name_primary_link_url: type: string format: uri description: >- The domain url from the website or email address of the company. Used as unique identifier in some cases. example: https://www.techcorp.com tax_id: type: object properties: value: type: string description: Tax ID issued by local or national tax authority. example: DE123456789 type: type: string description: >- Type of tax ID, useful for applying formatting and validation rules.[all tax id types](/enums/tax-id) See all available labels for complete list. example: - VAT - TVA - IVA - ... registration: oneOf: - type: object properties: trade_name: type: string description: >- Commercial or branding name (if different from registered name). example: TechSol registered_name: type: string description: Legal company name example: TechCorp AI Solutions LLC required: - registered_name - type: object properties: trade_name: type: string description: >- Commercial or branding name (if different from registered name). example: TechSol registered_name: type: string description: Legal company name example: TechCorp AI Solutions LLC required: - trade_name registration_number: type: object properties: business_type: type: string enum: - Inc - Corp - LLC - GmbH - Ltd - SA - SAS description: >- Legal entity structure type. See [all business entity types](/enums/business-entity-by-country) for complete list. example: GmbH value: type: string description: Official company registration number. example: HRB 123456 registry_name: type: string description: >- Name of the official registration body. See [all available registry name](/enums/registry-name) for complete list. example: Handelsregister Berlin registry_country: type: string pattern: ^[A-Z]{2}$ description: |- Country of the registry authority. Must be valid ISO country code example: DE, FR, US, etc. description: type: string minLength: 1 maxLength: 500 description: Company description explaining business purpose in max 2 sentences. example: An innovative technology company focused on AI solutions required: - registration WorkspaceCreateAttributes: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Workspace name description: type: string maxLength: 1000 description: Workspace description avatar_color: type: string pattern: ^#[A-Fa-f0-9]{6}$ description: 'Avatar color in hexadecimal format (e.g., #FF5733)' external_workspace_id: type: string minLength: 1 maxLength: 255 description: External workspace identifier required: - name DocumentCreateAttributes: type: object properties: file_name: type: string status: type: string file_type: type: string size_bytes: type: integer MembershipCreateAttributes: type: object properties: firebase_id: type: string role: type: string enum: - admin - member - owner - ... description: >- User role in the workspace. See [all available roles](/enums/role) for complete list. required: - role MediaCreateAttributes: type: object properties: media_type: type: string enum: - avatar - logo - banner description: Type of media (avatar, logo, banner) is_primary: type: boolean default: true description: 'Marks preferred media. Default: true' PhoneAttributes: type: object properties: number: type: string pattern: ^\+[1-9]\d{1,14}$ description: Full international phone number in E164 format example: '+14155552671' label: type: string enum: - work - personal - other - ... description: >- Phone label type. See [all available labels](/enums/label) for complete list. is_primary: type: boolean description: Whether this is the primary phone number created_at: type: string format: date-time description: Timestamp when the phone was created WebLinkAttributes: type: object properties: platform: type: string enum: - website - linkedin - x - github description: Web platform type url: type: string description: Full profile URL created_at: type: string format: date-time description: Date and time when the web link was created updated_at: type: string format: date-time description: Date and time when the web link was updated CompanyAttributes: type: object properties: description: type: string domain_name_primary_link_url: type: string format: url maxLength: 500 description: >- The domain url from the website or email address of the company. Used as unique identifier in some cases. examples: - acme.com tax_id: type: object properties: value: description: Tax ID issued by local or national tax authority. type: string examples: - DE123456789 type: description: >- Type of tax ID, useful for applying formatting and validation rules. type: string examples: - VAT registration: type: object properties: trade_name: description: Commercial or branding name (if different from registered name). type: string examples: - TechSol registered_name: description: Legal company name. type: string minLength: 1 maxLength: 100 examples: - Red Hat Inc. registration_number: type: object properties: business_type: description: Legal entity structure type. type: string examples: - GmbH value: description: Official company registration number. type: string examples: - HRB 123456 registry_name: description: Name of the official registration body. type: string examples: - Handelsregister Berlin registry_country: description: Country of the registry authority. (string (ISO 3166-1 alpha-2)) type: string examples: - DE workspace_id: type: string format: uuid description: UUID of the workspace associated with this company created_at: type: string format: date-time updated_at: type: string format: date-time MediaAttributes: type: object properties: media_type: type: string enum: - avatar - logo - banner url: type: string format: uri description: URL to the media file is_primary: type: boolean description: Whether this is the primary media processed_at: type: - string format: date-time description: Timestamp when media processing completed uploaded_at: type: string format: date-time MembershipAttributes: type: object properties: role: type: string firebase_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time DocumentAttributes: type: object properties: file_name: type: string status: type: string uploaded_at: type: string format: date-time processed_at: type: string format: date-time file_type: type: string size_bytes: type: integer ````