Migrate from the Square Employees API
This topic describes how an application migrates code from using the Square Employees API to using the Square Team API. The Team API accesses the same underlying objects as the Employees API. You do not convert an employee into a team member. Instead, you access the same object using the Team API.
On this page
Migration overview
The Square Team API replaces the Square Employees API and provides new functionality to make it easier to manage team members for Square sellers.
The Employees API is used to retrieve a single employee by ID and filtered lists of employees.
Important dates
Deprecation: 2020-08-26
Retirement: 2021-08-26
If you need help
If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Slack, or reach out to your Square Account Manager.
New features in the Team API
The Team API provides all the functionality of the Employees API and adds these features:
Wage settings. The Team API lets an application manage multiple wage levels and job titles per team member to allow for different pay rates for different jobs.
Access. The Team API supports create, update, and read access to team members in the Team Management feature of the Seller Dashboard.
Pagination. The Team API reporting endpoints provide pagination and sorting, along with location and time range filtering.
Endpoints
Team API endpoints replace the employee list and retrieve functionality in the Employees API.
| Deprecated Employees API endpoint | Replacement |
|---|---|
| ListEmployees | SearchTeamMembers |
| RetrieveEmployee | RetrieveTeamMember |
Field mapping
Fields in the Employee object are replaced by fields in the TeamMember object. The field names are the same except the fields in the following table:
| Employee field | TeamMember field | Notes |
|---|---|---|
first_name | given_name | |
last_name | family_name | |
email | email_address | |
location_ids | assigned_locations |
Migrate employees to the Team API
List employees → search team members
Example employees request
A request that retrieves three active employees at a time who are assigned to locationid:
GET /v2/employees?status=ACTIVE&location_id=locationid&limit=3
Example Team API call
POST /v2/team-members/search
{
query: {
filter: {
location_ids: ["locationid"],
status: ACTIVE
}
},
limit: 3
}
Example responses
Employees response
{
"employees": [{
"id": "employee_id",
"first_name": "John",
"last_name": "Doe",
"location_ids": ["loaction_id"],
"status": "ACTIVE",
"created_at": "2020-04-28T22:33:56.526Z",
"updated_at": "2020-06-09T17:08:14.593Z",
"email": "jdoe@squareup.com"
},
{
"id": "employee_id",
"first_name": "Bob",
"last_name": "Smith",
"location_ids": ["location_id"],
"status": "ACTIVE",
"created_at": "2020-07-01T19:55:32.828Z",
"updated_at": "2020-07-01T19:55:32.828Z",
"email": "bsmith@squareup.com"
},
{
"id": "employee_id",
"location_ids": ["location_id"],
"first_name": "Charles",
"last_name": "Bee",
"status": "ACTIVE",
"created_at": "2019-07-16T19:52:41Z",
"updated_at": "2019-07-16T19:52:41Z",
"email": "cbee@squareup.com",
"is_owner": true
}
],
"cursor": "N:QBax45V6nn13m1W5yt3Z"
}
Team API response
{
"team_members": [{
"id": "employee_id",
"is_owner": false,
"status": "ACTIVE",
"given_name": "John",
"family_name": "Doe",
"email_address": "jdoe@squareup.com",
"created_at": "2020-04-28T22:33:56.526Z",
"updated_at": "2020-06-09T17:08:14.593Z",
"assigned_locations": {
"assignment_type": "EXPLICIT_LOCATIONS",
"location_ids": ["loaction_id"]
}
},
{
"id": "employee_id",
"is_owner": false,
"status": "ACTIVE",
"given_name": "Bob",
"family_name": "Smith",
"email_address": "bsmith@squareup.com",
"created_at": "2020-07-01T19:55:32.828Z",
"updated_at": "2020-07-01T19:55:32.828Z",
"assigned_locations": {
"assignment_type": "EXPLICIT_LOCATIONS",
"location_ids": ["location_id"]
}
},
{
"id": "employee_id",
"is_owner": true,
"status": "ACTIVE",
"given_name": "Charles",
"family_name": "Bee",
"email_address": "cbee@squareup.com",
"created_at": "2019-07-16T19:52:41Z",
"updated_at": "2019-07-16T19:52:41Z",
"assigned_locations": {
"assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
}
}
],
"cursor": "N:QBax45V6nn13m1W5yt3Z"
}
Retrieve employee → retrieve team member
Employees request
GET /v2/employees/{id}
Employees response
{
"employee": {
"id": "YWHZ5NXEWheVH6iRie7B",
"first_name": "Joe",
"last_name": "Public",
"location_ids": [
"90A9W5RRYD2GQ",
"EWVV7AYQC45SS"
],
"status": "ACTIVE",
"created_at": "2020-06-04T22:06:11.123Z",
"updated_at": "2020-06-04T22:06:11.123Z",
"email": "joe@mybusiness.com",
"phone_number": "+12535551212"
}
}
Team API request
GET /v2/team-members/{team_member_id}
Team API response
{
"team_member": {
"id": "YWHZ5NXEWheVH6iRie7B",
"reference_id": "abc-123",
"is_owner": false,
"status": "ACTIVE",
"given_name": "Joe",
"family_name": "Public",
"email_address": "joe@mybusiness.com",
"phone_number": "+12535551212",
"created_at": "2020-06-04T22:06:11.123Z",
"updated_at": "2020-06-04T22:06:11.123Z",
"assigned_locations": {
"assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
}
}
}