> ## 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 list > Create a new saved list. Lists can hold either persons or companies, determined by `list_type`. Optionally link to a job, person, or company. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/lists 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/lists: post: tags: - Lists summary: Create list description: >- Create a new saved list. Lists can hold either persons or companies, determined by `list_type`. Optionally link to a job, person, or company. operationId: createList requestBody: content: application/json: schema: $ref: '#/components/schemas/ListCreateRequest' responses: '201': description: List created content: application/json: schema: $ref: '#/components/schemas/ListCreateResponse' example: success: true data: id: aaa11111-bbbb-cccc-dddd-eeeeeeee1111 name: Engineering Candidates Q2 list_type: persons is_public: true is_archived: false linked_job_id: fff66666-0000-1111-2222-333333336666 linked_person_id: null linked_organization_company_id: null created_at: '2024-01-15T10:00:00Z' '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: ListCreateRequest: type: object properties: name: type: string minLength: 1 description: List name (required). list_type: type: string enum: - persons - companies default: persons description: Type of entities in this list. Defaults to "persons". is_public: type: boolean default: false description: Whether the list is visible to all team members. Defaults to false. linked_job_id: type: string format: uuid description: Job UUID to link this list to. linked_person_id: type: string format: uuid description: Person UUID to link this list to. linked_organization_company_id: type: string format: uuid description: Company UUID to link this list to. owner_ids: type: array items: type: string format: uuid description: >- Team member UUIDs to assign as list owners. If omitted, the caller is auto-assigned. team_member_id: type: string format: uuid description: >- Team member UUID to attribute as the list creator. Required for API-key auth (which has no implicit user context). Ignored when using session or OAuth auth. required: - name ListCreateResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/ListCreateResponseData' required: - success - data ListCreateResponseData: type: object properties: id: type: string format: uuid description: Created list UUID. name: type: string description: List name. list_type: type: string enum: - persons - companies description: List type. is_public: type: boolean description: Public visibility. is_archived: type: boolean description: Archived status. linked_job_id: type: - string - 'null' format: uuid description: Linked job UUID. linked_person_id: type: - string - 'null' format: uuid description: Linked person UUID. linked_organization_company_id: type: - string - 'null' format: uuid description: Linked company UUID. created_at: type: - string - 'null' description: ISO 8601 creation timestamp. required: - id - name - list_type - is_public - is_archived - linked_job_id - linked_person_id - linked_organization_company_id - created_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````