> ## 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 calling list > Create an empty calling list for a rep or team workflow, then add contacts through membership operations or an asynchronous import. Requires `lists:write`. Supply a name and the `ownerId` of a current workspace member that the key is allowed to manage. An optional `groupName` helps organize lists; omitted or null means no group. The response returns the new numeric list ID and current details. List names are not unique, so save the ID instead of using the name as an identifier. Contact rows are not accepted in this request, and creating a list does not place calls. A persisted `Idempotency-Key` is required. Reuse it with the same body after a timeout to recover the original `201` response. `403 invalid_owner` requires an allowed member; `400 invalid_request` identifies malformed fields. For `409 idempotency_conflict`, recover the original request rather than blindly creating another list. See [create a list](/guides/contact-lists#create-a-list). ## OpenAPI ````yaml /api/openapi.json post /lists openapi: 3.1.0 info: title: PowerDialer API v2 version: 2.0.0 description: >- Connect your CRM, sales workspace or reporting tools to PowerDialer using scoped API keys. Manage contacts and calling lists, read call evidence and analytics, and receive signed events. All example records and IDs are synthetic; replace them with values from your workspace. Shared-key v1 is retired. API availability was verified on 2026-10-08; see /availability for historical data coverage. Legacy outbound webhooks use a separate contract. servers: - url: https://api.migration.powerdialer.ai/api/public/v2 description: Production API v2; availability verified on 2026-10-08. security: - ApiKey: [] tags: - name: Authentication - name: Contacts - name: Calling lists - name: Imports - name: Calls - name: Synchronization - name: Analytics - name: Webhooks - name: Webhook deliveries - name: Incoming webhook payloads paths: /lists: post: tags: - Calling lists summary: Create a calling list description: >- Create an empty calling list for a rep or team workflow, then add contacts through membership operations or an asynchronous import. Requires `lists:write`. Supply a name and the `ownerId` of a current workspace member that the key is allowed to manage. An optional `groupName` helps organize lists; omitted or null means no group. The response returns the new numeric list ID and current details. List names are not unique, so save the ID instead of using the name as an identifier. Contact rows are not accepted in this request, and creating a list does not place calls. A persisted `Idempotency-Key` is required. Reuse it with the same body after a timeout to recover the original `201` response. `403 invalid_owner` requires an allowed member; `400 invalid_request` identifies malformed fields. For `409 idempotency_conflict`, recover the original request rather than blindly creating another list. See [create a list](/guides/contact-lists#create-a-list). operationId: postLists parameters: - name: Idempotency-Key in: header required: true schema: type: string pattern: ^[A-Za-z0-9._:-]{1,200}$ description: >- Persist one key for this logical operation before sending it. Reuse the same value only with the same method, path and body after a timeout. A changed request returns 409 idempotency_conflict; a matching retry returns the original response. example: 9d6b623c-c132-4d2f-b8cf-7c65d4760dbe requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ListWrite' example: name: October inbound leads ownerId: user_example groupName: Inbound responses: '201': description: >- The new empty calling list, or its original creation response on an identical retry. headers: X-Request-Id: schema: type: string format: uuid RateLimit-Limit: schema: type: integer RateLimit-Remaining: schema: type: integer Idempotency-Replayed: schema: type: string enum: - 'true' - 'false' content: application/json: schema: $ref: '#/components/schemas/List' example: name: October inbound leads ownerId: user_example groupName: Inbound id: 456 orgId: org_example createdAt: '2026-10-08T12:00:00.000Z' updatedAt: '2026-10-08T12:00:00.000Z' contactsCount: 0 default: description: >- Error. 400 invalid request; 401 invalid credential; 403 insufficient access; 404 not found; 409 state/idempotency conflict; 413 size limit; 422 verification failure; 429 rate limit (Retry-After seconds); 503 temporary service failure. headers: Retry-After: schema: type: integer X-Request-Id: schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: API key is invalid, expired or revoked requestId: 00000000-0000-4000-8000-000000000004 x-codeSamples: - lang: bash label: cURL source: >- # Replace example resource IDs and ownerId with values from your workspace. : "${POWERDIALER_API_KEY:?Set POWERDIALER_API_KEY to your scoped API key}" # Set this once per operation; reuse it with the same request after a timeout. : "${POWERDIALER_REQUEST_ID:?Set POWERDIALER_REQUEST_ID to a new UUID for this operation}" curl --request POST \ --url 'https://api.migration.powerdialer.ai/api/public/v2/lists' \ --header "Authorization: Bearer $POWERDIALER_API_KEY" \ --header "Idempotency-Key: $POWERDIALER_REQUEST_ID" \ --header 'Content-Type: application/json' \ --data '{ "name": "October inbound leads", "ownerId": "user_example", "groupName": "Inbound" }' components: schemas: ListWrite: type: object properties: name: type: string minLength: 1 maxLength: 150 description: Display name for the calling list. ownerId: type: string minLength: 1 maxLength: 100 description: >- Active workspace member who owns the list and is allowed by this key. groupName: anyOf: - type: string maxLength: 100 - type: 'null' default: null description: Optional grouping label. Omission on PUT clears the stored label. required: - name - ownerId additionalProperties: false examples: - name: October inbound leads ownerId: user_example groupName: Inbound List: type: object properties: id: type: integer description: >- PowerDialer list ID. Use this integer in list URLs and analytics filters. name: type: string description: Calling-list display name. ownerId: type: string description: PowerDialer member who owns this list. orgId: anyOf: - type: string - type: 'null' description: Workspace identifier stored on the list. groupName: anyOf: - type: string - type: 'null' description: Optional grouping label, or null. createdAt: type: string format: date-time description: List creation time in UTC. updatedAt: type: string format: date-time description: Last list update time in UTC. contactsCount: type: integer description: >- Stored total membership count for the list. It may exceed the contacts visible to a restricted key. required: - id - name - ownerId - orgId - groupName - createdAt - updatedAt - contactsCount examples: - name: October inbound leads ownerId: user_example groupName: Inbound id: 456 orgId: org_example createdAt: '2026-10-08T12:00:00.000Z' updatedAt: '2026-10-08T12:00:00.000Z' contactsCount: 1 Error: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code. message: type: string description: Human-readable explanation. requestId: type: string format: uuid description: Request identifier to include when investigating a failure. details: type: array items: type: object properties: path: type: string message: type: string required: - path - message description: Validation errors, when available. required: - code - message - requestId required: - error examples: - error: code: insufficient_scope message: Requires contacts:read requestId: 00000000-0000-4000-8000-000000000004 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: pd__. description: >- Issued in Developers. Workspace/owner/scopes come from credential, never acting-user headers. API keys cannot manage API credentials. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.