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 Permalink Get a link to this section

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.

Important dates Permalink Get a link to this section

  • Deprecation: 2020-08-26

  • Retirement: 2021-08-26

If you need help Permalink Get a link to this section

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 Permalink Get a link to this section

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.

Migrate v1 Employees.roles to the Team API Permalink Get a link to this section

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.

Note

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.

Endpoints Permalink Get a link to this section

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 endpointLabor 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 ListTeamMemberWagesNo longer returns a list of EmployeeRole. Now returns a list of TeamMemberWage.
RetrieveEmployeeRole GetTeamMemberWageGets a single TeamMemberWage with the details of a team member job.
UpdateEmployeeRole UpdateWageSettingCreates or updates a WageSetting object for a team member.

Field mapping Permalink Get a link to this section

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

v1 fieldSquare fieldNotes
nameTeamMemberWage.title
permissionsN/ASet permissions in the Seller Dashboard.
is_ownerTeamMember.is_ownerThe owner flag is set on the team member.

v1 List employee roles to Square List team member wage settings Permalink Get a link to this section

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

Labor API request Permalink Get a link to this section

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'

V1 Employees roles API response Permalink Get a link to this section

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

Labor API response Permalink Get a link to this section

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

Update a job title in the Team API Permalink Get a link to this section

Update or create a job title Permalink Get a link to this section

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

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

V2 UPDATE JOB TITLE RESPONSE Permalink Get a link to this section

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

Migrate v1 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 v2 Employees request

Request that retrieves three active employees that are assigned to a location ID at a time:

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 Permalink Get a link to this section

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

Create employee → Create team member Permalink Get a link to this section

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": "created_employee@squareup.com"
}

Team API request

POST /v2/team-members
{
    "team_member": {
        "assigned_locations": {
            "assignment_type": "EXPLICIT_LOCATIONS",
            "location_ids": ["location_id"]
        },
        "given_name": "Jane",
        "family_name": "Smith",
        "email_address": "jsmith@squareup.com"
    }
}

Example response

v1 Employees response

{
    "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": "jsmith@squareup.com"
}

Team API response

{
    "team_member": {
        "id": "employee_id",
        "is_owner": false,
        "status": "ACTIVE",
        "given_name": "Jane",
        "family_name": "Smith",
        "email_address": "jsmith@squareup.com",
        "assigned_locations": {
            "assignment_type": "EXPLICIT_LOCATIONS",
            "location_ids": ["location_id"]
        }
    }
}

Update Employee → Update Team Member Permalink Get a link to this section

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

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

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

Example request

v1 Employees request

GET /v1/me/employees/{employee_id}

Team API request

GET /v2/team-members/{team_member_id}