> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Create client contact > Promote an existing person into a client contact by linking them to a client company. The associated company is automatically flagged as a client. **Idempotency**: A person can be an active client contact for at most one client company per team (DB constraint). If a non-deleted client contact already exists for this person, the existing record is returned with `is_new: false` and the echoed `client_id` reflects the contact's actual client company — compare it to the requested `client_id` to detect mismatches. New contacts return 201 with `is_new: true`; existing contacts return 200. **Status**: When `client_contact_status_id` is omitted, the team default status is assigned. Pass null to leave the new contact without a status. **Owners**: When `owner_ids` is omitted, the authenticated caller is auto-assigned (if they are a team member). Pass an empty array to create a contact with no owners. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/client-contacts openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/client-contacts: post: tags: - Client Contacts summary: Create client contact description: >- Promote an existing person into a client contact by linking them to a client company. The associated company is automatically flagged as a client. **Idempotency**: A person can be an active client contact for at most one client company per team (DB constraint). If a non-deleted client contact already exists for this person, the existing record is returned with `is_new: false` and the echoed `client_id` reflects the contact's actual client company — compare it to the requested `client_id` to detect mismatches. New contacts return 201 with `is_new: true`; existing contacts return 200. **Status**: When `client_contact_status_id` is omitted, the team default status is assigned. Pass null to leave the new contact without a status. **Owners**: When `owner_ids` is omitted, the authenticated caller is auto-assigned (if they are a team member). Pass an empty array to create a contact with no owners. operationId: createClientContact requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateClientContactRequest' responses: '200': description: Existing client contact returned (no duplicate created) content: application/json: schema: $ref: '#/components/schemas/CreateClientContactResponse' example: success: true data: id: ab12cd34-ef56-7890-ab12-cd34ef567890 person_id: fff66666-0000-1111-2222-333333336666 client_id: bbb22222-cccc-dddd-eeee-ffffffff2222 client_contact_status_id: 890e1234-f56a-78b9-c012-345678901234 owner_ids: - ddd44444-eeee-ffff-0000-111111114444 created_at: '2024-01-15T10:00:00Z' is_new: false '201': description: Client contact created content: application/json: schema: $ref: '#/components/schemas/CreateClientContactResponse' example: success: true data: id: ab12cd34-ef56-7890-ab12-cd34ef567890 person_id: fff66666-0000-1111-2222-333333336666 client_id: bbb22222-cccc-dddd-eeee-ffffffff2222 client_contact_status_id: 890e1234-f56a-78b9-c012-345678901234 owner_ids: - ddd44444-eeee-ffff-0000-111111114444 created_at: '2024-01-15T10:00:00Z' is_new: true '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: CreateClientContactRequest: type: object properties: person_id: type: string format: uuid description: >- Person UUID to promote into a client contact. Get IDs from POST /v1/persons/search or POST /v1/persons. client_id: type: string format: uuid description: >- Client company UUID this person belongs to. Get IDs from GET /v1/companies. The company is automatically flagged as a client when this contact is created. client_contact_status_id: type: - string - 'null' format: uuid description: >- Optional client contact status UUID. When omitted, the team default status is used. Use GET /v1/client-contacts/statuses to discover available status IDs. owner_ids: type: array items: type: string format: uuid description: >- Optional team member UUIDs to assign as client-contact owners. If omitted, the authenticated caller (when they are a team member) is auto-assigned. required: - person_id - client_id CreateClientContactResponse: type: object properties: success: type: boolean enum: - true data: type: object properties: id: type: string format: uuid description: Created client contact UUID. person_id: type: string format: uuid description: Person UUID linked to this client contact. client_id: type: string format: uuid description: Client company UUID this contact belongs to. client_contact_status_id: type: - string - 'null' format: uuid description: Assigned client contact status UUID, if any. owner_ids: type: array items: type: string format: uuid description: Team member UUIDs assigned as owners. created_at: type: string description: ISO 8601 creation timestamp. is_new: type: boolean description: >- True when a new client contact row was created. False when an existing client contact for this person was returned instead — in that case the echoed `client_id` may differ from the requested value if the person was already linked to a different client company. required: - id - person_id - client_id - client_contact_status_id - owner_ids - created_at - is_new required: - success - data securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````