# cURL Examples

Practical cURL command examples for integrating with the Zaits API using HTTP requests.

## Authentication

All API requests require authentication using your API key in the Authorization header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.zaits.net/v1/endpoint
```

## Face Recognition Examples

### Face Verification

```bash
# Basic face verification
curl -X POST https://api.zaits.net/v1/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image1=@./photo1.jpg" \
  -F "image2=@./photo2.jpg"
```

### Face Analysis

```bash
# Analyze face for age, gender, and emotion
curl -X POST https://api.zaits.net/v1/face/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@./face.jpg" \
  -F 'actions=["age", "gender", "emotion"]'
```

### Face Detection

```bash
# Detect all faces in an image
curl -X POST https://api.zaits.net/v1/face/detect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@./group_photo.jpg" \
  -F "min_confidence=0.8"
```

### Liveness Detection

```bash
# Check if face is live (anti-spoofing)
curl -X POST https://api.zaits.net/v1/face/liveness \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@./selfie.jpg" \
  -F "threshold=0.7"
```

## OCR Examples

### ID Extraction (INE)

```bash
# Extract INE with front only
curl -X POST https://api.zaits.net/v1/ocr/extract/id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "front=@./ine_frente.jpg" \
  -F "document_type=ine"
```

```bash
# Extract INE with front + back (recommended — enables MRZ validation)
curl -X POST https://api.zaits.net/v1/ocr/extract/id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "front=@./ine_frente.jpg" \
  -F "back=@./ine_reverso.jpg" \
  -F "document_type=ine"
```

```bash
# Extract passport
curl -X POST https://api.zaits.net/v1/ocr/extract/id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "front=@./pasaporte.jpg" \
  -F "document_type=passport"
```

```bash
# Extract ID + authenticity verification in one call
curl -X POST https://api.zaits.net/v1/ocr/extract/id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "front=@./ine_frente.jpg" \
  -F "back=@./ine_reverso.jpg" \
  -F "document_type=ine" \
  -F "include_authenticity=true"
```

### Address Proof Extraction

```bash
# CFE utility bill
curl -X POST https://api.zaits.net/v1/ocr/extract/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@./recibo_cfe.jpg" \
  -F "document_type=cfe"
```

```bash
# TELMEX phone bill
curl -X POST https://api.zaits.net/v1/ocr/extract/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@./recibo_telmex.jpg" \
  -F "document_type=telmex"
```

### Authenticity Verification (standalone)

```bash
# Verify document authenticity via Google Cloud Document AI
curl -X POST https://api.zaits.net/v1/ocr/verify/authenticity \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@./ine_frente.jpg"
```

## Document Signing Examples

### Create Signing Request

```bash
# Create document signing request
curl -X POST https://api.zaits.net/v1/signing/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "./contract.pdf",
    "signers": [
      {
        "name": "John Doe",
        "email": "john@example.com",
        "role": "client"
      },
      {
        "name": "Jane Smith",
        "email": "jane@company.com",
        "role": "provider"
      }
    ],
    "title": "Service Agreement",
    "message": "Please review and sign this agreement.",
    "expires_in": "30d"
  }'
```

### Check Signing Status

```bash
# Get signing status
curl -X GET https://api.zaits.net/v1/signing/status/DOC_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Download Signed Document

```bash
# Download signed document
curl -X GET https://api.zaits.net/v1/signing/download/DOC_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o "signed_document.pdf"
```

## Usage Analytics Examples

### Get Usage Summary

```bash
# Get current usage summary
curl -X GET https://api.zaits.net/v1/usage/summary \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get Detailed Statistics

```bash
# Get detailed usage statistics with filters
curl -X GET "https://api.zaits.net/v1/usage/stats?start_date=2024-01-01&end_date=2024-01-31&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Deployment Management Examples

### List Deployments

