---
title: "Create New Client"
method: POST
path: "/internal/api/clients/"
tags: ["CLIENT", "Client Management"]
---

# Create New Client

`POST /internal/api/clients/`

## Request

- Base URL: `https://api.signalshq.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.signalshq.io/internal/api/clients/`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Create a new client with comprehensive information including filing details, address, and contact info. Only full name is required - all other fields are optional.

## Request body

- ClientCreate: Schema for creating a new client. Contains all the information needed to create a client record including address. Only full name is mandatory; all other fields are optional.
  - `full_name` string, required: Full legal name of the client (required)
  - `external_id` string, nullable: External client ID from external system (optional)
  - `filing_type` 'INDIVIDUAL_1040' | 'SOLO_SCHEDULE_C'
  - `filing_status` 'SINGLE' | 'MARRIED_FILING_JOINTLY' | 'MARRIED_FILING_SEPARATELY' | 'HEAD_OF_HOUSEHOLD' | 'QUALIFYING_SURVIVING_SPOUSE'
  - `blind` boolean, nullable: Is the client blind?
  - `disabled` boolean, nullable: Is the client disabled?
  - `ssn` string, nullable: Social Security Number (optional - will be encrypted and stored securely if provided)
  - `date_of_birth` string, date, nullable: Date of birth in YYYY-MM-DD format (optional)
  - `address` ClientAddressCreate: Address information for client creation
    - `street_address` string, nullable: Street address
    - `address_line_2` string, nullable: Additional address information
    - `city` string, nullable: City
    - `state` string, nullable: State
    - `zip_code` string, nullable: ZIP code
  - `email` string, nullable: Email address for communication (optional)
  - `phone` string, nullable: Phone number with country code (optional)
  - `spouse` SpouseCreate: Schema for creating a new spouse. Includes all spouse information plus SSN for tax filing purposes. The SSN will be encrypted and stored securely.
    - `full_name` string, required: Full legal name of the spouse
    - `email` string, email, nullable: Email address for communication (optional)
    - `phone` string, nullable: Phone number with country code (optional)
    - `date_of_birth` string, date, nullable: Date of birth in YYYY-MM-DD format (optional)
    - `blind` boolean: Is the spouse blind?
    - `disabled` boolean: Is the spouse disabled?
    - `same_as_taxpayer_address` boolean: Whether the spouse uses the same address as the taxpayer (client)
    - `relationship_type` string: Relationship type (always SPOUSE for spouse records)
    - `ssn` string, nullable: Social Security Number (will be encrypted and stored securely)
    - `address` AddressCreate
      - `street_address` string, nullable: The primary street address including house number and street name
      - `address_line_2` string, nullable: Additional address information such as apartment, suite, or unit number
      - `city` string, nullable: The city name
      - `state` string, nullable: The state abbreviation or full state name
      - `zip_code` string, nullable: The postal/ZIP code
  - `dependents` DependentCreate[], nullable: List of dependents (optional)
    - `full_name` string, required: Full legal name of the dependent
    - `date_of_birth` string, date, nullable: Date of birth in YYYY-MM-DD format (optional but recommended for tax purposes)
    - `blind` boolean: Is the dependent blind for tax deduction purposes
    - `disabled` boolean: Is the dependent disabled for tax deduction purposes
    - `relationship_type` 'SON' | 'DAUGHTER' | 'FOSTER_CHILD' | 'GRANDCHILD' | 'STEPCHILD' | 'GRANDPARENT' | 'PARENT' | 'BROTHER' | 'HALF_BROTHER' | 'STEP_BROTHER' | 'SISTER' | 'HALF_SISTER' | 'STEP_SISTER' | 'AUNT' | 'UNCLE' | 'NIECE' | 'NEPHEW' | 'NONE' | 'OTHER', required: Enumeration of possible relationships for dependents. Used to classify the relationship between the client and their dependent for tax filing purposes.
    - `relationship_other` string, nullable: Custom relationship description for additional context
    - `months_in_home` integer, nullable: Number of months the dependent lived in the home during the tax year (1-12)
    - `full_time_student` boolean: Whether the dependent is a full-time student
    - `ssn` string, nullable: Social Security Number (will be encrypted and stored securely)

## Response `201`

Successful Response

