Learn how to migrate your application from the Square v2 Employees API to the Team API.
Team API

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.

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.

  • Deprecation: 2020-08-26

  • Retirement: 2021-08-26

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.

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.

Team API endpoints replace the employee list and retrieve functionality in the Employees API.

Deprecated Employees API endpointReplacement
ListEmployeesSearchTeamMembers
RetrieveEmployeeRetrieveTeamMember

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 fieldTeamMember fieldNotes
first_namegiven_name
last_namefamily_name
emailemail_address
location_idsassigned_locations

Example employees request

A request that retrieves three active employees at a time who are assigned to locationid:

List Employees
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/employees?location_id=LOCATION_ID&status=ACTIVE&limit=3 \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Example Team API call

Search Team Members
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareupsandbox.com/v2/team-members/search \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "{LOCATION_ID}"
        ],
        "status": "ACTIVE"
      }
    },
    "limit": 3
  }'

Employees response

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
{
    "employees": [{
            "id": "{EMPLOYEE_ID}",
            "first_name": "John",
            "last_name": "Doe",
            "location_ids": ["{LOCATION_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

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
{
    "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": ["{LOCATION_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"
}

Employees request

Retrieve Employee
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/employees/{id} \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Employees response

Team API request

Retrieve Team Member
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/team-members/TEAM_MEMBER_ID \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Team API response

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.