Connect v1 Migration

Migrate from the v1 Employees API

This topic describes how an application migrates code from using the v1 Employees API to using the Square Team API.

Migration overview
New features in the Team API
Migrate v1 Employees.roles to the Team API
Endpoints
Field mapping
v1 List employee roles to Square List team member wage settings
Migrate v1 Employees to the Team API

Link to section
Migration overview

The Square Team API replaces the v1 Employee API and provides new functionality to make it easier to manage team members for Square sellers.

The v1 Employee API is used to create employees, manage a seller's employee roster, and provide the names and job titles of employees. Combined with the now deprecated v1 Timecards API, it provided a basic timekeeping solution for sellers.

The Team and Labor APIs provide additional timekeeping features and other team member management capabilities.

Link to section
Important dates

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

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 Discord community, 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 Connect v1 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. Job titles were known as employee roles in the v1 Employees API.

Note

The position an employee had for a seller was mapped one to one with the permissions assigned to them. With the Team API, these concepts are separated. The job title is now just about what the team member does at the business. For this reason, developers should reference the job title instead of the role name when determining what the team member does for the seller.
Access. Create, update, and read access to the team members in the Team Management feature of the Seller Dashboard.
Pagination. The Team API reporting endpoints provide pagination and sorting along with location.

Link to section
Migrate v1 Employees.roles to the Team API

As a replacement for the deprecated EmployeeRole object, use a Team API WageSetting object. Your application should create a WageSetting object for each team member. The WageSetting.job_assignments field holds an array of JobAssignment objects that provide a job title and pay information for jobs assigned to a team member.

The WageSetting.JobAssignment.job_title replaces the EmployeeRole.name as the primary reporting attribute of a team member in all Square products and APIs.

The Labor API and Team API access the same set of job titles for a team member. To retrieve a list of job titles, you can use the Labor API listTeamMemberWages endpoint. To create or update a job title, use the Team API UpdateWageSetting endpoint.

You cannot currently set or update a team member permission assignment using the UpdateWageSetting endpoint. To update permissions and access point assignments, sign in to Seller Dashboard and access team member settings.

Link to section
Endpoints

The Square Team and Labor API wage setting endpoints replace the employee role endpoints in the v1 Employees API.

The Square Labor API endpoints for employee wages are deprecated and replaced with team member wage endpoints as shown in the following table:

Deprecated Employee endpoint	Labor API replacement
GetEmployeeWage	GetTeamMemberWage
ListEmployeeWages	ListTeamMemberWages

You must update the code that relies on the following endpoints to avoid breaking when the v1 Employees API retires:

v1 endpoint	Square replacement	Usage
ListEmployeeRoles	ListTeamMemberWages	No longer returns a list of `EmployeeRole`. Now returns a list of TeamMemberWage.
RetrieveEmployeeRole	GetTeamMemberWage	Gets a single TeamMemberWage with the details of a team member job.
UpdateEmployeeRole	UpdateWageSetting	Creates or updates a WageSetting object for a team member.

Link to section
Field mapping

Fields in the Employee.roll object are replaced by fields in the TeamMemberWage and TeamMember objects.

v1 field	Square field	Notes
`name`	`TeamMemberWage.title`
`permissions`	N/A	Set permissions in the Seller Dashboard.
`is_owner`	`TeamMember.is_owner`	The owner flag is set on the team member.

Link to section
v1 List employee roles to Square List team member wage settings

v1 Employees roles	v2 Labor API team member wage settings
GET `/v1/me/roles`	`GET /v2/labor/team-member-wages?team_member_id={team_member_id}`

Link to section
Labor API request

curl https://connect.squareup.com/v2/labor/team-member-wages?team_member_id=TMBRVY_Q_rXeZ8Ht \
  -H 'Square-Version: 2020-07-22' \
  -H 'Authorization: Bearer {{AUTHORIZATION_TOKEN}}' \
  -H 'Content-Type: application/json'

[{
    "permissions": [
        "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE"
    ],
    "id": "0J0F9R7RXqTfXkIpAu6U",
    "name": "Manager",
    "is_owner": false,
    "updated_at": "1593741956446",
    "created_at": "1567123155000"
}]

{
    "team_member_wages": [{
        "id": "LoGRa14MSkSdfKYfQTyk47ts",
        "team_member_id": "0m6a6Nn26S0P1MD_YUZc",
        "title": "Manager",
        "hourly_rate": {
            "amount": 6000,
            "currency": "USD"
        }
    }]
}

Link to section
Update a job title in the Team API

Link to section
Update or create a job title

The following Team API endpoint lets you create a new job title for a team member if it does not exist:

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

PUT /v2/team-members/0m6a6Nn26S0P1MD_YUZc/wage-setting

{
    "wage_setting": {
        "is_overtime_exempt": true,
        "job_assignments": [{
            "job_title": "Manager",
            "pay_type": "HOURLY",
            "annual_rate": {
                "amount": 6000,
                "currency": "USD"
            }
        }]
    }
}

