Clients API Guide

Manage clients with fiscal information for Mexican tax compliance. The Clients API handles customer data, RFC validation, EFOS checking, and SAT compliance requirements.

Overview

Clients are the foundation of your invoicing system. Each client contains fiscal information required for Mexican tax compliance, including RFC (tax ID), tax system, and address information.

Key Features

RFC Validation - Automatic tax ID validation against SAT

EFOS Checking - Blacklist validation for compliance

Address Management - Mexican address structure support

Metadata Support - Custom fields for additional data

Duplicate Prevention - Search for existing clients before creating (upsert-like behavior)

Auto-creation - Create clients during invoice/payment flow

Endpoints

List Clients

Retrieve a paginated list of clients with filtering and search capabilities.

Query Parameters:

Parameter	Type	Description
`limit`	integer (1-100)	Number of results per page (default: 10)
`next`	string	Pagination cursor for next page
`team`	string	gigstack Connect: Target team ID
`order_by`	string	Field to sort by (e.g., `created_at`)
`sort`	string	Sort direction (`asc`, `desc`)
`created_gte`	integer	Filter by creation date (greater than or equal to timestamp)
`created_lte`	integer	Filter by creation date (less than or equal to timestamp)
`metadata.{key}`	string	Filter by metadata field using dot notation (e.g., `metadata.external_id=EXT-123`)
`metadata_{key}`	string	Filter by metadata field using underscore notation (e.g., `metadata_external_id=EXT-123`)
`page`	integer	Page number for pagination when using metadata filters (default: 1)

Metadata Filtering:

You can filter clients by any metadata key using either dot notation or underscore notation. Both formats are equivalent and supported:

The metadata filtering uses Typesense search for efficient querying without requiring Firestore indexes. When using metadata filters, pagination is controlled via the page parameter instead of the next cursor.

Example Requests:

Example Response:

