---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# (POST) Create partners
Create one or more partners. Each partner requires a name.
**Category:** Partners
## Endpoint

POST /api/partners

Create one or more partners. Accepts an array of partner objects. Each partner requires a name. Email and phone are optional.

**Endpoint**

```text
POST /api/partners
```

## Authentication

Requires authentication with an API key that has the partnersWrite scope.

## Request Body

The request body must be an array of partner objects. Each object represents one partner to create.

You can create up to 10,000 partners in a single request. Requests above 10,000 items are rejected.

| Parameter | Type | Required | Location | Description |
|---|---|---|---|---|
| name | string | Yes | body | The name of the partner. |
| email | string (email) | No | body | Email address of the partner. |
| phone | string | No | body | Phone number of the partner. |

> **Warning: Request Size**
> Ensure the request body contains at least one partner object.

## Status Codes

### 201

Partners created successfully.

**Request**

```bash
curl -X POST "https://hoko.to/api/partners" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Partner Name",
      "email": "partner@example.com",
      "phone": "+1234567890"
    }
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      name: "Partner Name",
      email: "partner@example.com",
      phone: "+1234567890"
    }
  ])
});
const partners = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Partner Name",
    "email": "partner@example.com",
    "phone": "+1234567890",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]
```

### 400

Invalid request body (missing required fields or invalid values).

**Request**

```bash
curl -X POST "https://hoko.to/api/partners" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
      {}
    ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {}
  ])
});
```

**Response**

```json
{
  "error": {
    "en": "Invalid request",
    "ar": "طلب غير صالح"
  }
}
```

### 401

Invalid or missing API key.

**Request**

```bash
curl -X POST "https://hoko.to/api/partners" \
  -H "Authorization: Bearer invalid_key"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "POST",
  headers: {
    "Authorization": "Bearer invalid_key"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Invalid API key",
    "ar": "مفتاح API غير صالح"
  }
}
```

### 403

API key does not have the required partnersWrite scope.

**Request**

```bash
curl -X POST "https://hoko.to/api/partners" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Missing required scopes",
    "ar": "الصلاحيات المطلوبة مفقودة"
  },
  "missingScopes": ["partnersWrite"]
}
```

### 429

Rate limit exceeded. Check X-RateLimit-* headers for details.

**Request**

```bash
curl -X POST "https://hoko.to/api/partners" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Rate limit exceeded",
    "ar": "تم تجاوز حد المعدل"
  },
  "retryAfter": 60
}
```

## Examples

**Request**

```bash
curl -X POST "https://hoko.to/api/partners" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Partner Name",
      "email": "partner@example.com",
      "phone": "+1234567890"
    }
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      name: "Partner Name",
      email: "partner@example.com",
      phone: "+1234567890"
    }
  ])
});
const partners = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Partner Name",
    "email": "partner@example.com",
    "phone": "+1234567890",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]
```

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)