# Quick Start Guide

Get up and running with the Zaits API in under 5 minutes. This guide will walk you through making your first API call.

## Before You Start

1. **Sign up** for a free account at [zaits.net](https://zaits.net)
2. **Generate your API key** (see [Authentication Guide](/api/getting-started/authentication.md))
3. **Choose your method**: cURL, JavaScript, Python, or our SDKs

## Your First API Call

Let's start with a simple face verification request to see if two photos contain the same person.

### Option 1: Using cURL

```bash
curl -X POST https://api.zaits.net/v1/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image1=@/path/to/first_photo.jpg" \
  -F "image2=@/path/to/second_photo.jpg"
```

### Option 2: Using JavaScript/Node.js

```javascript
const FormData = require("form-data");
const fs = require("fs");
const fetch = require("node-fetch");

async function verifyFaces() {
  const formData = new FormData();
  formData.append("image1", fs.createReadStream("first_photo.jpg"));
  formData.append("image2", fs.createReadStream("second_photo.jpg"));

  try {
    const response = await fetch("https://api.zaits.net/v1/face/verify", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
      body: formData,
    });

    const result = await response.json();
    console.log("Verification result:", result);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

verifyFaces();
```

### Option 3: Using Python

```python
import requests

# Verify faces
with open('first_photo.jpg', 'rb') as img1, open('second_photo.jpg', 'rb') as img2:
    response = requests.post(
        'https://api.zaits.net/v1/face/verify',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        files={
            'image1': img1,
            'image2': img2
        }
    )

    result = response.json()
    print(f"Match: {result['data']['verified']}")
    print(f"Confidence: {result['data']['confidence']}")
```

## Expected Response

All methods above will return a similar response:

```json
{
  "success": true,
  "data": {
    "verified": true,
    "confidence": 0.89,
    "distance": 0.32,
    "threshold": 0.6,
    "processing_time": 1.2
  }
}
```

### Understanding the Response

| Field             | Description                                      |
| ----------------- | ------------------------------------------------ |
| `verified`        | `true` if faces match, `false` if they don't     |
| `confidence`      | Confidence score (0-1, higher is more confident) |
| `distance`        | Face distance metric (lower means more similar)  |
| `threshold`       | The threshold used for verification decision     |
| `processing_time` | Time taken to process (in seconds)               |

## Try More APIs

Now that you've made your first call, try these other popular endpoints:

### OCR — ID Extraction

Extract structured data from a Mexican INE or passport:

```bash
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"
```

### OCR — Address Proof

Extract data from a CFE, TELMEX, or IZZI utility bill:

```bash
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"
```

### Face Analysis

Get age, gender, and emotion analysis:

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

### Face Matching (1:1 and 1:n)

Enroll faces and search for matches across your database:

**Enroll a face:**

```bash
curl -X POST https://api.zaits.net/v1/face-matching/enroll \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@user_photo.jpg" \
  -F "enrollment_source=registration" \
  -F "metadata={\"label\":\"Employee ID Badge\"}"
```

**Search for matches (1:n identification):**

```bash
curl -X POST https://api.zaits.net/v1/face-matching/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@unknown_person.jpg" \
  -F "threshold=0.6" \
  -F "limit=10"
```

**Verify against specific user (1:1 verification):**

```bash
curl -X POST https://api.zaits.net/v1/face-matching/verify/USER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@person_to_verify.jpg" \
  -F "threshold=0.6"
```

### Create a Signing Document

Create a document for electronic signatures:

```bash
curl -X POST https://api.zaits.net/v1/signing/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F "title=Service Agreement" \
  -F "signers=[{\"email\":\"john@example.com\",\"name\":\"John Doe\"}]"
```

## Common First-Time Issues

### "Invalid API Key" Error

**Problem:** Your API key is incorrect or missing **Solution:**

1. Double-check your API key in the dashboard
2. Ensure you're using the correct key format (`sk_...`)
3. Make sure the `Authorization: Bearer` header is included

### "File Too Large" Error

**Problem:** Image file exceeds the 5MB limit **Solution:**

1. Compress your image files
2. Use formats like JPEG with reasonable quality settings
3. Resize images to appropriate dimensions (max 2048x2048 recommended)

### "Unsupported File Type" Error

**Problem:** File format is not supported **Solution:**

1. Use supported formats: JPG, JPEG, PNG, WebP
2. For documents: PDF, JPG, PNG
3. Check the file extension matches the actual file type

### "Permission Denied" Error

**Problem:** Your API key doesn't have the required permissions **Solution:**

1. Go to your dashboard → API Keys
2. Edit your key and enable "Write" permissions
3. Save changes and retry your request

## Rate Limits for New Users

Free accounts have these limits:

* **20 credits per month**
* **5MB max file size**

You'll see these headers in responses:

```http
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 18
X-RateLimit-Reset: 1742860800
X-RateLimit-Tier: free
X-RateLimit-Billing-Method: credits
X-Credit-Balance: 18
X-Credit-Cost: 2
```

## Next Steps

**Congratulations!** You've made your first Zaits API call. Here's what to explore next:

### Learn the APIs

* [Face Recognition API](/api/api-reference/face.md) - Face verification, analysis, and detection
* [Face Matching API](/api/api-reference/face-matching.md) - Biometric identification (1:1 and 1:n)
* [OCR API](/api/api-reference/ocr.md) - Extract text from any document
* [Document Signing](/api/api-reference/document-signing.md) - E-signature workflows
* [Mexican Government Services](/api/api-reference/mexico-services.md) - CURP and INE validation

### Integration Guides

* [Webhook Setup](/api/api-reference/webhooks.md) - Get real-time notifications
* [Usage Monitoring](/api/api-reference/usage-analytics.md) - Track your API usage
* [Best Practices](/api/guides/best-practices.md) - Optimization tips

### Code Examples

* [JavaScript Examples](/api/code-examples/javascript.md) - Frontend and backend examples
* [Python Examples](/api/code-examples/python.md) - Scripts and web app integration
* [Integration Patterns](/api/code-examples/integration-patterns.md) - Common use cases

***

**Ready to build something amazing?** Start integrating Zaits into your application!


---

# 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/getting-started/quickstart.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.