{
    "message": "Clients retrieved successfully",
    "data": [
        {
            "id": "client_1234567890",
            "name": "Juan Pérez García",
            "company": "Empresa SA de CV",
            "email": "juan.perez@ejemplo.com",
            "tax_id": "PEGJ800101ABC",
            "tax_system": "601",
            "livemode": true,
            "created_at": 1677651234,
            "efos": {
                "is_valid": true
            }
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Client

Create a new client with fiscal information.

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 (200).

If a match is found and search.update is true: Updates the existing client with the provided data and returns it (200).

If no match is found: Creates a new client (201).

If multiple matches are found: Returns a 409 Conflict error with the list of matching client IDs.

Request Body:

{
    "name": "Juan Pérez García",
    "company": "Empresa SA de CV",
    "email": "juan.perez@ejemplo.com",
    "phone": "+52 55 1234 5678",
    "tax_id": "PEGJ800101ABC",
    "tax_system": "601",
    "use": "P01",
    "legal_name": "Juan Pérez García",
    "address": {
        "country": "MEX",
        "street": "Av. Insurgentes Sur",
        "exterior": "123",
        "interior": "4B",
        "neighborhood": "Del Valle",
        "municipality": "Benito Juárez",
        "city": "Ciudad de México",
        "state": "CDMX",
        "zip": "03100"
    },
    "metadata": {
        "custom_field": "value"
    },
    "search": {
        "on_key": "tax_id",
        "on_value": "PEGJ800101ABC",
        "update": false
    }
}

Search Parameters:

Parameter	Type	Description
`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. Default: `false`

Example Request (Simple):

Example Request (With Duplicate Prevention):

Response Codes:

Code	Description
`200`	Existing client found (when using `search`)
`201`	Client created successfully
`409`	Multiple clients match the search criteria

Get Client

Retrieve a specific client by ID.

Example Request:

Update Client

Update an existing client's information.

Example Request:

Delete Client

Delete a specific client.

Example Request:

Validate Client

Validate client's fiscal information against SAT.

Example Request:

Stamp Pending Receipts

Stamp all pending receipts for a client.

Example Request:

Customer Portal Access

Get access token for client customer portal.

Client Structure

Required Fields

None - All fields are optional for maximum flexibility

Important Fields

tax_id (string) - RFC for Mexican tax compliance

tax_system (string) - SAT tax system code (e.g., "601", "612")

use (string) - Default CFDI use code (e.g., "P01", "G03")

email (string) - Email for invoice delivery

Tax System Codes

Common SAT tax system codes:

601 - General de Ley Personas Morales

612 - Persona Física con Actividades Empresariales

621 - Incorporación Fiscal

622 - Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras

623 - Opcional para Grupos de Sociedades

624 - Coordinados

625 - Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas

626 - Régimen Simplificado de Confianza

CFDI Use Codes

Common CFDI use codes:

P01 - Por definir

G01 - Adquisición de mercancías

G02 - Devoluciones, descuentos o bonificaciones

G03 - Gastos en general

I01 - Construcciones

I02 - Mobiliario y equipo de oficina por inversiones

I03 - Equipo de transporte

I04 - Equipo de computo y accesorios

I05 - Dados, troqueles, moldes, matrices y herramental

I06 - Comunicaciones telefónicas

I07 - Comunicaciones satelitales

I08 - Otra maquinaria y equipo

Search and Duplicate Prevention

The search parameter enables upsert-like behavior when creating clients. This is useful for integrations that may send the same client multiple times.

Direct Client Creation (POST /clients)

{
    "name": "Juan Pérez García",
    "email": "juan.perez@ejemplo.com",
    "tax_id": "PEGJ800101ABC",
    "tax_system": "601",
    "search": {
        "on_key": "tax_id",
        "on_value": "PEGJ800101ABC",
        "update": false
    }
}

Within Invoices or Payments

When creating invoices or payments, you can search for existing clients inline:

{
    "client": {
        "search": {
            "on_key": "tax_id",
            "on_value": "PEGJ800101ABC",
            "update": true
        },
        "name": "Juan Pérez García",
        "email": "juan.perez@ejemplo.com",
        "tax_id": "PEGJ800101ABC",
        "tax_system": "601"
    }
}

Search Behavior

Scenario	Result
Single match found, `update: false`	Returns existing client unchanged
Single match found, `update: true`	Updates client with provided data, returns updated client
No match found	Creates new client automatically
Multiple matches found	Returns 409 Conflict with list of matching client IDs

Example: Update Existing Client on Match

This will find the client with tax_id: PEGJ800101ABC and update their email to nuevo.email@ejemplo.com.

Validation and Compliance

RFC Validation

Automatic format validation

SAT registry verification

EFOS Checking

Blacklist validation against SAT's EFOS list

Automatic status updates

Compliance reporting

Address Validation

Mexican postal code verification

Address completeness checking

Best Practices

Always include tax_id for Mexican clients

Set appropriate tax_system based on client type

Use metadata for custom business logic

Validate clients before important transactions

Keep addresses updated for compliance

Use search functionality to avoid duplicates

Invoices API - Create invoices for clients

Payments API - Process payments from clients

Teams API - Manage team settings that affect clients

Error Handling

Common error scenarios:

Invalid RFC Format

{
    "message": "Invalid tax_id format",
    "error": "RFC must be 12 or 13 characters"
}

Client Not Found

{
    "message": "Client not found",
    "error": "The specified client does not exist"
}

EFOS Validation Failed

{
    "message": "Client failed EFOS validation",
    "error": "Client is on SAT blacklist"
}

Multiple Clients Match Search Criteria (409 Conflict)

When using the search parameter and multiple clients match the criteria:

{
    "success": false,
    "error": {
        "code": "resource_conflict",
        "message": "Multiple clients found matching tax_id=\"PEGJ800101ABC\". Please use a more specific search criteria.",
        "details": ["client_1234567890", "client_0987654321"]
    }
}

Resolution: Use one of the returned client IDs directly, or use a more specific search key (e.g., combine with email or use the client id directly).

For additional assistance, contact support@gigstack.io

Clients API Guide

Clients API Guide#

Overview#

Key Features#

Endpoints#

List Clients#

Create Client#

Get Client#

Update Client#

Delete Client#

Validate Client#

Stamp Pending Receipts#

Customer Portal Access#

Client Structure#

Required Fields#

Important Fields#

Tax System Codes#

CFDI Use Codes#

Search and Duplicate Prevention#

Direct Client Creation (POST /clients)#

Within Invoices or Payments#

Search Behavior#

Example: Update Existing Client on Match#

Validation and Compliance#

RFC Validation#

EFOS Checking#

Address Validation#

Best Practices#

Related Resources#

Error Handling#

Invalid RFC Format#

Client Not Found#

EFOS Validation Failed#

Multiple Clients Match Search Criteria (409 Conflict)#

Clients API Guide

Overview

Key Features

Endpoints

List Clients

Create Client

Get Client

Update Client

Delete Client

Validate Client

Stamp Pending Receipts

Customer Portal Access

Client Structure

Required Fields

Important Fields

Tax System Codes

CFDI Use Codes

Search and Duplicate Prevention

Direct Client Creation (POST /clients)

Within Invoices or Payments

Search Behavior

Example: Update Existing Client on Match

Validation and Compliance

RFC Validation

EFOS Checking

Address Validation

Best Practices

Related Resources

Error Handling

Invalid RFC Format

Client Not Found

EFOS Validation Failed

Multiple Clients Match Search Criteria (409 Conflict)