---
updatedAt: 2026-01-28T13:27:43.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Auto-Assign

Automate shift assignments using the auto-assign feature. This considers user qualifications, availability, limitations, and open shift requests to optimally distribute shifts.

## How Auto-Assign Works

1. **Submit a request** with shift IDs to auto-assign
2. **Processing occurs** asynchronously (may take several minutes)
3. **Poll the status** endpoint to check results
4. **Review results** showing which shifts were assigned or unassigned

***

## Create Auto-Assign Request

Initiate an auto-assign request for specified shifts.

### Request Body

| Field                    | Type    | Required | Default | Description                     |
| :----------------------- | :------ | :------- | :------ | :------------------------------ |
| shiftsIds                | array   | Yes      | -       | Shift IDs to auto-assign        |
| isForceQualification     | boolean | No       | true    | Consider user qualifications    |
| isForceUnavailability    | boolean | No       | true    | Consider user unavailabilities  |
| isForceLimitations       | boolean | No       | true    | Consider user limitations       |
| isForceOpenShiftRequests | boolean | No       | false   | Assign only to shift requesters |

### Example

```bash
curl --request POST \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts/auto-assign \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "shiftsIds": [
      "6784dacb3c07733b0a849f49",
      "6784dacb3c07733b0a849f50",
      "6784dacb3c07733b0a849f51"
    ],
    "isForceQualification": true,
    "isForceUnavailability": true,
    "isForceLimitations": true,
    "isForceOpenShiftRequests": false
  }'
```

### Response

```json
{
  "requestId": "abc123...",
  "data": {
    "autoAssignRequestId": "12345678"
  }
}
```

> ⚠️ Warning
>
> All shifts in a request must be within the same work week (based on scheduler settings). If shifts span multiple weeks, split them into separate requests.

***

## Get Auto-Assign Status

Check the status of an auto-assign request.

### Path Parameters

| Parameter           | Type    | Description                     |
| :------------------ | :------ | :------------------------------ |
| autoAssignRequestId | integer | Request ID from create response |

### Example

```bash
curl --request GET \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts/auto-assign/12345678 \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response (Processing)

```json
{
  "requestId": "abc123...",
  "data": {
    "autoAssignRequestId": "12345678",
    "status": "processing",
    "assignedShiftIds": null,
    "unassignedShiftIds": null
  }
}
```

### Response (Completed)

```json
{
  "requestId": "abc123...",
  "data": {
    "autoAssignRequestId": "12345678",
    "status": "completed",
    "assignedShiftIds": [
      "6784dacb3c07733b0a849f49",
      "6784dacb3c07733b0a849f50"
    ],
    "unassignedShiftIds": [
      "6784dacb3c07733b0a849f51"
    ]
  }
}
```

### Response Fields

| Field               | Type   | Description                            |
| :------------------ | :----- | :------------------------------------- |
| autoAssignRequestId | string | Request identifier                     |
| status              | string | `processing`, `completed`, or `failed` |
| assignedShiftIds    | array  | Successfully assigned shift IDs        |
| unassignedShiftIds  | array  | Shift IDs that couldn't be assigned    |

***

## Configuration Options

### isForceQualification

When `true` (default), only assigns users who have the required qualifications for the shift. Set to `false` to ignore qualification requirements.

### isForceUnavailability

When `true` (default), respects user unavailabilities and approved time-off. Set to `false` to potentially assign users during their marked unavailable periods.

### isForceLimitations

When `true` (default), respects user work limitations (max hours, consecutive days, etc.). Set to `false` to ignore these constraints.

### isForceOpenShiftRequests

When `true`, only assigns open shifts to users who specifically requested them. When `false` (default), prioritizes requesters first, then assigns remaining shifts to other eligible users.

***

## Polling Strategy

Auto-assign processing can take several minutes. Recommended polling approach:

```
1. Submit request
2. Wait 5 seconds
3. Check status
4. If still processing, wait 10 seconds
5. Continue with exponential backoff (max 60 seconds)
6. Timeout after 5 minutes
```

### Example Polling Logic

```javascript
async function pollAutoAssign(schedulerId, requestId, maxAttempts = 30) {
  let delay = 5000; // Start with 5 seconds
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.connecteam.com/scheduler/v1/schedulers/${schedulerId}/shifts/auto-assign/${requestId}`,
      { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
    );
    
    const result = await response.json();
    
    if (result.data.status !== 'processing') {
      return result.data;
    }
    
    await new Promise(r => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 60000); // Max 60 seconds
  }
  
  throw new Error('Auto-assign timed out');
}
```

***

## Error Handling

### 400 Bad Request

* **"No shift IDs provided"**: Request body must include `shiftsIds` array
* **"All shifts must be within the same week period"**: Split shifts across week boundaries
* **"No valid shifts found for the provided IDs"**: Verify shift IDs exist

### 409 Conflict

* **"There is already an auto assign request in progress"**: Wait for existing request to complete before starting another

***

## Best Practices

1. **Batch by week**: Group shifts within the same work week
2. **Poll efficiently**: Use exponential backoff to avoid rate limits
3. **Handle partial success**: Some shifts may remain unassigned
4. **Review unassigned**: Check why shifts couldn't be assigned (missing qualifications, no available users, etc.)
5. **Test with small batches**: Start with a few shifts to verify configuration

***

[API Reference](https://developer.connecteam.com/reference/)