{
    "wage_setting": {
        "team_member_id": "0m6a6Nn26S0P1MD_YUZc",
        "job_assignments": [{
            "job_title": "Manager",
            "pay_type": "HOURLY",
            "hourly_rate": {
                "amount": 6000,
                "currency": "USD"
            }
        }],
        "is_overtime_exempt": true,
        "version": 2,
        "created_at": "2019-07-10T17:26:48+00:00",
        "updated_at": "2020-06-11T23:12:04+00:00"
    }
}

Link to section
Migrate v1 Employees to the Team API

Link to section
List employees → Search team members

Example v2 Employees request

Request to retrieve a page of three active employees for a location ID:

GET /v2/employees?status=ACTIVE&location_id=locationid&limit=3

Example Team API call

1
2
3
4
5
6
7
8
9
10

POST /v2/team-members/search
{
    query: {
        filter: {
            location_ids: ["locationid"],
            status: ACTIVE
        }
    },
    limit: 3
}

Link to section
Example responses

v1 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
36

{
    "items": [{
            "id": "employee_id",
            "first_name": "John",
            "last_name": "Doe",
            "role_ids": ["role_id"],
            "authorized_location_ids": ["location_id"],
            "status": "ACTIVE",
            "created_at": "2020-04-28T22:33:56.526Z",
            "updated_at": "2020-06-09T17:08:14.593Z",
            "email": "[email protected]"
        },
        {
            "id": "employee_id",
            "first_name": "Bob",
            "last_name": "Smith",
            "role_ids": ["role_id"],
            "authorized_location_ids": ["location_id"],
            "status": "ACTIVE",
            "created_at": "2020-07-01T19:55:32.828Z",
            "updated_at": "2020-07-01T19:55:32.828Z",
            "email": "[email protected]"
        },
        {
            "id": "employee_id",
            "role_ids": ["role_id"],
            "authorized_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": "[email protected]"
        }
    ]
}

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": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
            "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
Get Square account owner v1 employee → Get Square account owner TeamMember

With the v1 Employee API, the is_owner flag was stored in a V1EmployeeRole object. Each employee was assigned to one or more roles via the role_ids field. With the v2 TeamMember object, the is_owner flag is stored in the TeamMember object.

Link to section
v1 Employee

With the v1 Employee, you had to find the employee roles that were marked as owner roles and then use those owner role IDs to compare with the role IDs in each employee object. When there was a match between role ID and an employee role ID, an owner was found.

v1 Employee roles request Get all of the employee roles:

GET /v1/me/roles

V1 Employees roles API response The response is a collection of all employee roles, one or more of which is the Square account owner role.

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

[{
    "permissions": [
        "REGISTER_ACCESS_SALES_HISTORY",
    "REGISTER_OPEN_CASH_DRAWER_OUTSIDE_SALE",
    "REGISTER_APPLY_RESTRICTED_DISCOUNTS",
    "REGISTER_CHANGE_SETTINGS",
    "REGISTER_EDIT_ITEM",
    "REGISTER_ISSUE_REFUNDS",
    "REGISTER_VIEW_SUMMARY_REPORTS",
    ],
    "id": "0J0F9R7RXqTfXkIpAu6U",
    "name": "Manager",
    "is_owner": true,
    "updated_at": "1593741956446",
    "created_at": "1567123155000"
}]

Keep the V1EmployeeRole.id field value for the object whose is_owner is true.

v1 Employee request Get all of the employees

GET /v1/me/employees

V1 Employees API response The response is a collection of all employees, one or more of which is the Square account owner role.

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

{
    "items": [{
            "id": "employee_id",
            "first_name": "John",
            "last_name": "Doe",
            "role_ids": ["0J0F9R7RXqTfXkIpAu6U"]
            "authorized_location_ids": ["location_id"],
            "status": "ACTIVE",
            "created_at": "2020-04-28T22:33:56.526Z",
            "updated_at": "2020-06-09T17:08:14.593Z",
            "email": "[email protected]"
        }
    ],
    "batch_token": "N:QBax45V6nn13m1W5yt3Z"
}

The employe whose role_ids field includes the desired owner role ID is a Square account owner.

Link to section
v2 TeamMember

v2 TeamMember request Get a list of the team members for the seller

1
2
3
4
5
6
7
8
9
10
11
12

curl https://connect.squareupsandbox.com/v2/team-members/search \
  -X POST \
  -H 'Square-Version: 2021-06-16' \
  -H 'Authorization: Bearer EAAAEPS7dlj2Mgr9OpGXSMYzEL4TMyvyw_ZACpBqa4b-P-81LUvFOjILLilC-lPx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "status": "ACTIVE"
      }
    }
  }'

v2 TeamMember response Within the list of team members in the response, there will be at least one team member designated as the Square account owner. This is specified by is_owner true.

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

{
  "team_members": [
    {
      "id": "wmdWZvPrutElgxxSyQPH",
      "is_owner": true,
      "status": "ACTIVE",
      "given_name": "Adam",
      "family_name": "Ankunding",
      "email_address": "sand[email protected]",
      "created_at": "2019-07-19T23:37:59Z",
      "updated_at": "2019-07-19T23:37:59Z",
      "assigned_locations": {
        "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
      }
    }
  ]
}

