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

Example

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

{
  "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

Example

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)

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

Response (Completed)

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

Response Fields

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

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