Integration Guide

Use the Team API to automate creating and configuring team members. Team members can be used in Square labor shifts, appointment scheduling, cash drawer shifts, and payroll. The Team API allows for individual and bulk updates to team members, including setting wage levels and job descriptions.

Setting up a new team member includes the following tasks:

1. Creating a TeamMember assigned to specified seller locations.
2. Setting a wage rate and job assignment for the team member.
3. Granting Square account permissions to the new team member.

EMPLOYEES_WRITE OAuth permission must be granted to your application for these operations.

After you create a new team member, the team member can be assigned to a Labor API Shift record to track worked hours or CashDrawerShift to associate the cash drawer connected to the Square POS with the team member.

The CreateTeamMember endpoint is used to create a single team member. You can limit a team member's access to a defined set of seller locations by setting the assigned_locations.assignment_type request to EXPLICIT_LOCATIONS and adding IDs for the locations.

If the new team member has access to all of a seller's locations, set the assignment_type to ALL_CURRENT_AND_FUTURE_LOCATIONS. This allows the team member to automatically be assigned to any new location created on the account. With this assignment type, the location_ids field is optional and any location IDs that are set are ignored.

The email address that you assign is used by Square to invite the team member to create their Square account after you've assigned them permissions in the Seller Dashboard. It can't be an address that Square has already registered to a different team member. If the address has already been registered, the CreateTeamMember call fails with a CONFLICT error code and the following message: "The email address has already been registered to one of your team members".

The following example creates a new team member who can sign in to the two locations specified by the location_ids array:

The following response contains the new team member with a unique ID that's used when assigning the team member to a wage level created in a subsequent operation:

{
  "team_member": {
    "id": "K6JiNAakLUf5lUYmfjn",
    "given_name": "Joe",
    "family_name": "Doe",
    "status": "ACTIVE",
    "assigned_locations": {
      "location_ids": [
        "{LOCATION_ID 1}",
        "{LOCATION_ID 2}"
      ],
      "assignment_type": "EXPLICIT_LOCATIONS"
    },
    "email_address": "[email protected]"
  }
}

After the team member is created, you assign a wage and job assignment to the team member.

With the Team API, you can now assign, update, and retrieve wages and job titles for a team member. WageSetting is considered a subresource of TeamMember because a WageSetting can't exist as a standalone entity. It always exists in the context of a team member.