```bash
# List all deployments
curl -X GET https://api.zaits.net/api/deployments \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Create Deployment

```bash
# Create new deployment
curl -X POST https://api.zaits.net/api/deployments/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "acme-corp",
    "clientName": "ACME Corporation",
    "domain": "acme.yourapp.com",
    "platform": "web",
    "environment": "production",
    "config": {
      "primaryColor": "#007bff",
      "logo": "https://acme.com/logo.png",
      "companyName": "ACME Corp"
    }
  }'
```

### Get Deployment Status

```bash
# Check deployment status
curl -X GET https://api.zaits.net/api/deployments/DEPLOYMENT_ID/status \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Advanced cURL Techniques

### Using Variables and Scripts

```bash
#!/bin/bash

# Set your API key
API_KEY="your_api_key_here"
BASE_URL="https://api.zaits.net"

# Function to make API calls with error handling
make_api_call() {
    local endpoint=$1
    local method=$2
    local data=$3
    
    response=$(curl -s -w "\n%{http_code}" \
        -X "$method" \
        -H "Authorization: Bearer $API_KEY" \
        "$BASE_URL$endpoint" \
        $data)
    
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | head -n -1)
    
    if [ "$http_code" -eq 200 ]; then
        echo "Success: $endpoint"
        echo "$body" | jq .
    else
        echo "Error $http_code: $endpoint"
        echo "$body" | jq .
    fi
}

# Example usage
make_api_call "/v1/usage/summary" "GET"
```

### Batch Processing with cURL

```bash
#!/bin/bash

API_KEY="your_api_key_here"
IMAGE_DIR="./images"

# Process all images in directory
for image in "$IMAGE_DIR"/*.jpg; do
    echo "Analyzing: $(basename "$image")"
    
    curl -X POST https://api.zaits.net/v1/face/analyze \
        -H "Authorization: Bearer $API_KEY" \
        -F "image=@$image" \
        -F 'actions=["age", "gender", "emotion"]' \
        -o "results/$(basename "$image" .jpg)_analysis.json"
    
    sleep 1  # Rate limiting
done

echo "Batch processing complete!"
```

### Error Handling and Retries

```bash
#!/bin/bash

API_KEY="your_api_key_here"
MAX_RETRIES=3
RETRY_DELAY=2

make_api_call_with_retry() {
    local endpoint=$1
    local method=$2
    local data=$3
    local attempt=1
    
    while [ $attempt -le $MAX_RETRIES ]; do
        echo "Attempt $attempt/$MAX_RETRIES for $endpoint"
        
        response=$(curl -s -w "\n%{http_code}" \
            -X "$method" \
            -H "Authorization: Bearer $API_KEY" \
            "https://api.zaits.net$endpoint" \
            $data)
        
        http_code=$(echo "$response" | tail -n1)
        body=$(echo "$response" | head -n -1)
        
        case $http_code in
            200)
                echo "Success on attempt $attempt"
                echo "$body" | jq .
                return 0
                ;;
            429)
                echo "Rate limited. Waiting ${RETRY_DELAY}s..."
                sleep $RETRY_DELAY
                ;;
            5*)
                echo "Server error $http_code. Retrying..."
                sleep $RETRY_DELAY
                ;;
            *)
                echo "Client error $http_code. Not retrying."
                echo "$body" | jq .
                return 1
                ;;
        esac
        
        attempt=$((attempt + 1))
        RETRY_DELAY=$((RETRY_DELAY * 2))  # Exponential backoff
    done
    
    echo "Failed after $MAX_RETRIES attempts"
    return 1
}

# Example usage
make_api_call_with_retry "/v1/face/verify" "POST" "-F image1=@face1.jpg -F image2=@face2.jpg"
```

### File Upload with Progress

```bash
# Upload large ID image with progress bar
curl -X POST https://api.zaits.net/v1/ocr/extract/id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "front=@./ine_frente.jpg" \
  -F "document_type=ine" \
  --progress-bar \
  -o response.json
```

### JSON Response Processing with jq

