# 6. Batch Operations

### 6.1 Batch Request
**Status:** VERIFIED - Works with Beta Teams Admin APIs

| Property | Value |
|----------|-------|
| **Endpoint** | `POST /beta/$batch` |
| **API Version** | Beta (REQUIRED for Teams Admin APIs) |
| **Permission** | Same as individual requests |
| **Max Requests** | 20 per batch |

**Documentation:** [JSON Batching](https://learn.microsoft.com/en-us/graph/json-batching)

**Critical Finding - Version Compatibility:**

| Batch Endpoint | Can Include | Cannot Include |
|----------------|-------------|----------------|
| `v1.0/$batch` | v1.0 endpoints only | Beta endpoints (returns 405) |
| `beta/$batch` | Beta endpoints | - |

**For Teams Phone CLI:** Since all `/admin/teams/*` endpoints are beta-only, we MUST use `https://graph.microsoft.com/beta/$batch`.

**Request Format:**
```json
POST https://graph.microsoft.com/beta/$batch
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "/admin/teams/userConfigurations/user-id-1"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/admin/teams/userConfigurations/user-id-2"
    },
    {
      "id": "3",
      "method": "GET",
      "url": "/admin/teams/telephoneNumberManagement/numberAssignments?$filter=telephoneNumber eq '+12065551234'"
    }
  ]
}
```

**Required Properties per Request:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | String | **Yes** | Unique identifier for correlating responses |
| `method` | String | **Yes** | HTTP method (GET, POST, etc.) |
| `url` | String | **Yes** | Relative URL (not full URL) |
| `headers` | Object | When body present | Headers including Content-Type |
| `body` | Object | For POST/PATCH | Request body |
| `dependsOn` | String[] | No | IDs of requests that must complete first |

**Response Format:**
```json
{
  "responses": [
    {
      "id": "1",
      "status": 200,
      "headers": { "Content-Type": "application/json" },
      "body": { /* userConfiguration data */ }
    },
    {
      "id": "2",
      "status": 200,
      "body": { /* userConfiguration data */ }
    },
    {
      "id": "3",
      "status": 200,
      "body": { "value": [ /* numberAssignment data */ ] }
    }
  ]
}
```

**Error Handling:**
- Batch response `200` = batch parsed successfully (not individual success)
- Individual requests have their own status codes
- Partial failures are possible - one failure doesn't stop others
- Responses may arrive in different order than requests (use `id` to correlate)

| Status | Meaning |
|--------|---------|
| `200` | Request succeeded |
| `403` | Insufficient permissions |
| `405` | Method not allowed (version mismatch) |
| `424` | Failed dependency (dependsOn failed) |
| `429` | Throttling limit exceeded |

**Use Cases for CLI:**
1. **Bulk user lookup** - Fetch multiple userConfigurations in one call
2. **Number search** - Look up multiple phone numbers simultaneously
3. **Export operations** - Reduce API calls when exporting large datasets

**Limitations:**
- Cannot mix v1.0 and beta endpoints in same batch
- 20 requests max per batch
- Each request still counts against throttling limits
- Sequential dependencies via `dependsOn` reduce parallelism benefits

**Contract Status:** [x] Verified [x] Documented [ ] Tested

---

