> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automatebusiness.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Contact

> Creates a new contact within the workspace. Duplicate checks are automatically performed against existing phone numbers in the workspace.

Use this endpoint to add new contacts to your workspace.

You must provide a valid `phoneNumber` and `countryCode` to create a contact. You can also optionally enrich the contact's profile with their name, email, tags, and custom fields during creation.

The system automatically performs duplicate checks. By default, you cannot create multiple contacts with the same phone number in a single workspace. You can pass `overwrite: true` to seamlessly update the existing contact's values instead of receiving a duplication error.


## OpenAPI

````yaml POST /api/contacts
openapi: 3.1.0
info:
  title: Automate Chats API
  description: >-
    API for managing WhatsApp template messages, contacts, custom fields, tags,
    and external integrations.
  version: 1.0.0
servers:
  - url: https://api.automatechats.com
security:
  - apiKeyAuth: []
paths:
  /api/contacts:
    post:
      summary: Create Contact
      description: >-
        Creates a new contact within the workspace. Duplicate checks are
        automatically performed against existing phone numbers in the workspace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreateInput'
            examples:
              createSimple:
                summary: Simple Contact
                value:
                  firstName: John
                  lastName: Doe
                  phoneNumber: '9876543210'
                  countryCode: '+91'
                  email: john.doe@example.com
              createWithTagsAndCustomFields:
                summary: With Tags & Custom Fields
                value:
                  firstName: Alice
                  lastName: Smith
                  phoneNumber: '9998887776'
                  countryCode: '+91'
                  email: alice.smith@example.com
                  subscribed: true
                  tagsId:
                    - 65e0bc51c12e4d70834b070e
                    - 65e0bc51c12e4d70834b070f
                  customFields:
                    - fieldId: 65f12ab3c9e4f1a2b3c4d5e6
                      value: Enterprise Partner
                    - fieldId: 65f12ab3c9e4f1a2b3c4d5e7
                      value: 50000
                  dob: '1990-05-12'
      responses:
        '201':
          description: Contact created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  code:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: Contact created successfully
                  data:
                    type: object
                    properties:
                      contact:
                        $ref: '#/components/schemas/Contact'
                  timestamp:
                    type: string
                    format: date-time
        '400':
          description: Bad Request (e.g. Validation Errors or Missing Fields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Conflict (Phone number already exists in workspace)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                code: 409
                message: >-
                  Duplicate key error: Contact with this phone number already
                  exists in the workspace.
                timestamp: '2026-05-18T15:00:00.000Z'
components:
  schemas:
    ContactCreateInput:
      type: object
      required:
        - firstName
        - phoneNumber
        - countryCode
        - source
      properties:
        firstName:
          type: string
          minLength: 2
          maxLength: 50
          description: Contact's first name
          example: John
        lastName:
          type: string
          maxLength: 50
          description: Contact's last name
          example: Doe
        chatName:
          type: string
          maxLength: 100
          description: Formatted name used in active chats
          example: John Doe
        email:
          type: string
          format: email
          description: Contact's email address
          example: john.doe@example.com
        phoneNumber:
          type: string
          description: Phone number without country code (typically 10-15 digits)
          example: '9876543210'
        countryCode:
          type: string
          description: Country code including '+' (e.g. `+91`, `+1`)
          example: '+91'
        source:
          type: string
          maxLength: 50
          description: Required source identifier (e.g., contact_form)
          example: contact_form
        subscribed:
          type: boolean
          default: true
          description: Auto-subscribe contact to WhatsApp broadcasts
        overwrite:
          type: boolean
          default: false
          description: >-
            If true, updates the existing contact if a contact with the same
            phone number already exists, instead of returning a duplicate error.
        tagsId:
          type: array
          description: Array of 24-character hexadecimal MongoDB Tag IDs to assign
          items:
            type: string
          example:
            - 65e0bc51c12e4d70834b070e
        customFields:
          type: array
          description: Array of custom field values to assign
          items:
            $ref: '#/components/schemas/CustomFieldInput'
        dob:
          type: string
          format: date
          description: Date of Birth (YYYY-MM-DD)
          example: '1990-01-15'
        anniversary:
          type: string
          format: date
          description: Anniversary date (YYYY-MM-DD)
          example: '2020-06-20'
    Contact:
      type: object
      properties:
        id:
          type: string
          description: Unique MongoDB ID of the contact
          example: 65e0bc51c12e4d70834b070e
        firstName:
          type: string
          description: Contact's first name
          example: John
        lastName:
          type: string
          description: Contact's last name
          example: Doe
        chatName:
          type: string
          description: Formatted name used in active chats
          example: John Doe
        email:
          type: string
          format: email
          description: Contact's email address
          example: john.doe@example.com
        phoneNumber:
          type: string
          description: Contact's phone number without country code
          example: '9876543210'
        countryCode:
          type: string
          description: Contact's telephone country code
          example: '+91'
        source:
          type: string
          description: >-
            How the contact was entered into the system (e.g. `manual`,
            `import`, `widget`, `whatsapp`)
          example: manual
        subscribed:
          type: boolean
          description: WhatsApp subscription status
          example: true
        tagsId:
          type: array
          description: List of tag IDs assigned to this contact
          items:
            type: string
          example:
            - 65e0bc51c12e4d70834b070e
        tags:
          type: array
          description: Detailed metadata of tags assigned to this contact
          items:
            $ref: '#/components/schemas/ContactTag'
        customFields:
          type: array
          description: Detailed custom field values assigned to this contact
          items:
            type: object
            properties:
              id:
                type: string
                description: Custom field identifier
                example: 65f12ab3c9e4f1a2b3c4d5e6
              label:
                type: string
                description: Friendly name of the custom field
                example: Company Name
              value:
                description: Value associated with this custom field for this contact
                example: Google Deepmind
        dob:
          type: string
          format: date
          description: Date of Birth (ISO 8601 YYYY-MM-DD)
          example: '1990-01-15'
        anniversary:
          type: string
          format: date
          description: Anniversary date (ISO 8601 YYYY-MM-DD)
          example: '2020-06-20'
        workspaceId:
          type: integer
          description: Multi-tenant workspace ID ownership
          example: 246
        createdBy:
          type: string
          description: ID of the user who created this contact
          example: 6996aeeedf12574080a99d81
        createdAt:
          type: string
          format: date-time
          description: Timestamp when contact was created
          example: '2026-05-18T15:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when contact was last updated
          example: '2026-05-18T15:05:00.000Z'
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        code:
          type: integer
          example: 400
        message:
          type: string
          example: 'Invalid input: field first_name is required.'
        error:
          description: Optional validation error details or raw stack traces.
        timestamp:
          type: string
          format: date-time
          example: '2026-05-18T15:00:00.000Z'
    CustomFieldInput:
      type: object
      required:
        - fieldId
        - value
      properties:
        fieldId:
          type: string
          description: 24-character hex ID of the custom field defined in the workspace.
          example: 65f12ab3c9e4f1a2b3c4d5e6
        value:
          description: >-
            New value to assign. Supports strings, numbers, booleans, or dates
            based on the custom field definition.
          example: Enterprise
    ContactTag:
      type: object
      properties:
        tagId:
          type: string
          description: Unique ID of the tag
          example: 65e0bc51c12e4d70834b070e
        name:
          type: string
          description: Friendly tag name
          example: VIP
        text_color:
          type: string
          description: Hex text color code
          example: '#ffffff'
        background_color:
          type: string
          description: Hex background color code
          example: '#ef4444'
  responses:
    UnauthorizedError:
      description: Unauthorized (missing or invalid API key / JWT token)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: error
            code: 401
            message: >-
              Unauthorized access: Invalid or missing authentication
              credentials.
            timestamp: '2026-05-18T15:00:00.000Z'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````