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

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

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

Deprecated Employees API endpointReplacement
ListEmployees SearchTeamMembers
RetrieveEmployee RetrieveTeamMember

Field mapping Permalink Get a link to this section

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

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 employees request

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

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

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

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

Employees request

GET /v2/employees/{id}

Employees response

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

GET /v2/team-members/{team_member_id}

Team API response

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