# Zapini API — Contacts & Scheduled Messages

**Version:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Authentication

All endpoints require a Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Generate API tokens in your admin panel under **API Docs → Manage Tokens**.

---

## Contacts

### GET /contacts

List contacts.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| instance_id | string | Instance UUID |
| search | string | Search by name, number, email or company |
| is_group | boolean | Filter groups |
| sort | string | Sort field |
| dir | string | Direction (asc, desc) |
| per_page | integer | Items per page |

---

### POST /contacts

Create a new contact.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instance_id | string | Yes | Instance UUID |
| phone_number | string | Yes | Phone number |
| first_name | string | No | First name |
| last_name | string | No | Last name |
| display_name | string | No | Display name |
| email | string | No | Email |
| company | string | No | Company |
| job_title | string | No | Job title |
| notes | string | No | Notes |
| custom_fields | object | No | Custom fields |

---

### POST /contacts/import

Bulk import contacts.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instance_id | string | Yes | Instance UUID |
| contacts | array | Yes | Contact list (max 1000) |

**Example:**

```bash
curl -X POST https://zapini.app/api/v1/contacts/import \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "contacts": [
      {
        "phone_number": "+15551234567",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com"
      },
      {
        "phone_number": "+15559876543",
        "first_name": "Jane",
        "company": "XYZ Corp"
      }
    ]
  }'
```

---

### GET /contacts/{uuid}

Returns contact details.

---

### PATCH /contacts/{uuid}

Update a contact.

---

### DELETE /contacts/{uuid}

Delete a contact.

---

### GET /contacts/{uuid}/messages

List messages exchanged with a contact.

---

## Scheduled Messages

### GET /scheduled

List scheduled messages.

**Query Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| instance_id | string | Instance UUID |
| from | datetime | Start date |
| to | datetime | End date |
| per_page | integer | Items per page |

---

### POST /scheduled

Schedule a new message.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instance_id | string | Yes | Instance UUID |
| recipient | string | Yes* | Recipient number |
| contact_id | string | Yes* | Contact UUID (alternative to recipient) |
| message | string | Yes | Message content |
| scheduled_at | datetime | Yes | Send date/time |
| media_url | string | No | Media URL |
| media_type | string | No | Media type |

*One of the two is required: recipient or contact_id

---

### GET /scheduled/{uuid}

Returns scheduled message details.

---

### PATCH /scheduled/{uuid}

Update a pending scheduled message.

---

### DELETE /scheduled/{uuid}

Cancel a scheduled message.

---

### POST /scheduled/{uuid}/send-now

Send the scheduled message immediately.

---

*Generated by Zapini — https://zapini.app*