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

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:

List Employees

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

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

Retrieve employee → retrieve team member

Employees request

Retrieve Employee

curl https://connect.squareupsandbox.com/v2/employees/{id} \
  -H 'Square-Version: 2022-05-12' \
  -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: 2022-05-12' \
  -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

On this page

Migration overview

Important dates

If you need help

New features in the Team API

Endpoints

Field mapping

Migrate employees to the Team API

List employees → search team members

Example responses

Retrieve employee → retrieve team member

On this page

Migrate from the Square Employees API

On this page

On this page

Migration overview Permalink Get a link to this section

Important dates Permalink Get a link to this section

If you need help Permalink Get a link to this section

New features in the Team API Permalink Get a link to this section

Endpoints Permalink Get a link to this section

Field mapping Permalink Get a link to this section

Migrate employees to the Team API Permalink Get a link to this section

List employees → search team members Permalink Get a link to this section

Example responses Permalink Get a link to this section

Retrieve employee → retrieve team member Permalink Get a link to this section

On this page

Migration overview

Important dates

If you need help

New features in the Team API

Endpoints

Field mapping

Migrate employees to the Team API

List employees → search team members

Example responses

Retrieve employee → retrieve team member