---
title: "Create client"
method: POST
path: "/clients"
tags: ["Clients"]
---

# Create client

`POST /clients`

Create a new client with fiscal information for Mexican tax compliance.

**Duplicate Prevention (Upsert):** Use the `search` parameter to find existing clients before creating:
- If a match is found and `search.update` is `false` (default): Returns the existing client without modifications.
- If a match is found and `search.update` is `true`: Updates the existing client with the provided data and returns it.
- If no match is found: Creates a new client.

This is useful for integrations that may send the same client multiple times.

**gigstack Connect:** Create clients for other teams using the `team` parameter.

## Query parameters

- `team` string

## Request body

- ClientInput
  - `address` object, nullable
    - `country` string, nullable
    - `street` string, nullable
    - `zip` string, nullable
    - `city` string, nullable
    - `state` string, nullable
    - `exterior` string, nullable
    - `interior` string, nullable
    - `municipality` string, nullable
    - `neighborhood` string, nullable
  - `name` string, required
  - `company` string, nullable
  - `phone` string, nullable
  - `email` string, email, nullable, required
  - `bcc` string[]
  - `metadata` object, nullable
  - `legal_name` string, nullable
  - `tax_id` string, nullable
  - `use` string, nullable
  - `tax_system` string, nullable
  - `defaults` object
    - `keep_full_legal_name` boolean
    - `issue_automatic_invoices` boolean
    - `issue_invoiceable_receipts` boolean
  - `search` object, nullable — Search for an existing client before creating. If a match is found, the existing client is returned (or updated if `update: true`). This enables upsert-like behavior to avoid duplicate clients.
    - `on_key` string — The field to search on (e.g., 'tax_id', 'email', 'name')
    - `on_value` string — The value to match against the specified field
    - `update` boolean — If true and a match is found, update the existing client with the provided data. If false, return the existing client without modifications.

## Response `200`

Existing client found (when using `search` parameter)

- object
  - `message` string
  - `data` ApiPublicClient
    - `id` string, required — Unique client identifier
    - `address` ClientAddress, nullable
      - `country` string, nullable
      - `street` string, nullable
      - `zip` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `exterior` string, nullable
      - `interior` string, nullable
      - `municipality` string, nullable
      - `neighborhood` string, nullable
    - `name` string, nullable — Client name
    - `company` string, nullable — Client company name
    - `phone` string, nullable — Client phone number
    - `email` string, email, nullable, required — Client email address
    - `bcc` string[], nullable — BCC email addresses for client communications
    - `metadata` object, nullable — Additional metadata for the client
    - `is_valid` boolean, nullable — Whether the client data is valid
    - `from` string, required — Source of client creation
    - `legal_name` string, nullable — Legal name for tax purposes
    - `livemode` boolean, required — Whether this client is in live mode
    - `owner` string, required — User ID who owns this client
    - `tax_id` string, nullable — RFC (Tax ID) for Mexican tax compliance
    - `use` string, nullable — CFDI use code
    - `tax_system` string, nullable — SAT tax system code
    - `team` string, required — Team ID this client belongs to
    - `created_at` number, required — Unix timestamp of client creation
    - `efos` object, nullable — EFOS (SAT blacklist) validation status
      - `is_valid` boolean, nullable — Whether the client is valid according to SAT EFOS list
    - `defaults` object, nullable — Client default settings
      - `keep_full_legal_name` boolean, nullable — Keep full legal name in documents
      - `issue_automatic_invoices` boolean, nullable — Issue automatic invoices
      - `issue_invoiceable_receipts` boolean, nullable — Issue invoiceable receipts

## Other responses

- `201` — Client created successfully
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict - Multiple clients match the search criteria
- `500` — Internal Server Error

---

[API](https://skmtc.dev/disruptive-learning/apis/gigstack-api-v2.md) · [All operations](https://skmtc.dev/disruptive-learning/apis/gigstack-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/disruptive-learning/gigstack-api-v2/revisions/5cf53ffd7580/schema)