---
**📚 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.
---
# (PUT) Update/Upsert partners
Update existing partners or create new ones with upsert operations.
**Category:** Partners
## Endpoint

PUT /api/partners

Upsert (update or insert) one or more partners. If id is provided, the partner is updated. If the ID does not exist, the request fails. To create new partners, omit the id field.

**Endpoint**

```text
PUT /api/partners
```

## Authentication

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

## Request Body

The request body must be an array of partner objects. Include the id field to update an existing partner, or omit it to create a new one.

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

| Parameter | Type | Required | Location | Description |
|---|---|---|---|---|
| id | string (UUID) | Yes | body | Required when updating. Omit to create a new partner. If provided, it must exist in your workspace or the request fails. |
| name | string | No | body | The name of the partner. Required when creating a new partner (no id). Optional when updating. |
| email | string (email) | No | body | Email address of the partner. Optional for both create and update operations. |
| phone | string | No | body | Phone number of the partner. Optional for both create and update operations. |

> **Info: Update Behavior**
> When updating, only the fields you include are changed. Omitted fields keep their current values. To clear a value, send it explicitly as null.

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

## Status Codes

### 200

Partners updated or created successfully.

**Request**

```bash
curl -X PUT "https://hoko.to/api/partners" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Updated Partner",
      "email": "updated@example.com"
    }
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      id: "550e8400-e29b-41d4-a716-446655440000",
      name: "Updated Partner",
      email: "updated@example.com"
    }
  ])
});
const partners = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Partner",
    "email": "updated@example.com",
    "phone": null,
    "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 PUT "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: "PUT",
  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 PUT "https://hoko.to/api/partners" \
  -H "Authorization: Bearer invalid_key"
```

**Request**

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

**Response**

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

### 403

API key does not have the required linksWrite scope.

**Request**

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

**Request**

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

**Response**

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

### 429

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

**Request**

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

**Request**

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

**Response**

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

## Examples

**Request**

```bash
curl -X PUT "https://hoko.to/api/partners" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Updated Partner",
      "email": "updated@example.com"
    }
  ]'
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/partners", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify([
    {
      id: "550e8400-e29b-41d4-a716-446655440000",
      name: "Updated Partner",
      email: "updated@example.com"
    }
  ])
});
const partners = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Partner",
    "email": "updated@example.com",
    "phone": null,
    "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)