```bash
#!/bin/bash

API_KEY="your_api_key_here"

# Get usage summary and extract specific fields
response=$(curl -s -X GET https://api.zaits.net/v1/usage/summary \
    -H "Authorization: Bearer $API_KEY")

# Check if request was successful
if echo "$response" | jq -e '.success' > /dev/null; then
    echo "Usage Statistics:"
    echo "   Current month calls: $(echo "$response" | jq -r '.summary.current_month_calls')"
    echo "   Remaining calls: $(echo "$response" | jq -r '.summary.remaining_calls')"
    echo "   Percent used: $(echo "$response" | jq -r '.summary.percent_used')%"
    
    echo "\nUsage by endpoint:"
    echo "$response" | jq -r '.by_endpoint | to_entries[] | "   \(.key): \(.value)"'
else
    echo "API request failed:"
    echo "$response" | jq -r '.error.message'
fi
```

### Configuration File for API Keys

```bash
# config.sh
API_KEY_PROD="sk_live_your_production_key"
API_KEY_TEST="sk_test_your_test_key"
BASE_URL="https://api.zaits.net"

# Set environment
ENVIRONMENT="test"  # or "prod"

if [ "$ENVIRONMENT" = "prod" ]; then
    API_KEY=$API_KEY_PROD
    echo "Using production environment"
else
    API_KEY=$API_KEY_TEST
    echo "Using test environment"
fi

export API_KEY
export BASE_URL
```

```bash
#!/bin/bash
# main_script.sh

# Load configuration
source ./config.sh

# Use the configured API key
curl -X GET "$BASE_URL/v1/usage/summary" \
    -H "Authorization: Bearer $API_KEY"
```

### Webhook Testing

```bash
# Test webhook endpoint
curl -X POST https://your-app.com/webhooks/zaits \
  -H "Content-Type: application/json" \
  -H "X-Zaits-Signature: sha256=your_signature" \
  -d '{
    "event": "document.signed",
    "data": {
      "document_id": "doc_123",
      "status": "completed",
      "signer": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }'
```

### Performance Testing

```bash
#!/bin/bash

# Load test with multiple concurrent requests
API_KEY="your_api_key_here"
CONCURRENCY=5
TOTAL_REQUESTS=20

echo "Starting load test with $CONCURRENCY concurrent requests..."

# Create temporary directory for results
mkdir -p load_test_results

# Function to make a single request
make_request() {
    local request_id=$1
    local start_time=$(date +%s.%N)
    
    response=$(curl -s -w "\n%{http_code}\n%{time_total}" \
        -X GET https://api.zaits.net/v1/usage/summary \
        -H "Authorization: Bearer $API_KEY")
    
    local end_time=$(date +%s.%N)
    local duration=$(echo "$end_time - $start_time" | bc)
    local http_code=$(echo "$response" | tail -n2 | head -n1)
    local time_total=$(echo "$response" | tail -n1)
    
    echo "Request $request_id: $http_code (${duration}s)" >> load_test_results/summary.txt
}

# Run concurrent requests
for i in $(seq 1 $TOTAL_REQUESTS); do
    make_request $i &
    
    # Limit concurrency
    if (( i % CONCURRENCY == 0 )); then
        wait
    fi
done

wait  # Wait for remaining requests

echo "Load test complete. Results in load_test_results/summary.txt"

# Calculate statistics
success_count=$(grep -c "200" load_test_results/summary.txt)
error_count=$((TOTAL_REQUESTS - success_count))

echo "Results:"
echo "   Total requests: $TOTAL_REQUESTS"
echo "   Successful: $success_count"
echo "   Errors: $error_count"
echo "   Success rate: $(echo "scale=2; $success_count * 100 / $TOTAL_REQUESTS" | bc)%"
```

***

**Next:** [Integration Patterns](/api/code-examples/integration-patterns.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://zaits.gitbook.io/api/code-examples/curl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.