> ## Documentation Index > Fetch the complete documentation index at: https://docs.olimi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add a contact > Adds one contact to a customer list. If the list is part of a running campaign, the new contact is picked up for calling. Phone numbers are checked and stored in international format. See [Phone numbers](https://docs.olimi.ai/api-reference/endpoint/contacts/contacts.md#phone-numbers). To set custom field values, see [Custom fields](https://docs.olimi.ai/api-reference/endpoint/contacts/contacts.md#custom-fields). If the customer list doesn't allow duplicates, a phone number that's already in it is rejected with `contact_duplicate_phone_number`, and `data.existingContactId` tells you which contact has it. Duplicates are allowed or not per list, in the Dashboard. The response includes `customerListId`, the same value as `customerId`. Common causes of a `422` validation error: * `phoneNumber` is missing or longer than 50 characters. * `email` isn't a valid email address, or is longer than 50 characters. * `firstName` or `lastName` is longer than 100 characters. * An item in `variantValues` is missing `variantId` or `value`. ## OpenAPI ````yaml post /api/v2/contacts openapi: 3.0.1 info: title: Customer Management API description: API for managing customer lists and customers within those lists license: name: MIT version: 1.0.0 servers: - url: https://api-eg.olimi.ai security: - bearerAuth: [] paths: /api/v2/contacts: post: tags: - Contacts summary: Add a contact description: >- Adds one contact to a customer list. If the list is part of a running campaign, the new contact is picked up for calling. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactCreate' responses: '201': description: The new contact. content: application/json: schema: $ref: '#/components/schemas/ContactCreateResponse' '400': description: >- See [Errors](/api-reference/endpoint/contacts/contacts#errors). A duplicate number returns `data.existingContactId`. content: application/json: schema: $ref: '#/components/schemas/ContactDuplicateError' '401': description: The `X-API-KEY` header is missing or the key isn't valid. content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: The request didn't pass validation. content: application/json: schema: $ref: '#/components/schemas/ValidationError' security: - apiKeyAuth: [] components: schemas: ContactCreate: type: object required: - customerListId - phoneNumber properties: customerListId: type: string format: uuid description: The customer list to add the contact to. example: 9c4e1b7a-2d5f-4a83-b6e0-3f7d9a1c5e24 phoneNumber: type: string minLength: 1 maxLength: 50 description: >- See [Phone numbers](/api-reference/endpoint/contacts/contacts#phone-numbers). example: '+201001234567' firstName: type: string maxLength: 100 example: Ahmed lastName: type: string maxLength: 100 example: Hassan email: type: string format: email maxLength: 50 example: ahmed.hassan@example.com gender: type: string maxLength: 50 description: Free text. example: male variantValues: type: array items: $ref: '#/components/schemas/ContactVariantValueInput' description: >- Custom field values. See [Custom fields](/api-reference/endpoint/contacts/contacts#custom-fields). ContactCreateResponse: type: object properties: message: type: string example: Contact created successfully data: $ref: '#/components/schemas/ContactCreated' ContactDuplicateError: type: object properties: statusCode: type: integer example: 400 errorCode: type: string example: contact_duplicate_phone_number message: type: string example: A contact with this phone number already exists data: type: object description: Only for `contact_duplicate_phone_number`. properties: existingContactId: type: string format: uuid description: The contact that already has this number. example: b2f7c4e1-8a3d-4c59-9e06-1d5a7f3b8c42 ApiError: type: object properties: statusCode: type: integer example: 404 errorCode: type: string description: Machine-readable error code. example: agent_not_found message: type: string description: Human-readable text. May change; don't match on it. example: Agent not found ValidationError: type: object properties: statusCode: type: integer example: 422 message: type: array items: type: string description: What went wrong. Human-readable. example: - name must be shorter than or equal to 100 characters error: type: string example: Unprocessable Entity ContactVariantValueInput: type: object required: - variantId - value properties: variantId: type: string format: uuid description: The variant's `id`, from `GET /api/v2/customer-lists/{id}`. example: 7e3c9b15-6a2d-4f8e-b1c4-5d9a3e7f2b60 value: type: string minLength: 1 description: The contact's value for that column. example: ORD-10492 ContactCreated: allOf: - $ref: '#/components/schemas/ContactSingle' - type: object properties: customerListId: type: string format: uuid description: Same value as `customerId`. example: 9c4e1b7a-2d5f-4a83-b6e0-3f7d9a1c5e24 ContactSingle: type: object properties: id: type: string format: uuid description: The contact's ID. Use it to edit or delete the contact. example: b2f7c4e1-8a3d-4c59-9e06-1d5a7f3b8c42 customerId: type: string format: uuid description: The ID of the customer list the contact is in. example: 9c4e1b7a-2d5f-4a83-b6e0-3f7d9a1c5e24 firstName: type: string nullable: true description: First name. example: Ahmed lastName: type: string nullable: true description: Last name. example: Hassan phoneNumber: type: string description: Phone number in E.164 format. example: '+201001234567' email: type: string nullable: true description: Email address. example: ahmed.hassan@example.com gender: type: string nullable: true description: Free text, as you sent it. example: male retries: type: integer description: How many times a campaign has scheduled a retry for this contact. example: 0 lastCallStatus: type: string enum: - not_called - pending - in_progress - answered - not_answered - failed description: >- Outcome of the latest call. See [Call status values](/api-reference/endpoint/contacts/contacts#call-status-values). example: not_called callbackScheduled: type: boolean description: Whether the contact asked to be called back. example: false callbackAt: type: string format: date-time nullable: true description: When the callback is due (UTC). example: null variantValues: type: array description: The contact's custom field values. items: $ref: '#/components/schemas/ContactVariantValueSingle' createdAt: type: string format: date-time description: When the contact was added (UTC). example: '2026-09-20T08:14:22.531Z' updatedAt: type: string format: date-time description: When the contact was last changed (UTC). example: '2026-09-27T11:40:09.118Z' ContactVariantValueSingle: type: object properties: id: type: string format: uuid description: The value's own ID. example: 4d8e2a6f-1c7b-4e93-a5d0-8f2b6c1e9a37 value: type: string description: The contact's value for that column. example: ORD-10492 variant: $ref: '#/components/schemas/ContactVariant' ContactVariant: type: object properties: id: type: string format: uuid description: The variant's ID. example: 7e3c9b15-6a2d-4f8e-b1c4-5d9a3e7f2b60 name: type: string description: The column's display name. example: Order number slug: type: string description: The name used in the agent's script. example: order_number securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: X-API-KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.