V1 Employees

$v1EmployeesApi = $client->getV1EmployeesApi();

Class Name

V1EmployeesApi

Methods

List Employees

Provides summary information for all of a business's employees.

function listEmployees(
    ?string $order = null,
    ?string $beginUpdatedAt = null,
    ?string $endUpdatedAt = null,
    ?string $beginCreatedAt = null,
    ?string $endCreatedAt = null,
    ?string $status = null,
    ?string $externalId = null,
    ?int $limit = null,
    ?string $batchToken = null
): ApiResponse

Parameters

Parameter	Type	Tags	Description
`order`	`?string (SortOrder)`	Query, Optional	The order in which employees are listed in the response, based on their created_at field. Default value: ASC
`beginUpdatedAt`	`?string`	Query, Optional	If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format
`endUpdatedAt`	`?string`	Query, Optional	If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format.
`beginCreatedAt`	`?string`	Query, Optional	If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format.
`endCreatedAt`	`?string`	Query, Optional	If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format.
`status`	`?string (V1ListEmployeesRequestStatus)`	Query, Optional	If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE).
`externalId`	`?string`	Query, Optional	If provided, the endpoint returns only employee entities with the specified external_id.
`limit`	`?int`	Query, Optional	The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
`batchToken`	`?string`	Query, Optional	A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Employee[].

Example Usage

$order = Models\SortOrder::DESC;
$beginUpdatedAt = 'begin_updated_at6';
$endUpdatedAt = 'end_updated_at4';
$beginCreatedAt = 'begin_created_at6';
$endCreatedAt = 'end_created_at8';
$status = Models\V1ListEmployeesRequestStatus::ACTIVE;
$externalId = 'external_id6';
$limit = 172;
$batchToken = 'batch_token2';

$apiResponse = $v1EmployeesApi->listEmployees($order, $beginUpdatedAt, $endUpdatedAt, $beginCreatedAt, $endCreatedAt, $status, $externalId, $limit, $batchToken);