The job title and job ID fields in the WageSetting object are backed by a job record kept by Square. When you provide a new job title (that is, a title that has never been used in the seller's Square account), Square creates a new job record with a unique ID. That job can now be assigned to any team member by updating their job assignments with that exact job title.

Be sure to assign a standard title to all team members who have the same job. For example, use "Bartender" for all of the seller's bartenders. Your UI should provide an enumerated list of job titles for team members to choose from. If a team member provides a job title using an entry field, Square adds a job for each variation of the spelling of "Bartender" that's entered when a team member is created.

Assigning a job title and wage to a team member consists of the following tasks:

1. Creating or updating a set of JobAssignment objects.
2. Setting an overtime exempt status.

The UpdateWageSetting endpoint is used to assign and update job titles and wages for each team member. To assign a wage, the job title entity must be set in the JobAssignment. If the job title doesn't exist, you can specify a new job title within a new JobAssignment. Each job assignment has only one wage and either an hourly or salary pay type. You can also specify whether the team member is exempt from overtime.

The following example assigns a wage to a team member:

The following response contains the team member overtime_exempt status and a list of ordered job assignments with corresponding wages:

{
  "wage_setting":  {
    "team_member_id": "K6JiNAakLUf5lUYmfjn",
    "is_overtime_exempt": true,
    "job_assignments": [
      {
        "job_title": "Manager",
        "job_id": "c8-6JiNAakLUf5lUYmfj"
        "pay_type": "SALARY",
        "annual_rate": {
          "amount": 1000000,
          "currency": "USD"
        },
        "hourly_rate": {
          "amount": 1443,
          "currency": "USD"
        },
        "weekly_hours": 40
      }
    ],
    "version": 2,
    "created_at": "2020-02-05T19:09:37+00:00",
    "updated_at": "2020-02-06T19:09:37+00:00"
  }
}

1. In the left pane of the Seller Dashboard, choose Team.
2. In the left pane, choose Team Members, and then choose a team member from the Name list.
3. In the Permissions section, choose Edit.
4. Choose the Permission set to apply to the team member.
5. Set a Personal Passcode for the team member.
6. Choose Save.

Square sends an email message to the team member with an invitation to sign in to their Square account using the personal passcode assigned.

The list of job assignments in a wage_setting is treated as a single object that is created or updated as a whole. If you want to add an additional job assignment to the first (primary) job assignment, the update request body must contain a job assignments list that includes the existing job assignment and any new or updated job assignments. If you want to reorder existing job assignments to make a different job assignment the primary assignment, send a wage setting update request with the full set of reordered job assignments.

If you want to change the title of an existing job, you must use the Team application in the Seller Dashboard.

1. In the left pane of the Seller Dashboard, choose Team.

2. In the left pane, choose Team Members, and then choose a team member from the Name list.

3. In the Job and compensation section, choose Edit job.

4. Update the job title, and then choose save.

5. Repeat these steps for each person's job title you want to change.

   All job assignments with this ID (for any team member) and Labor API shifts with this job ID are updated to show the new job title.

When you use the UpdateWageSetting endpoint, you can only assign existing jobs to a team member or create new jobs (a new job record). You can't change the title of a job record using the Team API. Assign a job to a team member by providing a job title that exactly matches an existing job. If the title that you updated the wage setting with doesn't already exist, a new job is created with that title and a new ID.

The RetrieveWageSetting operation returns the wages and job titles of a single team member based on the ID provided in the request.

EMPLOYEES_READ OAuth permission must be granted to your application for this operation.

The response contains the team member overtime_exempt status and a list of ordered job assignments with corresponding wages. The first job assignment in job_assignments is the primary job assignment.

{
  "wage_setting":  {
    "team_member_id": "K6JiNAakLUf5lUYmfjn",
    "is_overtime_exempt": true,
    "job_assignments": [
      {
        "job_title": "Manager",
        "job_id": "c8-6JiNAakLUf5lUYmfj",
        "pay_type": "SALARY",
        "annual_rate": {
          "amount": 3000000,
          "currency": "USD"
        },
        "hourly_rate": {
          "amount": 1443,
          "currency": "USD"
        },
        "weekly_hours": 40
      }
    ],
    "version": 2,
    "created_at": "2020-02-05T19:09:37+00:00",
    "updated_at": "2020-02-06T19:09:37+00:00"
  }
}

If you're using the optional versioning feature of wage settings, you need to get the current version number of a wage setting to be updated before issuing the update request. The response contains the version number of the wage setting, which in this case is 2.

If the specified team member or wage setting doesn't exist, an empty wage_setting object is returned.

In the following update requests, the version number from the retrieve request is used. After each update request, use the version number in the response for a subsequent update request.

The following request replaces the job assignment of Manager with Supervisor:

If "Supervisor" is an existing job title, its job ID and title are set in the WageSetting by Square. Otherwise, a new job is created and associated with the WageSetting.

The following request adds the job assignment of Bookkeeper:

The following request makes Bookkeeper the primary job assignment:

Use the UpdateTeamMember endpoint to activate or deactivate a team member, set or clear assigned locations, add an email address, or make other updates to a TeamMember object.

Updating a team member involves the following tasks:

1. Retrieving the team member to be updated if you don't have the team member ID. Use the SearchTeamMembers endpoint to get a list of team members by location ID.

2. Declaring a TeamMember object whose field list includes values to be updated and values to be cleared. The id field is read-only and identifies the team member to be updated.

In the following example, team member Bob is being deactivated:

The following response provides an updated TeamMember object for Bob:

{
  "team_member": {
    "id": "K6JiNAakLUf5lUYmfjn",
    "given_name": "Bob",
    "family_name": "Doe",
    "status": "INACTIVE",
    "assigned_locations": {
      "location_ids": [
        "{LOCATION_ID 1}",
        "{LOCATION_ID 2}"
      ],
      "assignment_type": "EXPLICIT_LOCATIONS"
    },
    "email_address": "[email protected]",
    "created_at": "2020-02-05T19:09:37+00:00"
  }
}

Bulk operations are non-atomic. The failure of one create operation doesn't prevent other create operations from succeeding. Errors from failed operations are returned in results and keyed by the idempotency key assigned in the request.

Setting up new team members in a bulk operation involves the following tasks:

1. Creating a set of team members with a specified location.

   {
     "team_member_1": {
       "given_name": "Joe",
       "family_name": "Doe",
       "assigned_locations": {
         "location_ids": [
           "{LOCATION_ID 1}",
           "{LOCATION_ID 2}"
         ],
         "assignment_type": "EXPLICIT_LOCATIONS"
       },
       "email_address": "[email protected]"
     },
     "team_member_2": {
       "given_name": "Harper",
       "family_name: "Smith",
       "assigned_locations": {
         "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
       },
       "email_address": "[email protected]"
     }
   }

2. Wrapping the set of team members with associated operation idempotency keys in a BulkCreateTeamMembersRequest object.

   {
     "team_members": {
       "Cf634970-17a0-403c-9c3b-21c399d2b6ea" : {
         // team_member_1 goes here
       },
       "40468e44-41f2-48e9-887e-60b0d52c8630" : {
         //team_member_2 goes here
       }
     }
   }

   The BulkCreateTeamMembersRequest object is a map of application-defined idempotency keys and CreateTeamMemberRequest objects representing individual create operations.

   EMPLOYEES_WRITE OAuth permission must be granted to your application for these operations.

   Bulk create team members

   cURL

   The response provides a BulkCreateTeamMembersResponse map. The map keys identify the requested operations and TeamMember or error objects represent the result of each operation.

    {
      "team_members": {
        "Cf634970-17a0-403c-9c3b-21c399d2b6ea" : {
          "team_member": {
            "id": "K6JiNAakLUf5lUYmfjn",
            "given_name": "Joe",
            "family_name": "Doe",
            "status": "ACTIVE",
            "assigned_locations": {
              "location_ids": [
                "{LOCATION_ID 1}",
                "{LOCATION_ID 2}"
              ],
              "assignment_type": "EXPLICIT_LOCATIONS"
            },
            "email_address": "[email protected]"
          }
        },
        "40468e44-41f2-48e9-887e-60b0d52c8630" : {
          "team_member": {
            "id": "4O2xVQah-8Ql2MJKpS9I",
            "given_name": "Harper",
            "family_name": "Smith",
            "status": "ACTIVE",
            "assigned_locations": {
              "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
            },
            "email_address": "[email protected]"
          }
        }
      }
    }

Use the BulkUpdateTeamMembers operation to activate or deactivate a group of team members or to set or clear their locations. You can also use the operation to batch a set of individual and unrelated team member update operations.

Bulk operations are non-atomic. The failure of one operation doesn't prevent other operations from succeeding. Errors from failed operations are returned in results and keyed by the idempotency key assigned in the request.

Updating team members in a bulk operation involves the following tasks:

1. Declaring a set of TeamMember objects whose field list includes values to be updated and values to be cleared.

   {
     "team_member": {
       "given_name": "Bob",
       "status": "INACTIVE"
     }
   }

2. Wrapping the set of team members in a BulkUpdateTeamMembersRequest object. EMPLOYEES_WRITE OAuth permission must be granted to your application for these operations.

   The BulkUpdateTeamMembersRequest object is a map of team member IDs and UpdateTeamMemberRequest objects representing individual create operations.

   In this operation, the first team member is getting assigned to all seller locations and the last name is being updated. The second team member is getting assigned to specific locations and removing the email address.

   Bulk update team members

   cURL

   The response provides a BulkUpdateTeamMembersResponse map. The map keys identify the requested operations and TeamMember or error objects represent the result of each operation.

   {
     "team_members": {
       "K6JiNAakLUf5lUYmfjn" : {
         "team_member": {
           "id": "K6JiNAakLUf5lUYmfjn",
           "given_name": "Joe",
           "family_name": "McGee",
           "status": "ACTIVE",
           "assigned_locations": {
             "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
           },
           "email_address": "[email protected]",
           "created_at": "2020-02-05T19:09:37+00:00"
         }
       },
       "4O2xVQah-8Ql2MJKpS9I" : {
         "team_member": {
           "id": "4O2xVQah-8Ql2MJKpS9I",
           "given_name": "Harper",
           "family_name": "Smith",
           "status": "ACTIVE",
           "assigned_locations": {
             "location_ids": ["{LOCATION_ID 1}"],
             "assignment_type": "EXPLICIT_LOCATIONS"
           },
           "created_at": "2020-02-05T19:09:37+00:00"
         }
       }
     }
   }

Use the SearchTeamMembers endpoint to get a list of team members by location ID and status. EMPLOYEES_READ OAuth permission must be granted to your application for this operation. To return all team members, don't specify any query filters.

The following example asks for a list of all active team members whose location assignment includes location ID "{LOCATION_ID 2}":

The response includes two active employees, one of whom is assigned to multiple locations, including the filtered location.

{
  "team_members": [
    {
      "id": "K6JiNAakLUf5lUYmfjn",
      "given_name": "Joe",
      "family_name": "McGee",
      "status": "ACTIVE",
      "assigned_locations": {
        "location_ids": [
          "{LOCATION_ID 1}",
          "{LOCATION_ID 2}"
        ],
        "assignment_type": "EXPLICIT_LOCATIONS"
      },
      "email_address": "[email protected]",
      "created_at": "2020-02-05T19:09:37+00:00",
      "updated_at": "2020-02-06T19:09:37+00:00"
    }, 
    {
      "id": "4O2xVQah-8Ql2MJKpS9I",
      "given_name": "Harper",
      "family_name": "Smith",
      "status": "ACTIVE",
      "assigned_locations": {
        "location_ids": [
          "{LOCATION_ID 2}"
        ],
        "assignment_type": "EXPLICIT_LOCATIONS"
      },
      "email_address": "[email protected]",
      "created_at": "2020-02-05T19:09:37+00:00",
      "updated_at": "2020-02-06T19:09:37+00:00"
    }
  ]
}

The RetrieveTeamMember endpoint returns a single TeamMember value based on the ID provided in the request.

EMPLOYEES_READ OAuth permission must be granted to your application for this operation.

The response provides the requested TeamMember value.

{
  "team_member":  {
    "id": "4O2xVQah-8Ql2MJKpS9I",
    "given_name": "Harper",
    "family_name": "Smith",
    "status": "ACTIVE",
    "assigned_locations": {
      "location_ids": ["CHQV7VKNFR3SV"],
      "assignment_type": EXPLICIT_LOCATIONS
    },
    "email_address": "[email protected]",
    "created_at": "2020-02-05T19:09:37+00:00",
    "updated_at": "2020-02-06T19:09:37+00:00"
  }
}