Integration Guide

Learn how to use the Team API to manage team members for a Square seller.

Overview

Applications can use the Team API to create and configure team members and jobs and to synchronize team member data with external platforms. The Team API supports individual and bulk updates to team members, including setting job descriptions and compensation.

Team members can be integrated into business operations. For example, they can be assigned to a work shift to track worked hours, associated with a cash drawer connected to Square Point of Sale, and assigned to an appointment segment in a booking.

Link to section

Requirements and limitations

Applications that use OAuth require the following permissions to call Team API endpoints:
- EMPLOYEES_READ is required for SearchTeamMembers, RetrieveTeamMember, RetrieveWageSetting, ListJobs, and RetrieveJob.
- EMPLOYEES_WRITE is required for CreateTeamMember, BulkCreateTeamMembers, UpdateTeamMember, BulkUpdateTeamMembers, UpdateWageSetting, CreateJob, and UpdateJob.
Permissions, permission sets, and passcodes cannot be accessed using the Team API. Sellers use the Square Dashboard to assign permissions and passcodes to team members, after which Square emails an invitation to join the team and create a Square account.
Square recommends using Job and TeamManager endpoints to manage jobs and wage settings instead of RetrieveWageSetting and UpdateWageSetting.
These Beta features are added in Square API version 2024-12-18.
- The CreateJob, UpdateJob, ListJobs, and RetrieveJob endpoints, Job object, and JobAssignment.job_id field.
- TeamMember.wage_setting field. This field lets applications use CreateTeamMember, RetrieveTeamMember and other TeamMember endpoints to access and manage job assignments and compensation for team members.
The wage_setting and job_id fields are available to all API versions, but using Square SDKs to access them requires the corresponding Square SDK version or higher.

For more information and other considerations, see Requirements and limitations.

Link to section

Set up new team members

Using the Team API, first retrieve the jobs that team members can do and then create the team members. After a team member is created, sellers can assign team permissions in the Square Dashboard.

Link to section

1. List jobs

To assign jobs to a team member, you need to provide the corresponding job IDs. To get all jobs in a seller account, call ListJobs, as shown in the following example request:

List jobs

If you need to create a new job, call CreateJob and specify the job title and tip eligibility.

Note

Job endpoints are available in Square API version 2024-12-18 or higher.

Link to section

2. Create team members

To create team members, call one of the following endpoints:

CreateTeamMember - Create a single team member.
BulkCreateTeamMembers - Create multiple team members.

For each team member, provide profile and job information:

given_name and family_name - The team member's first and last name. These fields are required to create a team member.
assigned_locations - The locations where the team member's permissions apply.
Valid values for assignment_type:
- ALL_CURRENT_AND_FUTURE_LOCATIONS - Assigns the team member to all of the seller's locations, including locations added in the future. Any location_ids setting is ignored.
- EXPLICIT_LOCATIONS - Used with location_ids to assign the team member to specific locations. Use ListLocations to get the seller's locations.
  If assigned_locations is omitted, assignment_type defaults to EXPLICIT_LOCATIONS. For sellers with one location, the team member is assigned to that location. With multiple locations, the team member isn't assigned to any, so you must explicitly specify location_ids later.
email_address - The email address for the team member, which must be unique across team members in the seller account. Square sends an invitation to this address after team permissions are assigned in the Square Dashboard.
phone_number - The team member's phone number in E.164 format: +[country code][area code][subscriber number].
wage_setting - The team member's overtime exemption status and job assignments with compensation.
- is_overtime_exempt - Whether the team member is exempt from overtime rules.
- job_assignments - The list of jobs the team member can do, with the primary job listed first. For each job assignment, specify:
  - job_id - The job ID returned in the ListJobs or CreateJob response.
  - pay_type - The job's pay type.
    For HOURLY pay types, also provide hourly_rate.
    For SALARY pay types, also provide annual_rate and weekly_hours. Square uses these values to calculate the hourly rate.
    For jobs that don't have a pay type, such as volunteer positions, specify NONE.
