Manage Team Data from Any Platform with Square Team API

This year, businesses made the difficult decision to reorganize their teams as they faced financial challenges and shifting business models. Now, as businesses begin to reopen, business owners need an easy and reliable way to make employees’ return to the workforce as seamless as possible. Whether it’s onboarding new employees or assigning wages to returning team members, back-office team management can be time consuming and time sensitive.

Square Team Management makes it easy with an all-in-one labor and access management solution that enables sellers to efficiently and securely manage their teams and businesses. The Team Management free offering enables sellers to track their team’s time directly from their Square Point of Sale, sync their timecards with Square Payroll, and control access for their team members ⁠— at no cost. The Team Management paid offering, known as Square Team Plus, provides additional features like multiple access levels through custom permission sets and advanced reporting tools. Until now, Team Management was only available within Square Point of Sale and Square Payroll.

Today, we’re excited to announce Square Team API, which extends Team Management to third-party platforms so team members and managers can access and edit team data from anywhere. Built on top of Team Management, Team API enables developers to create, update, search, and retrieve team member profiles, individually and in bulk, within the first-party product and on any third-party platform. This includes creating and managing each team member’s status, job title, location, and compensation information, saving sellers time when handling large volumes of team data.

Additionally, Team API automatically synchronizes team data across Square and third-party systems, so sellers can trust they have a single source of truth for reporting and forecasting. Whether a developer is building a custom HR solution or a workforce management app, they can use Team API to synchronize Team Management data in real time and enable users to edit team data on their platform. Plus, developers can unlock additional capabilities like controlling access permissions within Square Dashboard once the data has been synchronized across platforms.

Finally, Team API can be used in conjunction with Square Labor API to manage timekeeping for labor cost reporting, payroll, and overtime management. Together, Team API and Labor API offer a complete labor management solution, unified across all platforms that a seller uses.

How it works

Let’s say you’ve hired a few new team members for your coffee shop in Birmingham in the UK. You’d like to create accounts and assign wages within Square Team Management. First, you need to create a set of team members with a specified location as follows.

{
  "a team_member": {
    "given_name": "Joe",
    "family_name": "Doe",
    "assigned_locations": {
      "location_ids": ["BIRMINGHAM"],
      "assignment_type": "EXPLICIT_LOCATIONS"
    },
    "email_address": "[email protected]"
  },
  "team_member": {
    "given_name": "Harper",
    "family_name": "Smith",
    "assigned_locations": {
      "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
    },
    "email_address": "[email protected]"
  }
}

Then you need to wrap the set of team members in a BulkCreateTeamMembersRequest object.

  {
    "team_members": {
      "Cf634970-17a0-403c-9c3b-21c399d2b6ea" : {
     //... TeamMember object from 1
    },
       "40468e44-41f2-48e9-887e-60b0d52c8630" : {
    //... TeamMember object from 1
    }
  }
}

Now that you’ve created team member accounts in bulk, you can begin to assign wages. First, call the UpdateWageSetting endpoint to assign job titles and wages on each team member, as shown below.

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 can only have one wage, and has either an hourly or salary pay type. You can also specify whether or not the team member is exempt from overtime.

curl https://connect.squareup.com/v2/team-members/K6JiNAakLUf5lUYmfjn/wage-setting
 \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
  wage_setting: {
    is_overtime_exempt: true,  
    job_assignments: [
      {
        job_title: “Manager”,
        pay_type: “SALARY”,
        annual_rate: {
          amount: 3000000,
          currency: “GBP”
        },
        weekly_hours: 40
      }
    ]
  }
}'

Let’s say you want to search for an existing team member and retrieve their wage. You can call the SearchTeamMembers endpoint to get a list of team members by location ID and status.

 curl https://connect.squareup.com/v2/team-members/search \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
    query: {
      filter: {
        location_ids: [“BIRMINGHAM],
        status: ACTIVE
      }
    },
    limit: 2
  }'

Then retrieve that team member’s wage by calling the RetrieveWageSetting endpoint for the given team_member_id.

{
  "wage_setting": {
    "team_member_id": "4O2xVQah-8Ql2MJKpS9I",
    "is_overtime_exempt": true,
    "ordered_job_assignments": [
      {
        "id": "AUn5EdxPmRmCufu4omn6iCmR",
        "job_title": "Barista",
        "pay_type": "SALARY",
        "hourly_rate": {
          "amount": 964,
          "currency": "GBP"
        },
        "annual_rate": {
          "amount": 2000000,
          "currency": "GBP"
        },
        "weekly_hours": 40
      }
    ],
    "created_at": "2020-02-05T19:09:37+00:00",
    "updated_at": "2020-02-06T19:09:37+00:00",
    "version": 1
  },
  "errors": []
}

Get started

Team API is available publicly to developers in the U.S., Canada, UK, Japan, and Australia. The API is free for developers to use in Sandbox with access to all features across Team Management and Team Plus. In production, developers can build with the API for free on behalf of sellers with a free Team Management account. If developers want to access features related to Team Plus, they must build on behalf of sellers with a paid Team Plus subscription. If not, developers will see an error message indicating that they must upgrade to the paid tier to access those specific features.

Check out the Team API documentation to learn how to get started and access the API reference docs. We encourage developers to share their feedback on our community Slack channel or Square Developer Forums.

If you want to keep up to date with the rest of our content, be sure to follow this blog and our Twitter account, and sign up for our developer newsletter!