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

# Create Contact

> Create a new contact or update an existing one. If a contact already exists for the company by **email** or **phone**, that row is updated; otherwise a new contact is created. On upsert, new **tags** are merged with existing tags (deduplicated). Response body is empty (no JSON payload).



## OpenAPI

````yaml POST /contacts/
openapi: 3.1.0
info:
  title: Outbox AI API
  description: API for managing AI agents (chatbots and voicebots) on the Outbox platform
  version: 1.0.0
servers:
  - url: https://api.getoutbox.ai
security: []
paths:
  /contacts/:
    post:
      summary: Create or upsert contact
      description: >-
        Create a new contact or update an existing one. If a contact already
        exists for the company by **email** or **phone**, that row is updated;
        otherwise a new contact is created. On upsert, new **tags** are merged
        with existing tags (deduplicated). Response body is empty (no JSON
        payload).
      requestBody:
        description: Contact fields
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: Success. Empty response body (no JSON payload).
        '400':
          description: Bad Request - Invalid contact data
        '401':
          description: Unauthorized - Invalid or missing API key
      security:
        - CompanyApiKey: []
components:
  schemas:
    ContactCreate:
      type: object
      properties:
        full_name:
          type: string
          description: Title-cased; split into first and last name
        email:
          type: string
          description: Lowercased; optional
        phone_number:
          type: string
          description: Normalized using the company's country when present
        business_name:
          type: string
        notes:
          type: string
        tags:
          type: array
          items:
            type: string
          description: >-
            On an existing contact, new tags are merged with existing tags
            (deduplicated)
        is_dnd:
          oneOf:
            - type: boolean
            - type: string
          description: Do-not-disturb; boolean or string variants accepted
        lead_source:
          type: string
          description: >-
            Must be one of: manual, api, webhook, facebook, instagram, import.
            Invalid values are stored as manual.
        custom_fields:
          type: object
          additionalProperties:
            type: string
          description: >-
            Map of custom field name to value (string). Only keys that exist as
            company CustomField names are stored.
  securitySchemes:
    CompanyApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Company API Key

````