Note
The TeamMember.wage_setting field (added in Square API version 2024-12-18) lets you access and manage wage settings using TeamMember endpoints instead of RetrieveWageSetting and UpdateWageSetting.
reference_id - An external team member ID. This field is recommended if you synchronize team members with an external platform.

Link to section

Create a single team member

To create a single team member, call CreateTeamMember. The following example request creates a team member assigned to the Manager job in two locations:

Create team member

This example includes the optional idempotency key to ensure the request is processed one time only.

Link to section

Create multiple team members

To create 1 to 25 team members in a bulk operation, call BulkCreateTeamMembers and provide a map of key-value pairs that represent individual create requests. For each key-value pair, the key is an idempotency key and the value is the team member data.

Bulk operations are non-atomic. Each individual create request returns a success or failure response within the bulk operation response.

Creating new team members in a bulk operation includes the following steps:

Define individual create requests that contain team member data.

{
  "team_member": {
    "given_name": "Joe",
    "family_name": "Doe",
    "assigned_locations": {
      "location_ids": [
        "L5MD8YG8Q3S02",
        "CHQV7VKNFR3SV"
      ],
      "assignment_type": "EXPLICIT_LOCATIONS"
    },
    "email_address": "[email protected]",
    "phone_number": "+12085551235",
    "wage_setting": {
      "is_overtime_exempt": true,  
      "job_assignments": [
        {
          "job_id": "FjS8x95cqHiMenw4f1NAUH4P",
          "pay_type": "SALARY",
          "annual_rate": {
            "amount": 6000000,
            "currency": "USD"
          },
          "weekly_hours": 40
        }
      ]
    }
  }
}

Assign a unique idempotency key to individual create requests and add them to the team_members map.

{
  "team_members": {
    "{UNIQUE_KEY 1}" : {
      // create request for team member 1 goes here
    },
    "{UNIQUE_KEY 2}" : {
      // create request for team member 2 goes here
    }
  }
}

Call BulkCreateTeamMembers and provide the team_members map.
Bulk create team members

Link to section

3. Assign team member permissions in the Square Dashboard

After the team member is created, the seller needs to assign permissions to the team member in the Team section of the Square Dashboard. Permissions, permission sets, and passcodes cannot be accessed using the Team API.

The following steps describe how you can simulate the seller experience using your own account.

In the Square Dashboard, in the left pane, choose Team.
On the Team Members page, choose the new team member from the Name list to open their details pane.
Select a permission set for the team member and enter or generate a personal passcode, then choose Save.
Square sends an email to the team member with an invitation to join the team.

For more information about how sellers manage their team, see Add and manage team members.

Note

The code examples in this topic call Square APIs in the production environment. Alternatively, you can use the https://connect.squareupsandbox.com/v2 domain to create team members in the Square Sandbox and then view them in the Sandbox Square Dashboard. However, the Sandbox Square Dashboard doesn't support testing these permission-related steps.

Link to section

Update team members

You can use the Team API to activate or deactivate team members and update assigned locations or other profile information. You can also update wage settings, including job assignments and compensation.

Note the following exceptions:

The Team API cannot be used to update the team member that represents the seller account. In the API, this team member has the is_owner field set to true. The seller can update their profile in the Square Dashboard.
After accepting the invitation to join the team, the Team API cannot be used to update the team member's email address. Only the team member can change their email address by updating their personal settings on the Square website.
Job assignments don't support sparse updates so you must provide the complete job_assignments list when updating this field.

Link to section

1. Retrieve team members

If you need to get team member IDs or other details, call SearchTeamMembers. If you have the team member ID but need to get other details, call RetrieveTeamMember.

Link to section

2. Update team members

To update team members, call one of the following endpoints:

UpdateTeamMember - Update a single team member.
BulkUpdateTeamMembers - Update multiple team members.

