> ## 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. # Add contacts (batch) > Appends up to 10,000 contacts in one transaction. A phone number already in the list is skipped and counted in `skippedExisting` (its name and metadata are not updated). Repeated numbers inside one payload collapse to the first one and are counted in `duplicatesInPayload`. A failure leaves nothing half-applied, so the request can simply be retried. ## OpenAPI ````yaml POST /contact-lists/{id}/contacts 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/{id}/contacts: parameters: - $ref: '#/components/parameters/ListId' post: tags: - Contacts summary: Add contacts (batch) description: >- Appends up to 10,000 contacts in one transaction. A phone number already in the list is skipped and counted in `skippedExisting` (its name and metadata are not updated). Repeated numbers inside one payload collapse to the first one and are counted in `duplicatesInPayload`. A failure leaves nothing half-applied, so the request can simply be retried. operationId: addContacts parameters: - $ref: '#/components/parameters/UserEmail' - $ref: '#/components/parameters/UserId' requestBody: required: true content: application/json: schema: type: object required: - contacts properties: contacts: type: array minItems: 1 maxItems: 10000 items: $ref: '#/components/schemas/ContactInput' additionalProperties: false example: contacts: - name: Ada Lovelace phoneNumber: '+15550100' additionalNumbers: - '+15550199' - name: Grace Hopper phoneNumber: '+15550101' metadata: company: Acme - phoneNumber: '+15550102' responses: '200': description: Batch result content: application/json: schema: $ref: '#/components/schemas/BatchAddResult' example: contactListId: 4821 received: 3 added: 2 skippedExisting: 1 duplicatesInPayload: 0 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/ListNotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: ListId: name: id in: path required: true description: Id of the contact list, from the create response. schema: type: integer example: 4821 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: 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 BatchAddResult: type: object required: - contactListId - received - added - skippedExisting - duplicatesInPayload properties: contactListId: type: integer example: 4821 received: type: integer description: Contacts in the request. example: 3 added: type: integer example: 2 skippedExisting: type: integer description: Numbers already in the list; not updated. example: 1 duplicatesInPayload: type: integer description: Repeated numbers inside the request, collapsed to the first. example: 0 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 ListNotFound: description: List not found, or not owned by the acting user. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Contact list 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.