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.

Migration overview
New features in the Team API
Endpoints
Field mapping
Migrate employees to the Team API

Link to section
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.

Link to section
Important dates

Deprecation: 2020-08-26
Retirement: 2021-08-26

Link to section
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.

Link to section
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.

Link to section
Endpoints

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

Deprecated Employees API endpoint	Replacement
ListEmployees	SearchTeamMembers
RetrieveEmployee	RetrieveTeamMember

Link to section
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`

Link to section
Migrate employees to the Team API

Link to section
List employees → search team members

Example employees request

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

List Employees

curl https://connect.squareupsandbox.com/v2/employees?location_id=LOCATION_ID&status=ACTIVE&limit=3 \
  -H 'Square-Version: 2023-01-19' \
  -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: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "{LOCATION_ID}"
        ],
        "status": "ACTIVE"
      }
    },
    "limit": 3
  }'

Link to section
Example responses

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

Link to section
Retrieve employee → retrieve team member

Employees request

Retrieve Employee

curl https://connect.squareupsandbox.com/v2/employees/{id} \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Employees response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

Retrieve Team Member

curl https://connect.squareupsandbox.com/v2/team-members/TEAM_MEMBER_ID \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Team API response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

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

Migrate from the Square Employees API

On this page

Link to section
Migration overview

Link to section
Important dates

Link to section
If you need help

Link to section
New features in the Team API

Link to section
Endpoints

Link to section
Field mapping

Link to section
Migrate employees to the Team API

Link to section
List employees → search team members

Link to section
Example responses

Link to section
Retrieve employee → retrieve team member

On this page

Migrate from the Square Employees API

On this page

Link to section Migration overview

Link to section Important dates

Link to section If you need help

Link to section New features in the Team API

Link to section Endpoints

Link to section Field mapping

Link to section Migrate employees to the Team API

Link to section List employees → search team members

Link to section Example responses

Link to section Retrieve employee → retrieve team member

On this page

Link to section
Migration overview

Link to section
Important dates

Link to section
If you need help

Link to section
New features in the Team API

Link to section
Endpoints

Link to section
Field mapping

Link to section
Migrate employees to the Team API

Link to section
List employees → search team members

Link to section
Example responses

Link to section
Retrieve employee → retrieve team member