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

# Create a customer once

> Save the customer, keep the ID, and find the same record on the next request.

**Case:** your application has customer `customer-1042`. You want one corresponding
client in gigstack, even when a job runs again.

Complete the [quickstart](/quickstart) first. These commands use `GIGSTACK_BASE_URL`
and `GIGSTACK_API_KEY` from that page, plus `jq` to read JSON responses.

## Create or find the customer

```bash theme={null}
set -euo pipefail
curl --fail-with-body "$GIGSTACK_BASE_URL/clients" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Workshop customer",
    "email": "customer@example.com",
    "metadata": {"external_id": "customer-1042"},
    "search": {
      "on_key": "metadata.external_id",
      "on_value": "customer-1042",
      "update": false
    }
  }' > client.json

CLIENT_ID=$(jq -er '.data.id' client.json)
export CLIENT_ID
```

**Expected:** `201` for a new client; `200` when a matching client already exists.
Both responses contain `data.id`. With `update: false`, finding the customer does not
change the stored record. If several records match, resolve the conflict instead of
selecting an arbitrary customer.

Use a stable identifier from your own system. This lookup helps with repeat jobs;
it is not a promise that simultaneous create requests are atomic.

## Add fiscal details when you need to invoice

A contact can exist without fiscal data. Choose the **issuing country** before adding
fiscal fields: [Mexico](/countries/mexico) or [Colombia](/countries/colombia).
The table and test fixture below apply to **Mexico**. Before issuing a Mexican CFDI, collect:

| API field | Ask the customer for |
| - | - |
| `tax_id` | RFC |
| `legal_name` | Registered name or razón social |
| `tax_system` | Régimen fiscal code |
| `address.zip` | Fiscal postal code, as a string |
| `address.country` | `MEX` for this Mexican recipient example |
| `use` | Intended Uso CFDI |

A successful client creation is **not proof that its fiscal details were validated**.
Inspect `data.fiscal_validation` when returned. A contact-only creation can report
`status: "skipped"` because required fiscal fields were not supplied.

The [SAT lists the required recipient data](https://www.gob.mx/sat/prensa/aclara-sat-que-constancia-de-situacion-fiscal-no-es-requisito-para-emitir-factura-04-2026?idiom=es).
Customers can supply those values directly; the CSF document itself is not mandatory.

Next: [build an invoice draft](/recipes/invoice).
For all fields and customer search options, read the [client reference](/reference/createClients).

## Test fiscal customer

For the tutorial in a configured Mexican **test** environment, this synthetic fiscal
fixture completed the preview and stamping flow. Use real customer data for real invoices;
these sample fiscal values are not a substitute for collecting it.

```bash theme={null}
curl --fail-with-body "$GIGSTACK_BASE_URL/clients" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Documentation fiscal example",
    "legal_name": "ESCUELA KEMPER URGATE",
    "tax_id": "EKU9003173C9",
    "tax_system": "601",
    "use": "G03",
    "address": {"country": "MEX", "zip": "42501"},
    "metadata": {"external_id": "fiscal-example-1042"},
    "search": {"on_key": "metadata.external_id", "on_value": "fiscal-example-1042", "update": false}
  }' > fiscal-client.json

CLIENT_ID=$(jq -er '.data.id' fiscal-client.json)
export CLIENT_ID
jq '{id: .data.id, livemode: .data.livemode}' fiscal-client.json
```

Confirm `livemode: false` before continuing to [the invoice recipe](/recipes/invoice).
Complete [issuer setup](/concepts/issuer-setup#mexico) for the provider and test certificates
before stamping.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.