If you need to get the Square email address of the account owner, find the TeamMember whose is_owner field is true. The email_address of that team member is the Square account owner email address.

Link to section
Create employee → Create team member

The v1 create employee endpoint only allows creating INACTIVE employees whereas the Team API allows the option to create ACTIVE and INACTIVE team members, with the default option set to ACTIVE.

v1 Employees request

POST /v1/me/employees
{
    "authorized_location_ids": ["location_id"],
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]"
}

Team API request

1
2
3
4
5
6
7
8
9
10
11
12

POST /v2/team-members
{
    "team_member": {
        "assigned_locations": {
            "assignment_type": "EXPLICIT_LOCATIONS",
            "location_ids": ["location_id"]
        },
        "given_name": "Jane",
        "family_name": "Smith",
        "email_address": "[email protected]"
    }
}

Example response

v1 Employees response

1
2
3
4
5
6
7
8
9
10
11

{
    "authorized_location_ids": ["location_id"],
    "role_ids": [],
    "id": "employee_id",
    "first_name": "Jane",
    "last_name": "Smith",
    "status": "INACTIVE",
    "updated_at": "2020-07-01T19:59:07Z",
    "created_at": "2020-07-01T19:59:07Z",
    "email": "[email protected]"
}

Team API response

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

{
    "team_member": {
        "id": "employee_id",
        "is_owner": false,
        "status": "ACTIVE",
        "given_name": "Jane",
        "family_name": "Smith",
        "email_address": "[email protected]",
        "assigned_locations": {
            "assignment_type": "EXPLICIT_LOCATIONS",
            "location_ids": ["location_id"]
        }
    }
}

Link to section
Update Employee → Update Team Member

v1 employee API only allows updating authorized_location_ids, last_name and first_name of an employee, whereas Square Team API allows updating the same fields plus phone_number, reference_id, and email_address.

v1 Employees request

PUT /v1/me/employees/{employee_id}
{
    "authorized_location_ids": ["location_id"],
    "first_name": "Jane",
    "last_name": "Smith"
}

Team API request

1
2
3
4
5
6
7
8
9
10
11

PUT /v2/team-members/{team_member_id}
{
    "team_member": {
        "assigned_locations": {
            "assignment_type": "EXPLICIT_LOCATIONS",
            "location_ids": ["location_id"]
        },
        "given_name": "Jane",
        "family_name": "Smith"
    }
}

Link to section
Retrieve employee → Retrieve team member

Example request

v1 Employees request

GET /v1/me/employees/{employee_id}

Team API request

GET /v2/team-members/{team_member_id}

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

Docs

Migrate from the v1 Employees API

On this page

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

Note

Link to section
Migrate v1 Employees.roles to the Team API

Note

Link to section
Endpoints

Link to section
Field mapping

Link to section
v1 List employee roles to Square List team member wage settings

Link to section
Labor API request

Link to section
V1 Employees roles API response

Link to section
Labor API response

Link to section
Update a job title in the Team API

Link to section
Update or create a job title

Link to section
V2 UPDATE JOB TITLE RESPONSE

Link to section
Migrate v1 Employees to the Team API

Link to section
List employees → Search team members

Link to section
Example responses

Link to section
Get Square account owner v1 employee → Get Square account owner TeamMember

Link to section
v1 Employee

Link to section
v2 TeamMember

Did you know?

Link to section
Create employee → Create team member

Link to section
Update Employee → Update Team Member

Link to section
Retrieve employee → Retrieve team member

On this page

Docs

Migrate from the v1 Employees API

On this page

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

Note

Link to section Migrate v1 Employees.roles to the Team API

Note

Link to section Endpoints

Link to section Field mapping

Link to section v1 List employee roles to Square List team member wage settings

Link to section Labor API request

Link to section V1 Employees roles API response

Link to section Labor API response

Link to section Update a job title in the Team API

Link to section Update or create a job title

Link to section V2 UPDATE JOB TITLE RESPONSE

Link to section Migrate v1 Employees to the Team API

Link to section List employees → Search team members

Link to section Example responses

Link to section Get Square account owner v1 employee → Get Square account owner TeamMember

Link to section v1 Employee

Link to section v2 TeamMember

Did you know?

Link to section Create employee → Create team member

Link to section Update Employee → Update Team Member

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
Migrate v1 Employees.roles to the Team API

Link to section
Endpoints

Link to section
Field mapping

Link to section
v1 List employee roles to Square List team member wage settings

Link to section
Labor API request

Link to section
V1 Employees roles API response

Link to section
Labor API response

Link to section
Update a job title in the Team API

Link to section
Update or create a job title

Link to section
V2 UPDATE JOB TITLE RESPONSE

Link to section
Migrate v1 Employees to the Team API

Link to section
List employees → Search team members

Link to section
Example responses

Link to section
Get Square account owner v1 employee → Get Square account owner TeamMember

Link to section
v1 Employee

Link to section
v2 TeamMember

Link to section
Create employee → Create team member

Link to section
Update Employee → Update Team Member

Link to section
Retrieve employee → Retrieve team member