if ($apiResponse->isSuccess()) {
    $v1Employee = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Create Employee

Use the CreateEmployee endpoint to add an employee to a Square account. Employees created with the Connect API have an initial status of INACTIVE. Inactive employees cannot sign in to Square Point of Sale until they are activated from the Square Dashboard. Employee status cannot be changed with the Connect API.

Employee entities cannot be deleted. To disable employee profiles, set the employee's status to INACTIVE

function createEmployee(V1Employee $body): ApiResponse

Parameters

Parameter	Type	Tags	Description
`body`	`V1Employee`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Employee.

Example Usage

$body_firstName = 'first_name6';
$body_lastName = 'last_name4';
$body = new Models\V1Employee(
    $body_firstName,
    $body_lastName
);
$body->setId('id6');
$body->setRoleIds(['role_ids0', 'role_ids1']);
$body->setAuthorizedLocationIds(['authorized_location_ids7', 'authorized_location_ids8']);
$body->setEmail('email0');
$body->setStatus(Models\V1EmployeeStatus::ACTIVE);

$apiResponse = $v1EmployeesApi->createEmployee($body);

if ($apiResponse->isSuccess()) {
    $v1Employee = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Retrieve Employee

Provides the details for a single employee.

function retrieveEmployee(string $employeeId): ApiResponse

Parameters

Parameter	Type	Tags	Description
`employeeId`	`string`	Template, Required	The employee's ID.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Employee.

Example Usage

$employeeId = 'employee_id0';

$apiResponse = $v1EmployeesApi->retrieveEmployee($employeeId);

if ($apiResponse->isSuccess()) {
    $v1Employee = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Update Employee

UpdateEmployee

function updateEmployee(string $employeeId, V1Employee $body): ApiResponse

Parameters

Parameter	Type	Tags	Description
`employeeId`	`string`	Template, Required	The ID of the role to modify.
`body`	`V1Employee`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Employee.

Example Usage

$employeeId = 'employee_id0';
$body_firstName = 'first_name6';
$body_lastName = 'last_name4';
$body = new Models\V1Employee(
    $body_firstName,
    $body_lastName
);
$body->setId('id6');
$body->setRoleIds(['role_ids0', 'role_ids1']);
$body->setAuthorizedLocationIds(['authorized_location_ids7', 'authorized_location_ids8']);
$body->setEmail('email0');
$body->setStatus(Models\V1EmployeeStatus::ACTIVE);

$apiResponse = $v1EmployeesApi->updateEmployee($employeeId, $body);

if ($apiResponse->isSuccess()) {
    $v1Employee = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

List Employee Roles

Provides summary information for all of a business's employee roles.

function listEmployeeRoles(?string $order = null, ?int $limit = null, ?string $batchToken = null): ApiResponse

Parameters

Parameter	Type	Tags	Description
`order`	`?string (SortOrder)`	Query, Optional	The order in which employees are listed in the response, based on their created_at field.Default value: ASC
`limit`	`?int`	Query, Optional	The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
`batchToken`	`?string`	Query, Optional	A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1EmployeeRole[].

Example Usage

$order = Models\SortOrder::DESC;
$limit = 172;
$batchToken = 'batch_token2';

$apiResponse = $v1EmployeesApi->listEmployeeRoles($order, $limit, $batchToken);

if ($apiResponse->isSuccess()) {
    $v1EmployeeRole = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Create Employee Role

Creates an employee role you can then assign to employees.

Square accounts can include any number of roles that can be assigned to employees. These roles define the actions and permissions granted to an employee with that role. For example, an employee with a "Shift Manager" role might be able to issue refunds in Square Point of Sale, whereas an employee with a "Clerk" role might not.

Roles are assigned with the V1UpdateEmployee endpoint. An employee can have only one role at a time.

If an employee has no role, they have none of the permissions associated with roles. All employees can accept payments with Square Point of Sale.

function createEmployeeRole(V1EmployeeRole $body): ApiResponse

Parameters

Parameter	Type	Tags	Description
`body`	`V1EmployeeRole`	Body, Required	An EmployeeRole object with a name and permissions, and an optional owner flag.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1EmployeeRole.

Example Usage

$body_name = 'name6';
$body_permissions = [Models\V1EmployeeRolePermissions::REGISTER_APPLY_RESTRICTED_DISCOUNTS, Models\V1EmployeeRolePermissions::REGISTER_CHANGE_SETTINGS, Models\V1EmployeeRolePermissions::REGISTER_EDIT_ITEM];
$body = new Models\V1EmployeeRole(
    $body_name,
    $body_permissions
);
$body->setId('id6');
$body->setIsOwner(false);
$body->setCreatedAt('created_at4');
$body->setUpdatedAt('updated_at8');

$apiResponse = $v1EmployeesApi->createEmployeeRole($body);

if ($apiResponse->isSuccess()) {
    $v1EmployeeRole = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Retrieve Employee Role

Provides the details for a single employee role.

function retrieveEmployeeRole(string $roleId): ApiResponse

Parameters

Parameter	Type	Tags	Description
`roleId`	`string`	Template, Required	The role's ID.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1EmployeeRole.

Example Usage

$roleId = 'role_id6';

$apiResponse = $v1EmployeesApi->retrieveEmployeeRole($roleId);

if ($apiResponse->isSuccess()) {
    $v1EmployeeRole = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Update Employee Role

Modifies the details of an employee role.

function updateEmployeeRole(string $roleId, V1EmployeeRole $body): ApiResponse

Parameters

Parameter	Type	Tags	Description
`roleId`	`string`	Template, Required	The ID of the role to modify.
`body`	`V1EmployeeRole`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1EmployeeRole.

Example Usage

$roleId = 'role_id6';
$body_name = 'name6';
$body_permissions = [Models\V1EmployeeRolePermissions::REGISTER_APPLY_RESTRICTED_DISCOUNTS, Models\V1EmployeeRolePermissions::REGISTER_CHANGE_SETTINGS, Models\V1EmployeeRolePermissions::REGISTER_EDIT_ITEM];
$body = new Models\V1EmployeeRole(
    $body_name,
    $body_permissions
);
$body->setId('id6');
$body->setIsOwner(false);
$body->setCreatedAt('created_at4');
$body->setUpdatedAt('updated_at8');

$apiResponse = $v1EmployeesApi->updateEmployeeRole($roleId, $body);

if ($apiResponse->isSuccess()) {
    $v1EmployeeRole = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

List Timecards

Provides summary information for all of a business's employee timecards.

function listTimecards(
    ?string $order = null,
    ?string $employeeId = null,
    ?string $beginClockinTime = null,
    ?string $endClockinTime = null,
    ?string $beginClockoutTime = null,
    ?string $endClockoutTime = null,
    ?string $beginUpdatedAt = null,
    ?string $endUpdatedAt = null,
    ?bool $deleted = false,
    ?int $limit = null,
    ?string $batchToken = null
): ApiResponse

Parameters

Parameter	Type	Tags	Description
`order`	`?string (SortOrder)`	Query, Optional	The order in which timecards are listed in the response, based on their created_at field.
`employeeId`	`?string`	Query, Optional	If provided, the endpoint returns only timecards for the employee with the specified ID.
`beginClockinTime`	`?string`	Query, Optional	If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format.
`endClockinTime`	`?string`	Query, Optional	If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format.
`beginClockoutTime`	`?string`	Query, Optional	If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format.
`endClockoutTime`	`?string`	Query, Optional	If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format.
`beginUpdatedAt`	`?string`	Query, Optional	If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format.
`endUpdatedAt`	`?string`	Query, Optional	If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format.
`deleted`	`?bool`	Query, Optional	If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned.
`limit`	`?int`	Query, Optional	The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
`batchToken`	`?string`	Query, Optional	A pagination cursor to retrieve the next set of results for your original query to the endpoint.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Timecard[].

Example Usage

$order = Models\SortOrder::DESC;
$employeeId = 'employee_id0';
$beginClockinTime = 'begin_clockin_time8';
$endClockinTime = 'end_clockin_time2';
$beginClockoutTime = 'begin_clockout_time0';
$endClockoutTime = 'end_clockout_time2';
$beginUpdatedAt = 'begin_updated_at6';
$endUpdatedAt = 'end_updated_at4';
$deleted = false;
$limit = 172;
$batchToken = 'batch_token2';

$apiResponse = $v1EmployeesApi->listTimecards($order, $employeeId, $beginClockinTime, $endClockinTime, $beginClockoutTime, $endClockoutTime, $beginUpdatedAt, $endUpdatedAt, $deleted, $limit, $batchToken);

if ($apiResponse->isSuccess()) {
    $v1Timecard = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Create Timecard

Creates a timecard for an employee and clocks them in with an API_CREATE event and a clockin_time set to the current time unless the request provides a different value.

To import timecards from another system (rather than clocking someone in). Specify the clockin_time and* clockout_time in the request.

Timecards correspond to exactly one shift for a given employee, bounded by the clockin_time and clockout_time fields. An employee is considered clocked in if they have a timecard that doesn't have a clockout_time set. An employee that is currently clocked in cannot be clocked in a second time.

function createTimecard(V1Timecard $body): ApiResponse

Parameters

Parameter	Type	Tags	Description
`body`	`V1Timecard`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Timecard.

Example Usage

$body_employeeId = 'employee_id4';
$body = new Models\V1Timecard(
    $body_employeeId
);
$body->setId('id6');
$body->setDeleted(false);
$body->setClockinTime('clockin_time2');
$body->setClockoutTime('clockout_time2');
$body->setClockinLocationId('clockin_location_id4');

$apiResponse = $v1EmployeesApi->createTimecard($body);

if ($apiResponse->isSuccess()) {
    $v1Timecard = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Delete Timecard

Deletes a timecard. Timecards can also be deleted through the Square Dashboard. Deleted timecards are still accessible through Connect API endpoints, but cannot be modified. The deleted field of the Timecard object indicates whether the timecard has been deleted.

Note: By default, deleted timecards appear alongside valid timecards in results returned by the ListTimecards endpoint. To filter deleted timecards, include the deleted query parameter in the list request.

Only approved accounts can manage their employees with Square. Unapproved accounts cannot use employee management features with the API.

function deleteTimecard(string $timecardId): ApiResponse

Parameters

Parameter	Type	Tags	Description
`timecardId`	`string`	Template, Required	The ID of the timecard to delete.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type array.

Example Usage

$timecardId = 'timecard_id0';

$apiResponse = $v1EmployeesApi->deleteTimecard($timecardId);

if ($apiResponse->isSuccess()) {
    $data = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Retrieve Timecard

Provides the details for a single timecard.

Only approved accounts can manage their employees with Square. Unapproved accounts cannot use employee management features with the API.

function retrieveTimecard(string $timecardId): ApiResponse

Parameters

Parameter	Type	Tags	Description
`timecardId`	`string`	Template, Required	The timecard's ID.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Timecard.

Example Usage

$timecardId = 'timecard_id0';

$apiResponse = $v1EmployeesApi->retrieveTimecard($timecardId);

if ($apiResponse->isSuccess()) {
    $v1Timecard = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Update Timecard

Modifies the details of a timecard with an API_EDIT event for the timecard. Updating an active timecard with a clockout_time clocks the employee out.

function updateTimecard(string $timecardId, V1Timecard $body): ApiResponse

Parameters

Parameter	Type	Tags	Description
`timecardId`	`string`	Template, Required	TThe ID of the timecard to modify.
`body`	`V1Timecard`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1Timecard.

Example Usage

$timecardId = 'timecard_id0';
$body_employeeId = 'employee_id4';
$body = new Models\V1Timecard(
    $body_employeeId
);
$body->setId('id6');
$body->setDeleted(false);
$body->setClockinTime('clockin_time2');
$body->setClockoutTime('clockout_time2');
$body->setClockinLocationId('clockin_location_id4');

$apiResponse = $v1EmployeesApi->updateTimecard($timecardId, $body);

if ($apiResponse->isSuccess()) {
    $v1Timecard = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

List Timecard Events

Provides summary information for all events associated with a particular timecard.

Only approved accounts can manage their employees with Square. Unapproved accounts cannot use employee management features with the API.

function listTimecardEvents(string $timecardId): ApiResponse

Parameters

Parameter	Type	Tags	Description
`timecardId`	`string`	Template, Required	The ID of the timecard to list events for.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1TimecardEvent[].

Example Usage

$timecardId = 'timecard_id0';

$apiResponse = $v1EmployeesApi->listTimecardEvents($timecardId);

if ($apiResponse->isSuccess()) {
    $v1TimecardEvent = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

List Cash Drawer Shifts

Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days.

function listCashDrawerShifts(
    string $locationId,
    ?string $order = null,
    ?string $beginTime = null,
    ?string $endTime = null
): ApiResponse

Parameters

Parameter	Type	Tags	Description
`locationId`	`string`	Template, Required	The ID of the location to list cash drawer shifts for.
`order`	`?string (SortOrder)`	Query, Optional	The order in which cash drawer shifts are listed in the response, based on their created_at field. Default value: ASC
`beginTime`	`?string`	Query, Optional	The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days.
`endTime`	`?string`	Query, Optional	The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1CashDrawerShift[].

Example Usage

$locationId = 'location_id4';
$order = Models\SortOrder::DESC;
$beginTime = 'begin_time2';
$endTime = 'end_time2';

$apiResponse = $v1EmployeesApi->listCashDrawerShifts($locationId, $order, $beginTime, $endTime);

if ($apiResponse->isSuccess()) {
    $v1CashDrawerShift = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

Retrieve Cash Drawer Shift

Provides the details for a single cash drawer shift, including all events that occurred during the shift.

function retrieveCashDrawerShift(string $locationId, string $shiftId): ApiResponse

Parameters

Parameter	Type	Tags	Description
`locationId`	`string`	Template, Required	The ID of the location to list cash drawer shifts for.
`shiftId`	`string`	Template, Required	The shift's ID.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type V1CashDrawerShift.

Example Usage

$locationId = 'location_id4';
$shiftId = 'shift_id0';

$apiResponse = $v1EmployeesApi->retrieveCashDrawerShift($locationId, $shiftId);

if ($apiResponse->isSuccess()) {
    $v1CashDrawerShift = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Get more response info...
// $statusCode = $apiResponse->getStatusCode();
// $headers = $apiResponse->getHeaders();

FilesExpand file tree

v1-employees.md

Latest commit

History

v1-employees.md

File metadata and controls

V1 Employees

Class Name

Methods

List Employees

Parameters

Response Type

Example Usage

Create Employee

Parameters

Response Type

Example Usage

Retrieve Employee

Parameters

Response Type

Example Usage

Update Employee

Parameters

Response Type

Example Usage

List Employee Roles

Parameters

Response Type

Example Usage

Create Employee Role

Parameters

Response Type

Example Usage

Retrieve Employee Role

Parameters

Response Type

Example Usage

Update Employee Role

Parameters

Response Type

Example Usage

List Timecards

Parameters

Response Type

Example Usage

Create Timecard

Parameters

Response Type

Example Usage

Delete Timecard

Parameters

Response Type

Example Usage

Retrieve Timecard

Parameters

Response Type

Example Usage

Update Timecard

Parameters

Response Type

Example Usage

List Timecard Events

Parameters

Response Type

Example Usage

List Cash Drawer Shifts

Parameters

Response Type

Example Usage

Retrieve Cash Drawer Shift

Parameters

Response Type

Example Usage