Team API

Integration Guide

Use the Team API to automate creating and configuring team members 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.

Set up a new team member Permalink Get a link to this section

Setting up a new team member involves these tasks:

  1. Creating a TeamMember assigned to specified seller locations.

  2. Setting a wage rate and job assignment for the 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 Shift or CashDrawerShift.

Step 1: Create a team member Permalink Get a link to this section

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

Note

Use the ListLocations endpoint to get all locations for a seller.

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.

Use the following cURL command to create a new team member who can sign in to the two locations specified by the location_ids array:

Create Team Member
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
curl https://connect.squareup.com/v2/team-members \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "cf634970-17a0-403c-9c3b-21c399d2b6ea",
    "team_member": {
      "given_name": "Joe",
      "family_name": "Doe",
      "assigned_locations": {
        "location_ids": [
          "{{LOCATION_ID 1}}",
          "{{LOCATION_ID 2}}"
        ],
        "assignment_type": "EXPLICIT_LOCATIONS"
      },
      "email_address": "joedoe@gmail.com"
    }
  }'

The following response contains the new team member with a unique ID that is 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": "joedoe@gmail.com"
  }
}

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

Step 2: Assign a job title and wage Permalink Get a link to this section

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 cannot exist as a standalone entity. It always exists in the context of a team member.

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.

Note

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

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 does not 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.

Did you know?

Job titles are not normalized by the Team API. Your business logic is responsible for any job title standardization that a seller requires.

Use the following cURL command to assign a wage to a team member:

Update Wage Setting
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareup.com/v2/team-members/K6JiNAakLUf5lUYmfjn/wage-setting \
  -X PUT \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "wage_setting": {
      "is_overtime_exempt": true,
      "job_assignments": [
        {
          "job_title": "Manager",
          "pay_type": "SALARY",
          "annual_rate": {
            "amount": 1000000,
            "currency": "USD"
          },
          "weekly_hours": 40
        }
      ]
    }
  }'

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

Update job assignments Permalink Get a link to this section

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.

Important

wage_setting objects are optionally versioned for optimistic concurrency. If optimistic concurrency is important for your application, retrieve the object to be updated and then use that object version number in your subsequent update request.

Retrieve a wage setting for a team member Permalink Get a link to this section

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.

Retrieve Wage Setting
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/team-members/K6JiNAakLUf5lUYmfjn/wage-setting \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

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",
        "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 are 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 does not exist, an empty wage_setting object is returned.

Note

If you do not want to version wage settings, do not include a version field in your request. In that case, optimistic concurrency is not enforced and Square blindly overwrites the previous version of the wage setting for the team member.

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.

Update an existing job assignment Permalink Get a link to this section

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

{
  "wage_setting":  {
    "team_member_id": "K6JiNAakLUf5lUYmfjn",
    "is_overtime_exempt": true,
    "job_assignments": [
      {
        "job_title": "Supervisor",
        "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"
  }
}

Add a second job assignment Permalink Get a link to this section

The following request adds the job assignment of Bookkeeper:

{
  "wage_setting":  {
    "team_member_id": "K6JiNAakLUf5lUYmfjn",
    "is_overtime_exempt": true,
    "job_assignments": [
      {
        "job_title": "Supervisor",
        "pay_type": "SALARY",
        "annual_rate": {
          "amount": 1000000,
          "currency": "USD"
        },
        "hourly_rate": {
          "amount": 1443,
          "currency": "USD"
        },
        "weekly_hours": 40
      },
      {
        "job_title": "Bookkeeper",
        "pay_type": "SALARY",
        "annual_rate": {
          "amount": 400000,
          "currency": "USD"
        },
        "hourly_rate": {
          "amount": 1443,
          "currency": "USD"
        },
        "weekly_hours": 40
      }
            
    ],
    "version": 3,
    "created_at": "2020-02-05T19:09:37+00:00",
    "updated_at": "2020-02-06T19:09:37+00:00"
  }
}

Reorder job assignments Permalink Get a link to this section

The following request makes Bookkeeper the primary job assignment:

{
  "wage_setting":  {
    "team_member_id": "K6JiNAakLUf5lUYmfjn",
    "is_overtime_exempt": true,
    "job_assignments": [
      {
        "job_title": "Bookkeeper",
        "pay_type": "SALARY",
        "annual_rate": {
          "amount": 400000,
          "currency": "USD"
        },
        "hourly_rate": {
          "amount": 1443,
          "currency": "USD"
        },
        "weekly_hours": 40
      },
      {
        "job_title": "Supervisor",
        "pay_type": "SALARY",
        "annual_rate": {
          "amount": 1000000,
          "currency": "USD"
        },
        "hourly_rate": {
          "amount": 1443,
          "currency": "USD"
        },
        "weekly_hours": 40
      }
    ],
    "version": 4,
    "created_at": "2020-02-05T19:09:37+00:00",
    "updated_at": "2020-02-06T19:09:37+00:00"
  }
}

Update a team member Permalink Get a link to this section

Use the UpdateTeamMember operation 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 these tasks:

  1. Retrieving the team member to be updated if you do not have the team member ID.

    Use the SearchTeamMembers endpoint to get a list of team members by location ID.

  1. 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:

Update Team Member
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareup.com/v2/team-members/K6JiNAakLUf5lUYmfjn \
  -X PUT \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "team_member": {
      "status": "INACTIVE"
    }
  }'

The 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": "joedoe@gmail.com",
    "created_at": "2020-02-05T19:09:37+00:00"
  }
}