These endpoints support sparse updates. For each team member, you only need to include fields you want to add or change. To clear an optional field, specify null. The following fields can be updated:

given_name and family_name - The team member's first and last name.
assigned_locations - The locations where the team member's permissions apply.
Valid values for assignment_type:
- ALL_CURRENT_AND_FUTURE_LOCATIONS - Assigns the team member to all of the seller's locations, including locations added in the future. Any location_ids setting is ignored.
- EXPLICIT_LOCATIONS - Used with location_ids to assign the team member to specific locations. Use ListLocations to get the seller's locations.
  If assigned_locations is omitted, assignment_type defaults to EXPLICIT_LOCATIONS. For sellers with one location, the team member is assigned to that location. With multiple locations, the team member isn't assigned to any, so you must explicitly specify location_ids later.
email_address - The email address for the team member, which must be unique across team members in the seller account. Square sends an invitation to this address after team permissions are assigned in the Square Dashboard.
The Team API cannot update this field after the team member joins the team.
phone_number - The team member's phone number in E.164 format: +[country code][area code][subscriber number].
wage_setting - The team member's overtime exemption status and job assignments with compensation.
- is_overtime_exempt - Whether the team member is exempt from overtime rules.
- job_assignments - The complete list of jobs the team member can do, with the primary job listed first. For each job assignment, specify:
  - job_id - The job ID returned in the ListJobs or CreateJob response.
  - pay_type - The job's pay type.
    For HOURLY pay types, also provide hourly_rate.
    For SALARY pay types, also provide annual_rate and weekly_hours. Square uses these values to calculate the hourly rate.
    For jobs that don't have a pay type, such as volunteer positions, specify NONE.
To enable optimistic concurrency control for the wage setting update, include version set to the current wage setting version.
Note
The TeamMember.wage_setting field (added in Square API version 2024-12-18) lets you access and manage wage settings using TeamMember endpoints instead of RetrieveWageSetting and UpdateWageSetting.
For applications that continue to use UpdateWageSetting, you must provide the complete WageSetting object.
reference_id - An external team member ID. This field is recommended if you synchronize team members with an external platform.

Link to section

Update a single team member

To update a single team member, call UpdateTeamMember and specify the team_member_id. The following example request deactivates a team member.

Update team member

Link to section

Update multiple team members

To update 1 to 25 team members in a bulk operation, call BulkUpdateTeamMembers and provide a map of key-value pairs that represent individual update requests. For each key-value pair, the key is the team member ID and the value is the team member data.

Bulk operations are non-atomic. Each individual update request returns a success or failure response within the bulk operation response.

Updating team members in a bulk operation includes the following steps:

Define individual update requests that specify the fields that you want to add, change, or clear.

{
  "team_member": {
    "family_name": "McGee",
    "assigned_locations": {
      "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
    }
  }
}

Assign the team member ID to individual update requests and add them to the team_members map.

{
  "team_members": {
    "{TEAM_MEMBER_ID 1}" : {
      // update request for team member 1 goes here
    },
    "{TEAM_MEMBER_ID 2}" : {
      // update request for team member 2 goes here
    }
  }
}

Call BulkUpdateTeamMembers and provide the team_members map.
The following example updates two team members. The first update request changes the last name and location assignment type. The second update request updates the assigned locations and job assignments and removes the phone number.
Bulk update team members

Link to section

Examples: Update job assignments

The following example UpdateTeamMember requests add, remove, or reorder job assignments and change the pay rate. The first job assignment is considered the team member's primary job.

When adding or changing job assignments, you can call ListJobs to get job IDs.

Reactivate the team member and specify a single job assignment:

Update team member

These examples include the version field to enable optimistic concurrency control for wage setting updates.

Link to section

List or search for team members

Use the SearchTeamMembers endpoint to get a list of team members, optionally filtered by location, status, or whether the team member is the owner. If needed, call ListLocations to get the seller's locations. To return all team members, don't specify any filters.

