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

# Create a contact

> Creates a contact in the workspace.

Tags are linked by `id` or `name` and must already exist in the workspace — unknown tags are ignored. Use `PATCH /contacts/{contactId}/tags` to create tags on demand.

`customProperties` are keyed by property name and only properties already defined in the workspace are persisted.



## OpenAPI

````yaml POST /contacts
openapi: 3.1.0
info:
  title: Cogfy Messenger Public API
  version: 1.0.0
  description: API for interacting with the Cogfy Messenger platform
servers:
  - url: https://messenger-public-api.cogfy.com
    description: Production server
  - url: http://localhost:3100
    description: Local server
security:
  - ApiKeyAuth: []
paths:
  /contacts:
    post:
      tags:
        - Contacts
      summary: Create a contact
      description: >-
        Creates a contact in the workspace.


        Tags are linked by `id` or `name` and must already exist in the
        workspace — unknown tags are ignored. Use `PATCH
        /contacts/{contactId}/tags` to create tags on demand.


        `customProperties` are keyed by property name and only properties
        already defined in the workspace are persisted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  anyOf:
                    - type: string
                    - type: 'null'
                lastName:
                  anyOf:
                    - type: string
                    - type: 'null'
                email:
                  anyOf:
                    - type: string
                    - type: 'null'
                phone:
                  anyOf:
                    - type: string
                    - type: 'null'
                occupation:
                  anyOf:
                    - type: string
                    - type: 'null'
                gender:
                  anyOf:
                    - type: string
                    - type: 'null'
                birthdate:
                  anyOf:
                    - type: string
                    - type: 'null'
                age:
                  anyOf:
                    - type: number
                    - type: 'null'
                notes:
                  anyOf:
                    - type: string
                    - type: 'null'
                tags:
                  description: Tags to link to the contact. Only existing tags are linked
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: Id of an existing tag
                        type: string
                      name:
                        description: Name of an existing tag
                        type: string
                customProperties:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                  description: >-
                    Values for the custom contact properties of the workspace,
                    keyed by property name
            examples:
              complete:
                summary: Contact with tags and custom properties
                value:
                  firstName: John
                  lastName: Doe
                  email: john.doe@example.com
                  phone: '5511999998888'
                  occupation: Developer
                  notes: Met at the conference
                  tags:
                    - name: customers
                  customProperties:
                    plan: premium
              minimal:
                summary: Contact with a phone number only
                value:
                  phone: '5511999998888'
      responses:
        '201':
          description: Contact created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    description: Id of the created contact
                required:
                  - id
                additionalProperties: false
        '400':
          description: Bad request, invalid input data
        '401':
          description: Unauthorized
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key

````