> ## Documentation Index > Fetch the complete documentation index at: https://docs.powerdialer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a list > Creates a list, optionally seeded with contacts in the same call. Contacts go through the same path as a CSV upload, including background enrichment. If the payload repeats a phone number, only the first occurrence is kept and the response adds `duplicatesInPayload`. ## OpenAPI ````yaml /api-reference/openapi.json post /contact-lists openapi: 3.0.3 info: title: PowerDialer Public API version: '1.0' description: >- Manage PowerDialer contact lists and read a user's call analytics server-to-server. Every request carries the shared API key (`Authorization: Bearer ` or `x-api-key: `) and the PowerDialer user it acts for (`x-user-email` or `x-user-id`). Reads and writes are limited to lists that user owns; analytics are that user's own. Rate limit: 300 requests per minute per API key, across all users. servers: - url: https://api.migration.powerdialer.ai/api/public/v1 description: Production security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: Contact lists description: Create, update and delete lists. - name: Contacts description: Add and remove contacts in a list. - name: Analytics description: The acting user's call analytics. paths: /contact-lists: post: tags: - Contact lists summary: Create a list description: >- Creates a list, optionally seeded with contacts in the same call. Contacts go through the same path as a CSV upload, including background enrichment. If the payload repeats a phone number, only the first occurrence is kept and the response adds `duplicatesInPayload`. operationId: createContactList parameters: - $ref: '#/components/parameters/UserEmail' - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateContactListRequest' example: name: Partner leads October groupName: Partner contacts: - name: Ada Lovelace phoneNumber: '+15550100' - name: Grace Hopper phoneNumber: '+15550101' metadata: company: Acme email: grace@acme.com responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ContactList' example: id: 4821 name: Partner leads October groupName: Partner contactsCount: 2 orgId: org_2xyz... createdAt: '2026-10-06T12:00:00.000Z' updatedAt: '2026-10-06T12:00:00.000Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/UserNotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: UserEmail: name: x-user-email in: header required: false description: >- Login email of the PowerDialer user the request acts for. Send this or `x-user-id`; if both are sent, `x-user-id` wins. schema: type: string format: email example: rep@company.com UserId: name: x-user-id in: header required: false description: >- Clerk user id of the PowerDialer user the request acts for. Send this or `x-user-email`. schema: type: string example: user_2abc... schemas: CreateContactListRequest: type: object required: - name additionalProperties: false properties: name: type: string minLength: 1 maxLength: 150 example: Partner leads October groupName: type: string maxLength: 100 nullable: true description: Optional folder-style grouping. example: Partner contacts: type: array minItems: 1 maxItems: 10000 items: $ref: '#/components/schemas/ContactInput' description: Optional. Omit for an empty list. ContactList: type: object required: - id - name - groupName - contactsCount - orgId - createdAt - updatedAt properties: id: type: integer example: 4821 name: type: string example: Partner leads October groupName: type: string nullable: true example: Partner contactsCount: type: integer example: 2 orgId: type: string example: org_2xyz... createdAt: type: string format: date-time updatedAt: type: string format: date-time duplicatesInPayload: type: integer description: Present only when the create payload repeated a phone number. ContactInput: type: object required: - phoneNumber additionalProperties: false properties: phoneNumber: type: string minLength: 1 maxLength: 50 description: E.164 recommended, e.g. `+15550100`. example: '+15550100' name: type: string maxLength: 500 description: Optional; empty if omitted. example: Ada Lovelace additionalNumbers: type: array maxItems: 10 items: type: string minLength: 1 maxLength: 50 description: Alternate numbers for the same person. metadata: type: object additionalProperties: true description: Free-form fields shown on the contact (company, email, title, ...). example: company: Acme Error: type: object required: - error properties: error: type: string details: description: Optional. A string, or for validation errors a list of problems. oneOf: - type: string - type: array items: type: object properties: path: type: string message: type: string responses: BadRequest: description: >- Malformed body or query, unknown field, missing user header, impossible date. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid request details: - path: contacts.0.phoneNumber message: phoneNumber is required Unauthorized: description: Missing or wrong API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid API key UserNotFound: description: The user named in `x-user-email` / `x-user-id` does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: User not found RateLimited: description: More than 300 requests per minute for this API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Rate limit exceeded securitySchemes: bearerAuth: type: http scheme: bearer description: >- `Authorization: Bearer `. The key is issued by PowerDialer and must stay on your server. apiKeyHeader: type: apiKey in: header name: x-api-key description: 'Alternative to the Authorization header: `x-api-key: `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.