- ClientResponse
  - `id` string, uuid, required
  - `readable_id` string, required
  - `external_id` string, nullable, required
  - `tenant_id` string, uuid, required
  - `full_name` string, required
  - `filing_type` FilingTypeResponse, required: Response schema for filing type with value and human-readable label. Provides both the enum value and display-friendly text for frontend use.
    - `value` 'INDIVIDUAL_1040' | 'SOLO_SCHEDULE_C', required
    - `label` string, required: Human-readable label for the filing type
  - `filing_status` FilingStatusResponse, required: Response schema for filing status with value and human-readable label. Provides both the enum value and display-friendly text for frontend use.
    - `value` 'SINGLE' | 'MARRIED_FILING_JOINTLY' | 'MARRIED_FILING_SEPARATELY' | 'HEAD_OF_HOUSEHOLD' | 'QUALIFYING_SURVIVING_SPOUSE', required
    - `label` string, required: Human-readable label for the filing status
  - `blind` boolean, required
  - `disabled` boolean, required
  - `email` string, nullable, required
  - `phone` string, nullable, required
  - `date_of_birth` string, date, nullable, required
  - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE', required
  - `ssn_info` SSNInfoResponse, required: Response schema for SSN information. This schema represents encrypted SSN information that is returned to the client. The actual SSN is never returned in plain text - only masked versions are provided.
    - `id` string, uuid, required: Unique identifier for the SSN record
    - `entity_type` 'CLIENT' | 'SPOUSE' | 'DEPENDENT', required: Entity types for SSN information
    - `ssn_masked` string, required: Masked SSN showing only last 4 digits
    - `ssn_type` 'SSN' | 'ITIN', required: SSN types
  - `primary_address` AppSchemasClientClientAddressResponse, required
    - `id` string, uuid, required
    - `street_address` string, nullable, required
    - `address_line_2` string, nullable, required
    - `city` string, nullable, required
    - `state` string, nullable, required
    - `zip_code` string, nullable, required
  - `mailing_address` AppSchemasClientClientAddressResponse, required
    - `id` string, uuid, required
    - `street_address` string, nullable, required
    - `address_line_2` string, nullable, required
    - `city` string, nullable, required
    - `state` string, nullable, required
    - `zip_code` string, nullable, required
  - `spouse` SpouseResponse: Schema for spouse response data. Returns complete spouse information including encrypted SSN info. The SSN is never returned in plain text for security purposes.
    - `id` string, uuid, required: Unique identifier for the spouse record
    - `client_id` string, uuid, required: ID of the client this spouse belongs to
    - `tenant_id` string, uuid, required: Tenant organization ID
    - `full_name` string, required: Full legal name of the spouse
    - `email` string, email, nullable: Email address
    - `phone` string, nullable: Phone number
    - `date_of_birth` string, date, nullable: Date of birth
    - `blind` boolean, required: Is the spouse blind?
    - `disabled` boolean, required: Is the spouse disabled?
    - `same_as_taxpayer_address` boolean, required: Whether the spouse uses the same address as the taxpayer (client)
    - `relationship_type` string: Relationship type (always SPOUSE for spouse records)
    - `address` AppSchemasClientAddressAddressResponse
      - `id` string, uuid, required: Unique identifier for the address record
      - `street_address` string, nullable: The primary street address
      - `address_line_2` string, nullable: Additional address information
      - `city` string, nullable: The city name
      - `state` string, nullable: The state
      - `zip_code` string, nullable: The ZIP code
    - `ssn_info` SSNInfoResponse: Response schema for SSN information. This schema represents encrypted SSN information that is returned to the client. The actual SSN is never returned in plain text - only masked versions are provided.
      - `id` string, uuid, required: Unique identifier for the SSN record
      - `entity_type` 'CLIENT' | 'SPOUSE' | 'DEPENDENT', required: Entity types for SSN information
      - `ssn_masked` string, required: Masked SSN showing only last 4 digits
      - `ssn_type` 'SSN' | 'ITIN', required: SSN types
  - `dependents` DependentResponse[]
    - `id` string, uuid, required: Unique identifier for the dependent record
    - `client_id` string, uuid, required: ID of the client this dependent belongs to
    - `tenant_id` string, uuid, required: Tenant organization ID
    - `full_name` string, required: Full legal name of the dependent
    - `date_of_birth` string, date, nullable: Date of birth
    - `blind` boolean, required: Blind status
    - `disabled` boolean, required: Disabled status
    - `relationship_type` 'SON' | 'DAUGHTER' | 'FOSTER_CHILD' | 'GRANDCHILD' | 'STEPCHILD' | 'GRANDPARENT' | 'PARENT' | 'BROTHER' | 'HALF_BROTHER' | 'STEP_BROTHER' | 'SISTER' | 'HALF_SISTER' | 'STEP_SISTER' | 'AUNT' | 'UNCLE' | 'NIECE' | 'NEPHEW' | 'NONE' | 'OTHER', required: Enumeration of possible relationships for dependents. Used to classify the relationship between the client and their dependent for tax filing purposes.
    - `relationship_other` string, nullable: Custom relationship description
    - `months_in_home` integer, nullable: Number of months in home during tax year
    - `full_time_student` boolean, required: Full-time student status
    - `ssn_info` SSNInfoResponse: Response schema for SSN information. This schema represents encrypted SSN information that is returned to the client. The actual SSN is never returned in plain text - only masked versions are provided.
      - `id` string, uuid, required: Unique identifier for the SSN record
      - `entity_type` 'CLIENT' | 'SPOUSE' | 'DEPENDENT', required: Entity types for SSN information
      - `ssn_masked` string, required: Masked SSN showing only last 4 digits
      - `ssn_type` 'SSN' | 'ITIN', required: SSN types
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/signalshq/apis/signals-api.md) - [All operations](https://skmtc.dev/signalshq/apis/signals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalshq/apis/signals-api/revisions/2c22af3b5576?raw)