If you're looking for a particular team member, iterate through the results and check the phone_number, email_address, or other fields to see if there's a match.

Note

As a best practice, check the team member's status if you're retrieving team member data to perform a business activity. In many cases, only ACTIVE team members are applicable.

The following example lists all active team members whose location assignment includes the specified location ID. The limit field specifies a page size of 2. The default and maximum page size is 25.

Search team members

If the SearchTeamMembers response includes a cursor field, append the cursor to your previous request and resend it to retrieve the next page of results. Repeat this process until the response no longer contains a cursor. For more information, see Pagination.

Link to section

Retrieve a team member

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

Retrieve team member

Link to section

Manage jobs (Beta)

Square provides the following Job endpoints to create and manage jobs. A job defines a title and tip eligibility. Jobs are referenced by job assignments, which also include compensation information for a team member. A team member's job assignments are accessed and managed from the wage_setting.job_assignments field.

CreateJob - To create a job, call CreateJob and specify the title and tip eligibility. The title field is required and is_tip_eligible defaults to true.

UpdateJob - To change a job title or its tip eligibility, call UpdateJob. All job assignments (for any team member) and all Shift and TeamMemberWage objects in the Labor API that use this job ID are updated to show the new job title.

ListJobs or RetrieveJob - To get job IDs or other details, call ListJobs or call RetrieveJob if you have the job ID. ListJobs has a page size of 100 and returns jobs sorted by title in ascending order.

Job endpoints are available in Square API version 2024-12-18 or higher.

Link to section

Synchronize team members with an external platform

Applications that interact with team members for scheduling, payroll, accounting, and other purposes might need to periodically synchronize with Square to ensure data consistency. Synchronization between the external platform and Square can be bi-directional or one-way.

Link to section

Sync from an external platform to Square

Use the Team API to push changes to a Square seller account when team members are created or updated in your platform.

Link to section

Creating team members

Adding a new team member in Square includes creating the team member and then configuring job assignments and compensation. For more information, see Set up a new team member and List or search for team members.

This process might use the following endpoints:

Use ListJobs to get job IDs to configure job assignments in the team member's wage setting.
Use ListLocations to get location IDs to configure explicitly assigned locations.
Use SearchTeamMembers if you need to check whether a team member already exists. Omit the status filter to make sure that you're retrieving both activated and deactivated team members.
Use CreateTeamMember or BulkCreateTeamMembers to create one or more team members. It's a good practice to store the team member ID from your platform in the TeamMember.reference_id field and store the TeamMember.id field in your platform.

Note

Square recommends using TeamMember and Job endpoints to manage job assignments and compensation when possible. Previously, applications had to call UpdateWageSetting. (Learn more.)

Link to section

Updating team members

Updates to team member details include changing contact information, assigned locations, or the status to activate or deactivate the team member. For more information, see Update team members.

This process might use the following endpoints:

Use ListJobs to get job IDs to configure job assignments in the team member's wage setting.
Use ListLocations to get location IDs to configure explicitly assigned locations.
Use SearchTeamMembers to get the team member ID or other details. You can call RetrieveTeamMember if you have the team member ID but need to get other details.
Use UpdateTeamMember or BulkUpdateTeamMembers to update one or more team members.

Note

Square recommends using TeamMember and Job endpoints to manage job assignments and compensation when possible. Previously, applications had to call UpdateWageSetting. (Learn more.)

Link to section

Sync from Square to an external platform

To sync to an external platform, your application gets team member updates from Square and writes them to your platform. Common strategies include using webhook notifications, intermittent polling, or both.

Link to section

On notification of a change

Subscribe to the following webhook events to be notified about team member changes:

The team_member.created and team_member.updated notification payload includes the new or updated TeamMember object. The team_member.wage_setting.updated payload includes the new or updated WageSetting object.

For more information about using webhooks, see Square Webhooks. Note that the Events API can be used with webhook subscriptions for recovery and reconciliation of missed webhook events.

