> ## 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 Phone > Create a new phone number with relationships to people, companies, or workspaces ## OpenAPI ````yaml POST /v1/phones 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/phones: post: summary: Create phone description: >- Create a new phone number with relationships to people, companies, or workspaces parameters: - $ref: '#/components/parameters/AuthorizationHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PhoneCreateRequest' example: data: type: phone id: 3c90c3cc-0d44-4b50-8888-8dd25736052a attributes: country_code: 1 national_number: '4155552671' e164_number: '+14155552671' label: work is_primary: true is_verified: true created_at: '2023-11-07T05:31:56Z' updated_at: '2023-11-07T05:31:56Z' relationships: persons: data: - type: people id: people1 companies: data: - type: company id: company_tenant workspaces: data: - type: workspace id: workspace_sales - type: workspace id: 550e8400-e29b-41d4-a716-446655440000 included: - type: people id: people1 attributes: first_name: John last_name: Doe full_name: John Doe created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' - type: company id: company_tenant attributes: name: Acme Corporation description: Leading technology company locale: en domain_name_primary_link_url: acme.com created_at: '2023-12-01T09:00:00Z' updated_at: '2023-12-01T09:00:00Z' - type: workspace id: workspace_sales attributes: name: Sales Team Workspace description: Workspace for sales activities avatar_color: '#FF6B35' external_workspace_id: fygr_123 auto_extract_enabled: true created_at: '2024-01-10T08:15:00Z' updated_at: '2024-01-10T08:15:00Z' - type: workspace id: 550e8400-e29b-41d4-a716-446655440000 attributes: name: Marketing Team Workspace description: Workspace for marketing campaigns avatar_color: '#4A90E2' external_workspace_id: mkt_workspace_001 auto_extract_enabled: false created_at: '2024-01-12T14:45:00Z' updated_at: '2024-01-12T14:45:00Z' responses: '201': description: Phone created successfully content: application/json: schema: $ref: '#/components/schemas/PhoneCreateResponse' example: data: - type: phone id: 3c90c3cc-0d44-4b50-8888-8dd25736052a attributes: country_code: 1 national_number: '4155552671' e164_number: '+14155552671' label: work is_primary: true is_verified: true created_at: '2023-11-07T05:31:56Z' relationships: persons: data: - type: people id: people1 attributes: first_name: John last_name: Doe email: john.doe@example.com companies: data: - type: company id: company_tenant attributes: name: Acme Corporation description: Leading technology company website: https://acme.com workspaces: data: - type: workspace external_workspace_id: fygr_123 attributes: name: Sales Team Workspace description: Workspace for sales activities - type: workspace id: 550e8400-e29b-41d4-a716-446655440000 attributes: name: Marketing Team Workspace description: Workspace for marketing campaigns '400': description: Bad request - invalid phone data or validation error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Unauthorized - invalid API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '404': $ref: '#/components/responses/PersonNotFound' components: parameters: AuthorizationHeader: name: Authorization in: header required: true schema: type: string description: Bearer token for authentication schemas: PhoneCreateRequest: type: object properties: attributes: $ref: '#/components/schemas/PhoneCreateAttributes' relationships: $ref: '#/components/schemas/PhoneRelationships' required: - attributes - relationships PhoneCreateResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/Phone' 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 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 PhoneRelationships: $ref: '#/components/schemas/AtomicRelationshipsResponse' Phone: type: object properties: type: type: string const: phone id: type: string format: uuid description: UUID of the phone attributes: $ref: '#/components/schemas/PhoneAttributes' relationships: $ref: '#/components/schemas/AtomicRelationshipsResponse' included: $ref: '#/components/schemas/SimpleIncludedResponse' AtomicRelationshipsResponse: type: object properties: persons: $ref: '#/components/schemas/PeopleRelationResponse' companies: $ref: '#/components/schemas/CompanyRelationResponse' workspaces: $ref: '#/components/schemas/WorkspaceRelationResponse' 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 SimpleIncludedResponse: type: object properties: persons: type: object properties: data: type: array items: type: object properties: type: type: string const: people id: type: string format: uuid attributes: $ref: '#/components/schemas/PersonAttributes' companies: type: object properties: data: type: array items: type: object properties: type: type: string const: company id: type: string format: uuid attributes: $ref: '#/components/schemas/CompanyAttributes' workspaces: type: object properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string format: uuid attributes: $ref: '#/components/schemas/WorkspaceAttributes' PeopleRelationResponse: type: object properties: data: type: array items: properties: type: type: string enum: - people id: type: string format: uuid description: UUID of the people CompanyRelationResponse: type: object properties: data: type: array items: properties: type: type: string enum: - company id: type: string format: uuid description: UUID of the company WorkspaceRelationResponse: type: object properties: data: type: array items: oneOf: - properties: type: type: string enum: - workspace external_workspace_id: type: string description: External workspace identifier - properties: type: type: string enum: - workspace id: type: string format: uuid description: UUID of the workspace 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 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 WorkspaceAttributes: type: object properties: name: type: string description: Workspace name desription: type: string description: Workspace description external_workspace_id: type: string format: uuid description: external workspace id avatar_color: type: string format: colors description: Color of the avatar created_at: type: string format: date-time description: Timestamp when the workspace was created updated_at: type: string format: date-time description: Timestamp when the workspace was last updated responses: PersonNotFound: description: Person not found content: application/json: schema: type: object properties: code: type: string example: PERSON_NOT_FOUND description: Error code identifier status: type: integer example: 404 description: HTTP status code title: type: string example: Person Not Found description: Error title message: type: string example: The requested person could not be found 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 ````