Bulk create team members Permalink Get a link to this section

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

Important

Bulk actions are limited to 25 operations per request.

Setting up new team members in a bulk operation involves these 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": "joedoe@gmail.com"
      },
      "team_member_2": {
        "given_name": "Harper",
        "family_name: "Smith",
        "assigned_locations": {
          "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
        },
        "email_address": "hsmith@gmail.com"
      }
    }
    
  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
    • 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
    curl https://connect.squareup.com/v2/team-members/bulk-create \
      -X POST \
      -H 'Square-Version: 2020-11-18' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{
        "team_members": {
          "Cf634970-17a0-403c-9c3b-21c399d2b6ea": {
            "team_member": {
              "given_name": "Joe",
              "family_name": "Doe",
              "assigned_locations": {
                "location_ids": [
                  "{{LOCATION_ID 1}}",
                  "{{LOCATION_ID 2}}"
                ],
                "assignment_type": "EXPLICIT_LOCATIONS"
              },
              "email_address": "joedoe@gmail.com"
            }
          },
          "40468e44-41f2-48e9-887e-60b0d52c8630": {
            "team_member": {
              "given_name": "Harper",
              "family_name": "Smith",
              "assigned_locations": {
                "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
              },
              "email_address": "hsmith@gmail.com"
            }
          }
        }
      }'

    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": "joedoe@gmail.com"
           }
         },
         "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": "hsmith@gmail.com"
           }
         }
       }
     }
    

Bulk update team members Permalink Get a link to this section

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 does not prevent other operations from succeeding. Errors from failed operations are returned in results and keyed by the idempotency key assigned in the request.

Important

Bulk actions are limited to 25 operations per request.

Updating team members in a bulk operation involves these 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
    • 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
    curl https://connect.squareup.com/v2/team-members/bulk-update \
      -X POST \
      -H 'Square-Version: 2020-11-18' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{
        "team_members": {
          "K6JiNAakLUf5lUYmfjn": {
            "team_member": {
              "email_address": "joemcgee_12@gmail.com",
              "family_name": "McGee",
              "assigned_locations": {
                "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
              }
            }
          },
          "4O2xVQah-8Ql2MJKpS9I": {
            "team_member": {
              "assigned_locations": {
                "location_ids": [
                  "{{LOCATION_ID 1}}"
                ],
                "assignment_type": "EXPLICIT_LOCATIONS"
              },
              "email_address": null
            }
          }
        }
      }'

    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": "joemcgee_12@gmail.com",
            "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"
          }
        }
      }
    }
    

Search for team members Permalink Get a link to this section

Use the SearchTeamMembers endpoint to get a list of team members by location ID and status.

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

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

Search Team Members
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareup.com/v2/team-members/search \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "{{LOCATION_ID 2}}"
        ],
        "status": "ACTIVE"
      }
    },
    "limit": 2
  }'

Note

The default limit in search results is 25. If you do not specify a limit, the resulting page of team members is 25 or the number of team members who pass the filter.

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": "joemcgee_12@gmail.com",
      "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": "hsmith3@gmail.com",
      "created_at": "2020-02-05T19:09:37+00:00",
      "updated_at": "2020-02-06T19:09:37+00:00"
    }
  ]
}

Retrieve a team member Permalink Get a link to this section

The RetrieveTeamMember operation 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.

Retrieve Team Member
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/team-members/4O2xVQah-8Ql2MJKpS9I \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

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": "hsmith3@gmail.com",
    "created_at": "2020-02-05T19:09:37+00:00",
    "updated_at": "2020-02-06T19:09:37+00:00"
  }
}