Link to section

Regular interval polling

On a set time interval, poll for changes to team member details or job assignments and compensation. The following steps use the timestamp of your last sync to determine whether you need to update the data stored in your external platform.

Call SearchTeamMembers and iterate through the list of TeamMember objects returned in each paged response.
Check the TeamMember.updated_at timestamp and the TeamMember.wage_setting.updated_at timestamp. If either timestamp is greater than the timestamp of your last sync, write the data to your platform.
As a best practice, check the team member's status if you're retrieving team member data to perform a business activity. For many use cases, only ACTIVE team members are applicable.

If you regularly poll to synchronize stored team member data, you can use webhooks and increase the time between your polling.

Note

Square recommends using TeamMember and Job endpoints to retrieve job assignments and compensation when possible. Previously, applications had to call RetrieveWageSetting. (Learn more.)

Warning

Applications that send many requests in a short time might be subject to rate limiting by Square.

Link to section

RetrieveWageSetting and UpdateWageSetting

The RetrieveWageSetting and UpdateWageSetting endpoints are used to access and manage a team member's job assignments and compensation by interacting with a WageSetting object associated with the team member.

New features added in Square API version 2024-12-24 provide new, recommended ways to access and manage wage settings and jobs:

A new TeamMember.wage_setting field that lets you access and manage a team member's job assignments and compensation using TeamMember endpoints.
A new Job object and CreateJob, UpdateJob, ListJobs, and RetrieveJob endpoints.
A new JobAssignment.job_id field that references the job ID.

Square API version 2024-12-18 or higher is required to use Job endpoints. In addition, using a Square SDK to access the TeamMember.wage_setting and JobAssignment.job_id fields requires the corresponding Square SDK version or higher.

Link to section

RetrieveWageSetting

To get the team member's current wage setting, call RetrieveWageSetting and specify the team_member_id. Use SearchTeamMembers to get the team member ID.

Retrieve wage setting

Note

Square recommends using RetrieveTeamMember or SearchTeamMembers instead of RetrieveWageSetting when possible.

Link to section

UpdateWageSetting

To add or update the team member's wage setting, call UpdateWageSetting and specify the team_member_id. Use SearchTeamMembers to get the team member ID.

You must provide the complete WageSetting object in the request. To enable optimistic concurrency control, include version set to the current wage setting version.

Update wage setting

Note

Square recommends using CreateTeamMember, BulkCreateTeamMembers, UpdateTeamMember, or BulkUpdateTeamMembers instead of UpdateWageSetting when possible.

Applications that use UpdateWageSetting must specify job_id (recommended) or job_title for job assignments, and this setting must be consistently applied to all job assignments in the request. If you specify both job_id and job_title, job_title is ignored. Call ListJobs to get job IDs.

If you specify only job titles, make sure to:

Specify the exact, case-sensitive title of an existing job unless you want to create a new job.
Assign the same title to all team members who have the same job.

For example, use "Bartender" for all of the seller's bartenders. To avoid creating new job types based on spelling variations, your UI should provide an enumerated selection of job titles instead of letting team members input a job title.

Link to section

Docs

Integration Guide

On this page

Overview

Requirements and limitations

More details

Set up new team members

1. List jobs

Note

2. Create team members

More details

More details

Note

Create a single team member

Create multiple team members

3. Assign team member permissions in the Square Dashboard

Note

Update team members

1. Retrieve team members

2. Update team members

More details

More details

Note

Update a single team member

Update multiple team members

Examples: Update job assignments

List or search for team members

Note

Retrieve a team member

Manage jobs (Beta)

Synchronize team members with an external platform

Sync from an external platform to Square

Creating team members

Note

Updating team members

Note

Sync from Square to an external platform

On notification of a change

Regular interval polling

Note

Warning

RetrieveWageSetting and UpdateWageSetting

RetrieveWageSetting

Note

UpdateWageSetting

Note

See also

On this page