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.

The 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.assigment_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 is to be able to access all of a seller's locations, set the assigment_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:

curl https://connect.squareupsandbox.com/v2/team-members \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}'
{
  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 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 actions:

  1. Setting or creating a JobAssignment.

  2. Setting an overtime exempt status.

Note: The 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 on 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:

curl https://connect.squareupsandbox.com/v2/team-members/K6JiNAakLUf5lUYmfjn/wage-setting
 \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}'
{
  wage_setting: {
    is_overtime_exempt: true,  
    job_assignments: [
      {
        job_title: "Manager",
        pay_type: "SALARY",
        annual_rate: {
          amount: 1000000,
          currency: USD
        },
        weekly_hours: 40
      }
    ]
  }
}

The 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"
  },
  errors: []
}

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:

curl https://connect.squareupsandbox.com/v2/team-members/K6JiNAa \
  -X PUT \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}'
{
  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: {
     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: {
     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" : {
    … //TeamMember object from 1.
      },
      "40468e44-41f2-48e9-887e-60b0d52c8630" : {
    … //Another TeamMember object from 1.
      }
    }
    

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

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

     curl https://connect.squareupsandbox.com/v2/team-members/bulk-create
      \
       -X POST \
       -H 'Content-Type: application/json' \
       -H 'Square-Version: 2020-06-25' \
       -H 'Authorization: Bearer {{AUTH TOKEN}}'
     {
       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.

     {
       responses: {
         "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"
           },
           Errors:[]
         },
         "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"
           },
           errors:[]
         }
       },
       errors: []
     }
    

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

     curl https://connect.squareupsandbox.com/v2/team-members/bulk-update
      \
       -X POST \
       -H 'Content-Type: application/json' \
       -H 'Square-Version: 2020-06-25' \
       -H 'Authorization: Bearer {{AUTH TOKEN}}'
     {
       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.

     {
       responses: {
         "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"
           },
           errors:[]
         },
         "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"
           },
           errors:[] 
         }
       },
       errors: []
     }
    

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

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

curl https://connect.squareupsandbox.com/v2/team-members/search
 \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}'
{
  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"
    }
  ],
  errors:[]
}

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.

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

curl https://connect.squareupsandbox.com/v2/team-members/4O2xVQah-
 \
  -X GET \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}'

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"
  },
  errors: []
}

Retrieve a wage setting
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.

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

curl https://connect.squareupsandbox.com/v2/team-members/K6Jijn/wage-setting
 \
  -X GET \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}'

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"
  },
  errors: []
}