2026/11/16 - Amazon Connect Scheduling - 6 new api methods
Changes This release adds APIs for Amazon Connect Scheduling. Use them to create, get, approve, reject, and cancel agent time off requests, and to set agent time off balances.
Creates a time off request for a user. You don't provide a status, because Connect Customer owns the request lifecycle. To get the decided status, call GetTimeOff or use the time off state-change events.
ApprovalType controls who approves the request. You can specify one of the following values:
AWAIT_APPROVAL: the request waits in AWAITING_APPROVAL until you call ApproveTimeOff or RejectTimeOff. Rule evaluation and the overlap check run at approval, not at creation. A waiting request doesn't reserve its window, so another request for the same window can be approved first.
AUTOMATIC: Connect Customer evaluates the rules (time off balances and group allowances) and decides the request. The request can be PENDING while Connect Customer decides, and then ends APPROVED or REJECTED. If it overlaps another time off request for the user, the requested time off ends REJECTED with CONFLICTING_TIME_OFF_REQUEST. It also ends REJECTED if it overlaps overtime or voluntary time off. If the whole window is in the past, Connect Customer records failed rules as WARNING and doesn't reject the request, whatever the RuleFailureAction.
The staffing group's Supervisor approval needed setting doesn't apply to this operation. ApprovalType alone decides whether the request waits for approval. The operation fails with ValidationException on UserId in the following cases:
The user isn't in a staffing group, or the staffing group isn't associated with a forecast group.
Time off isn't enabled for the user's staffing group, or the user's staff rules don't allow time off.
To change the dates of a request, cancel it with CancelTimeOff and create a new request. The new request has a new TimeOffId.
For information about time off in the Connect Customer admin website, see Time off management in the Connect Customer Administrator Guide.
See also: AWS API Documentation
Request Syntax
client.create_time_off(
InstanceId='string',
UserId='string',
ShiftActivityId='string',
StartAt=datetime(2015, 1, 1),
EndAt=datetime(2015, 1, 1),
Description='string',
ApprovalType='AWAIT_APPROVAL'|'AUTOMATIC',
RuleFailureAction='REJECT'|'OVERRIDE',
ClientToken='string'
)
string
[REQUIRED]
The identifier of the Connect Customer instance. This can be the ID or the ARN of the instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user who the time off request is for. This can be the ID or the ARN of the user.
string
[REQUIRED]
The identifier of the shift activity that defines the type of time off being requested. This can be the ID or the ARN of the shift activity. It must be a time off activity. Activities that aren't set as Requestable are accepted.
datetime
[REQUIRED]
The start of the time off window, inclusive. It must be no earlier than one year before the current date. Connect Customer stores the value as sent, to the millisecond.
datetime
[REQUIRED]
The end of the time off window, exclusive. It must be after StartAt and no later than 24 months after the current date. Connect Customer stores the value as sent, to the millisecond.
string
A description recorded on the time off request. If you omit it, the request has no description.
string
[REQUIRED]
Controls who approves the request. AWAIT_APPROVAL waits for an ApproveTimeOff or RejectTimeOff call. AUTOMATIC has Connect Customer decide the request. For details, see CreateTimeOff.
string
Controls what happens when a configured rule fails. REJECT, the default, records an ERROR and ends the request REJECTED, unless the whole window is in the past. OVERRIDE records a WARNING and ends the request APPROVED, like the Override time off rules option in the Connect Customer admin website. OVERRIDE requires AUTOMATIC. With AWAIT_APPROVAL, OVERRIDE fails with ValidationException. Set it on ApproveTimeOff instead. OVERRIDE never waives CONFLICTING_TIME_OFF_REQUEST.
string
A unique, case-sensitive identifier that you provide to ensure that the operation completes no more than one time. If this token matches a previous request, Connect Customer returns the result of that request and doesn't create another time off request. If you don't provide a token, the AWS SDK populates this field. If you reuse a client token with a different request body, the request fails with ValidationException. For more information about idempotency, see Making retries safe with idempotent APIs.
This field is autopopulated if not provided.
dict
Response Syntax
{
'TimeOffId': 'string'
}
Response Structure
(dict) --
The response for CreateTimeOff.
TimeOffId (string) --
The identifier of the time off request.
Cancels a time off request.
Cancelling a CANCELLED request succeeds without a change. Returns ConflictException if the request is PENDING, which means Connect Customer is still processing the request asynchronously. Wait until GetTimeOff returns a status other than PENDING, and then retry.
See also: AWS API Documentation
Request Syntax
client.cancel_time_off(
InstanceId='string',
UserId='string',
TimeOffId='string',
Description='string'
)
string
[REQUIRED]
The identifier of the Connect Customer instance. This can be the ID or the ARN of the instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user who the time off request belongs to. This can be the ID or the ARN of the user.
string
[REQUIRED]
The unique identifier of the time off request to cancel. If the time off request doesn't belong to UserId, the operation returns ResourceNotFoundException.
string
A description recorded with the cancellation. It replaces the description of the time off request. If you omit it, the request's description is removed.
dict
Response Syntax
{}
Response Structure
(dict) --
The response for CancelTimeOff.
Returns a time off request, including its current status and validation results.
See also: AWS API Documentation
Request Syntax
client.get_time_off(
InstanceId='string',
UserId='string',
TimeOffId='string'
)
string
[REQUIRED]
The identifier of the Connect Customer instance. This can be the ID or the ARN of the instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user who the time off request belongs to. This can be the ID or the ARN of the user.
string
[REQUIRED]
The identifier of the time off request. If the time off request doesn't belong to UserId, the operation returns ResourceNotFoundException.
dict
Response Syntax
{
'TimeOffId': 'string',
'UserId': 'string',
'ShiftActivityId': 'string',
'StartAt': datetime(2015, 1, 1),
'EndAt': datetime(2015, 1, 1),
'Status': 'PENDING'|'APPROVED'|'REJECTED'|'CANCELLED'|'AWAITING_APPROVAL',
'Description': 'string',
'ValidationResults': [
{
'Severity': 'WARNING'|'ERROR',
'Code': 'INSUFFICIENT_USER_TIME_OFF_BALANCE'|'INSUFFICIENT_GROUP_TIME_OFF_ALLOWANCE'|'INSUFFICIENT_STAFFING_GROUP_TIME_OFF_ALLOWANCE'|'CONFLICTING_TIME_OFF_REQUEST'
},
],
'CreatedBy': {
'ConnectUserArn': 'string',
'AWSIdentityArn': 'string'
},
'CreatedAt': datetime(2015, 1, 1),
'UpdatedBy': {
'ConnectUserArn': 'string',
'AWSIdentityArn': 'string'
},
'UpdatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
The response for GetTimeOff.
TimeOffId (string) --
The identifier of the time off request.
UserId (string) --
The identifier of the user the time off is for.
ShiftActivityId (string) --
The identifier of the shift activity for the time off request.
StartAt (datetime) --
The start of the time off window, inclusive, as sent to CreateTimeOff.
EndAt (datetime) --
The end of the time off window, exclusive, as sent to CreateTimeOff.
Status (string) --
The status of the time off request.
PENDING: Connect Customer is processing a change to the request, which then changes to another status. An edit in the Connect Customer admin website can also make a request PENDING, so an APPROVED request can become PENDING and then end APPROVED or REJECTED.
AWAITING_APPROVAL: the request is waiting for an ApproveTimeOff or RejectTimeOff call.
Description (string) --
The description of the time off request. CreateTimeOff sets it, and CancelTimeOff replaces or removes it. An edit in the Connect Customer admin website can also change it. GetTimeOff doesn't return descriptions sent with ApproveTimeOff or RejectTimeOff.
ValidationResults (list) --
Warnings or failures produced while processing the time off request.
(dict) --
A warning or failure produced while processing the time off request.
Severity (string) --
The severity of the validation result. WARNING is a breach of the configured rules that is not enough to reject the request, either because of the rules configuration or because the caller sent RuleFailureAction OVERRIDE. ERROR is a reason the request was rejected.
Code (string) --
The specific reason for the validation result. New values may be added, so treat an unrecognized value as a generic failure of the reported severity.
INSUFFICIENT_USER_TIME_OFF_BALANCE: the user's time off balance for the activity is less than the time this request deducts. Connect Customer deducts only working time in the window. For details, see How the system calculates time off deductions in the Connect Customer Administrator Guide.
INSUFFICIENT_GROUP_TIME_OFF_ALLOWANCE: the time off allowance of the user's forecast group or demand group for the activity is too low for this request.
INSUFFICIENT_STAFFING_GROUP_TIME_OFF_ALLOWANCE: the daily time off allowance of the user's staffing group for the activity is too low for this request.
CONFLICTING_TIME_OFF_REQUEST: the request overlaps another time off request for the user that is APPROVED or being approved. Requests in AWAITING_APPROVAL don't count. For CreateTimeOff with AUTOMATIC, overlapping overtime and voluntary time off also count.
CreatedBy (dict) --
The identity that created the request. Immutable for the life of the request.
ConnectUserArn (string) --
The ARN of the Connect Customer user who performed the action.
AWSIdentityArn (string) --
The IAM or AWS STS ARN of the identity that performed the action. Present when that identity is not a Connect Customer user.
CreatedAt (datetime) --
The timestamp when the time off request was created.
UpdatedBy (dict) --
The identity that made the most recent ApproveTimeOff, RejectTimeOff, or CancelTimeOff call on the request, or took the same action in the Connect Customer admin website. Absent until one of those actions is taken, including after Connect Customer decides an AUTOMATIC request. UpdatedAt also changes when a PENDING request changes to another status and for other edits, which don't set UpdatedBy.
ConnectUserArn (string) --
The ARN of the Connect Customer user who performed the action.
AWSIdentityArn (string) --
The IAM or AWS STS ARN of the identity that performed the action. Present when that identity is not a Connect Customer user.
UpdatedAt (datetime) --
The timestamp when the time off request was last modified.
Rejects a time off request.
Rejecting a REJECTED request succeeds without a change. Returns ConflictException if the request is PENDING or CANCELLED. PENDING means Connect Customer is still processing the request asynchronously. Wait until GetTimeOff returns a status other than PENDING, and then retry.
See also: AWS API Documentation
Request Syntax
client.reject_time_off(
InstanceId='string',
UserId='string',
TimeOffId='string',
Description='string'
)
string
[REQUIRED]
The identifier of the Connect Customer instance. This can be the ID or the ARN of the instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user who the time off request belongs to. This can be the ID or the ARN of the user.
string
[REQUIRED]
The unique identifier of the time off request to reject. If the time off request doesn't belong to UserId, the operation returns ResourceNotFoundException.
string
A description recorded with the rejection, such as the reason. GetTimeOff doesn't return it.
dict
Response Syntax
{}
Response Structure
(dict) --
The response for RejectTimeOff.
Approves a time off request. Evaluates agent time off balances and group time off allowances before approving. RuleFailureAction controls what happens when these evaluations fail. The request is rejected with CONFLICTING_TIME_OFF_REQUEST if it overlaps another time off request for the user that is APPROVED or being approved.
The time off request is processed asynchronously, so a successful call doesn't indicate the final status. Read the resulting status with GetTimeOff or from the time off state-change events.
Approving an APPROVED request succeeds without a change. Approving a REJECTED request evaluates the rules again, so it can end APPROVED or REJECTED, and repeating the call can give a different result. Check the status with GetTimeOff before you retry.
Returns ConflictException if the request is PENDING or CANCELLED. PENDING means Connect Customer is still processing the request asynchronously. Wait until GetTimeOff returns a status other than PENDING, and then retry.
See also: AWS API Documentation
Request Syntax
client.approve_time_off(
InstanceId='string',
UserId='string',
TimeOffId='string',
Description='string',
RuleFailureAction='REJECT'|'OVERRIDE'
)
string
[REQUIRED]
The identifier of the Connect Customer instance. This can be the ID or the ARN of the instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user who the time off request belongs to. This can be the ID or the ARN of the user.
string
[REQUIRED]
The unique identifier of the time off request to approve. If the time off request doesn't belong to UserId, the operation returns ResourceNotFoundException.
string
A description recorded with the approval. GetTimeOff doesn't return it.
string
Controls what happens when a configured rule fails. REJECT, the default, records an ERROR and leaves the request REJECTED. OVERRIDE records a WARNING and approves the request, like the Override time off rules option in the Connect Customer admin website. OVERRIDE never waives CONFLICTING_TIME_OFF_REQUEST.
dict
Response Syntax
{}
Response Structure
(dict) --
The response for ApproveTimeOff.
Sets the time off balance for one user and shift activity. The value replaces the existing balance rather than adjusting it, so you can safely retry the call. This operation can't remove a balance. To remove one, upload a blank balance in the Connect Customer admin website. For more information, see Import an agent's time off balance in the Connect Customer Administrator Guide.
See also: AWS API Documentation
Request Syntax
client.put_time_off_balance(
InstanceId='string',
UserId='string',
ShiftActivityId='string',
Balance={
'Value': 123,
'Unit': 'MINUTES'|'HOURS'|'DAYS'
}
)
string
[REQUIRED]
The identifier of the Connect Customer instance. This can be the ID or the ARN of the instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user whose balance is being updated. This can be the ID or the ARN of the user.
string
[REQUIRED]
The identifier of the shift activity that the balance applies to. This can be the ID or the ARN of the shift activity.
dict
[REQUIRED]
The new time off balance for the user and activity. It replaces the existing balance.
Value (integer) -- [REQUIRED]
The number of units of time. You can use a negative value to report an overdrawn balance. The value must be within 876,000 hours (100 years) of zero: at most 52,560,000 MINUTES, 876,000 HOURS, or 36,500 DAYS.
Unit (string) -- [REQUIRED]
The unit the value is counted in.
dict
Response Syntax
{}
Response Structure
(dict) --
The response for PutTimeOffBalance.