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

# Create a customer



## OpenAPI

````yaml /openapi/public-api.yaml post /v1/customers
openapi: 3.1.0
info:
  title: Linkiasoft API
  version: 1.0.0
  description: >
    Send and read messages across WhatsApp, Instagram, Messenger and Telegram,
    and read

    and update the CRM behind them — leads, pipeline stages, company contacts
    and activity

    history.


    Every endpoint is authenticated with a tenant-scoped API key and returns
    only data

    belonging to that key's workspace.


    **Two hosts, one key.** Messaging lives on `social.linkiasoft.com` and the
    CRM on

    `api.linkiasoft.com`. Each endpoint below shows its own base URL; the same
    API key

    authenticates against both.
servers:
  - url: https://social.linkiasoft.com/api
    description: Production
security:
  - apiKey: []
    tenantId: []
tags:
  - name: Conversations
    description: Read threads and send messages.
  - name: Templates
    description: Approved WhatsApp message templates.
  - name: Channels
    description: The connected accounts you can send from.
  - name: Leads
    description: Deals moving through your pipeline.
  - name: Pipeline
    description: The stages a lead can sit in.
  - name: Contacts
    description: People attached to a company.
  - name: Activities
    description: Logged calls, emails, meetings and follow-ups.
  - name: Customers
    description: The companies and accounts your contacts belong to.
  - name: Tags
    description: Labels applied to customers, contacts and leads.
  - name: Quick replies
    description: Team-shared canned responses.
  - name: WhatsApp groups
    description: Create and manage WhatsApp group chats.
paths:
  /v1/customers:
    servers:
      - url: https://api.linkiasoft.com/api
    post:
      tags:
        - Customers
      summary: Create a customer
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '201':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    CustomerInput:
      type: object
      description: All fields optional on update; send only what changes.
      properties:
        name:
          type: string
        company_name:
          type: string
        industry:
          type: string
        website:
          type: string
        email:
          type: string
        phone:
          type: string
        address:
          type: object
          additionalProperties: true
        customer_type:
          type: string
          enum:
            - individual
            - business
        status:
          type: string
          enum:
            - active
            - inactive
            - prospect
            - archived
        source:
          type: string
          enum:
            - website
            - referral
            - import
            - manual
            - api
          description: Use `api` for records your integration creates.
        assigned_to_user_id:
          type: string
          format: uuid
        tags:
          type: array
          items:
            type: string
            format: uuid
        custom_fields:
          type: object
          additionalProperties: true
    Customer:
      type: object
      description: A company or account. The people at it are contacts.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        company_name:
          type: string
        industry:
          type: string
        website:
          type: string
        email:
          type: string
        phone:
          type: string
        address:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            country:
              type: string
            postal_code:
              type: string
        customer_type:
          type: string
          enum:
            - individual
            - business
        status:
          type: string
          enum:
            - active
            - inactive
            - prospect
            - archived
        source:
          type: string
          enum:
            - website
            - referral
            - import
            - manual
            - api
        assigned_to_user_id:
          type: string
          format: uuid
        tags:
          type: array
          description: Tag IDs. Resolve them with `GET /tags`.
          items:
            type: string
            format: uuid
        custom_fields:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          description: A sentence explaining the failure, or a list of field errors.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        error:
          type: string
      examples:
        - statusCode: 403
          message: 'API key missing required scope(s): conversations:read'
          error: Forbidden
  responses:
    BadRequest:
      description: The request was malformed. The `message` says what to fix.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The API key is missing, invalid, revoked, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >
        The key is valid but lacks the scope for this endpoint, or the workspace
        has hit a

        plan limit (for example its monthly active-contact quota).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        Your workspace API key. Create one in **Settings → API Keys**; the
        plaintext value

        is shown once and never again.


        Keys are scoped. A key needs `conversations:send` to send,
        `conversations:read` to

        read threads and messages, `templates:read` to list templates, and
        `channels:read`

        to list channels. A key missing the scope for an endpoint gets `403`.


        The CRM endpoints use the same `resource:action` form: `leads:read`,
        `leads:create`,

        `leads:update`, `leads:delete`, `customers:read`, `customers:create`,

        `customers:update`, `customers:delete`, `customers:manage`.


        Several resources have no scope of their own and borrow one:


        | Resource | Governed by |

        |---|---|

        | Contacts | `customers:*` |

        | Activities | `customers:*` for customer activities, `leads:*` for lead
        activities |

        | Tags | `customers:read` to list, `customers:manage` to change |

        | Pipeline stages | `leads:*` |

        | Quick replies | `quick-replies:read` / `quick-replies:write` |

        | WhatsApp groups | `wa-groups:manage` |


        Grant only what the integration needs — a key that only sends
        notifications should

        hold `conversations:send` and nothing else.
    tenantId:
      type: apiKey
      in: header
      name: X-Tenant-Id
      description: >
        Your workspace UUID. Required on every request **in addition to**
        `x-api-key`.


        It does not select the workspace — data access is always scoped to the
        workspace

        that owns the API key, and a mismatched value cannot read anyone else's
        data.

````