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

# Contacts API

> Contact management endpoints

# Contacts API

Manage contacts associated with companies.

## Endpoints

| Method | Path             | Auth     | Description                 |
| ------ | ---------------- | -------- | --------------------------- |
| GET    | `/contacts`      | Required | List contacts for a company |
| GET    | `/contacts/{id}` | Public   | Get a contact by ID         |
| POST   | `/contacts`      | Public   | Create a contact            |
| PATCH  | `/contacts/{id}` | Public   | Update a contact            |
| DELETE | `/contacts/{id}` | Required | Delete a contact            |

***

## List Contacts

Returns all contacts for a specific company. Requires authentication and company ownership.

```bash theme={null}
GET /contacts?company_id={uuid}
```

### Query Parameters

| Parameter    | Type | Required | Default | Description                   |
| ------------ | ---- | -------- | ------- | ----------------------------- |
| `company_id` | uuid | **Yes**  | —       | Company ID to filter contacts |
| `skip`       | int  | No       | `0`     | Number of records to skip     |
| `limit`      | int  | No       | `100`   | Max records to return         |

### Response `200 OK`

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "company_id": "7b3f1c2d-4e5a-6f7b-8c9d-0e1f2a3b4c5d",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@acme.com",
    "phone": "+91-9876543210",
    "designation": "Sales Manager",
    "is_primary": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
```

### Errors

| Status | Detail                                                   |
| ------ | -------------------------------------------------------- |
| `403`  | Not enough permissions to access this company's contacts |

***

## Get Contact

Fetch a single contact by ID. No authentication required.

```bash theme={null}
GET /contacts/{contact_id}
```

### Response `200 OK`

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "company_id": "7b3f1c2d-4e5a-6f7b-8c9d-0e1f2a3b4c5d",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@acme.com",
  "phone": "+91-9876543210",
  "designation": "Sales Manager",
  "is_primary": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

### Errors

| Status | Detail            |
| ------ | ----------------- |
| `404`  | Contact not found |

***

## Create Contact

Create a new contact. Public endpoint — no authentication required.

```bash theme={null}
POST /contacts
```

### Request Body

```json theme={null}
{
  "company_id": "7b3f1c2d-4e5a-6f7b-8c9d-0e1f2a3b4c5d",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@acme.com",
  "phone": "+91-9876543210",
  "designation": "Sales Manager",
  "is_primary": false
}
```

### Fields

| Field         | Type    | Required | Description                                |
| ------------- | ------- | -------- | ------------------------------------------ |
| `company_id`  | uuid    | No       | Associate with a company                   |
| `first_name`  | string  | **Yes**  | First name                                 |
| `last_name`   | string  | No       | Last name                                  |
| `email`       | string  | **Yes**  | Email address                              |
| `phone`       | string  | No       | Phone number                               |
| `designation` | string  | No       | Job title                                  |
| `is_primary`  | boolean | No       | Mark as primary contact (default: `false`) |

### Response `201 Created`

Returns the created contact object (same shape as Get Contact response).

### Errors

| Status | Detail            |
| ------ | ----------------- |
| `400`  | Company not found |

***

## Update Contact

Partially update an existing contact. All fields are optional.

```bash theme={null}
PATCH /contacts/{contact_id}
```

### Request Body

```json theme={null}
{
  "designation": "Head of Sales",
  "is_primary": true
}
```

### Response `200 OK`

Returns the updated contact object.

### Errors

| Status | Detail            |
| ------ | ----------------- |
| `404`  | Contact not found |

***

## Delete Contact

Permanently delete a contact.

```bash theme={null}
DELETE /contacts/{contact_id}
```

### Response `204 No Content`

No body returned.

### Errors

| Status | Detail            |
| ------ | ----------------- |
| `404`  | Contact not found |

***

## Rate Limits

| Endpoint            | Limit             |
| ------------------- | ----------------- |
| `POST /contacts`    | 60/min (public)   |
| All other endpoints | 120/min (general) |