> ## 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. # Set preferred phone (bulk) > Star a stored phone number as preferred for one or many persons. The phone number must already exist on each person — this endpoint does not add new numbers. Formatting differences are accepted when the digits match. Invalid rows fail individually and do not block other rows in the same request. When the same person_id appears twice, the last entry wins. For a single person that should return the updated person record, use `POST /v1/persons/{id}/preferred-phone`. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/persons/preferred-phone 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/persons/preferred-phone: post: tags: - Persons summary: Set preferred phone (bulk) description: >- Star a stored phone number as preferred for one or many persons. The phone number must already exist on each person — this endpoint does not add new numbers. Formatting differences are accepted when the digits match. Invalid rows fail individually and do not block other rows in the same request. When the same person_id appears twice, the last entry wins. For a single person that should return the updated person record, use `POST /v1/persons/{id}/preferred-phone`. operationId: setPersonsPreferredPhone requestBody: content: application/json: schema: $ref: '#/components/schemas/SetPreferredPhonesBulkRequest' responses: '200': description: Preferred phones updated content: application/json: schema: $ref: '#/components/schemas/SetPreferredPhonesBulkResponse' example: success: true data: updated: - person_id: 123e4567-e89b-12d3-a456-426614174000 preferred_phone: +1-555-0123 failed: - person_id: 00000000-0000-0000-0000-000000000001 error: Person not found '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: SetPreferredPhonesBulkRequest: type: object properties: updates: type: array items: type: object properties: person_id: type: string format: uuid description: Person UUID. Get IDs from POST /v1/persons/search. phone: type: string minLength: 1 description: >- Phone number to star as preferred. Must already exist on that person. required: - person_id - phone minItems: 1 maxItems: 100 description: >- Persons to update (1–100). Invalid rows fail individually and do not block other rows. When the same person_id appears twice, the last entry wins. required: - updates SetPreferredPhonesBulkResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/SetPreferredPhonesBulkResult' required: - success - data SetPreferredPhonesBulkResult: type: object properties: updated: type: array items: type: object properties: person_id: type: string format: uuid preferred_phone: type: string required: - person_id - preferred_phone description: >- Persons whose preferred phone was set. preferred_phone is the stored number that was starred. failed: type: array items: type: object properties: person_id: type: string format: uuid description: Person UUID that failed. error: type: string description: >- Why this row was not updated, such as "Person not found" or "Email is not stored on this person". required: - person_id - error description: >- Rows that could not be updated. Other valid rows in the same request are still processed. required: - updated - failed securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````