Employees API: Code Cookbook

Get a List of Active Employees

Get a paged list of active employees and display the results.

Web
Backend
Employees API
Labor API
cURL (Command Line)

Info you will need
Permalink Get a link to this section

  • An active location ID. Copy a valid Developer Account location ID from the Locations setting page of your Square application in the Developer Dashboard, or set the dashboard to Sandbox Settings mode and then copy a sandbox location ID.

Process Overview
Permalink Get a link to this section

The https://connect.squareup.com/v2/employees endpoint takes a GET request that includes filter and pagination instructions as URL parameters.

The following employee list request asks for all of a location's current employees:

  • At a specified location

  • Limit result page size to 20 employees

  • Are currently ACTIVE

Get a paged list of employees
Permalink Get a link to this section

curl https://connect.squareup.com/v2/employees?location_id=LOCATION_ID&status=ACTIVE&limit=20 \
 -H 'Content-Type: application/json'                       \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'

The response to the shift search request is an array of Employee objects that match the filter criteria. If more results are available, the response includes a cursor property: "cursor": "KFuNoJ1SQp1xkgb7EsxjSucfgx3K5PZbe0HifD22A43l03ZofED"

{
    "employees": [
        {
        {
            "id": "16LNfi7Kh1tAhDECMZEO",
            "first_name": "Jane",
            "last_name": "Smith",
            "location_ids": ["LOCATION_ID"],
            "status": "ACTIVE",
            "created_at": "2019-02-20T01:28:49Z",
            "updated_at": "2019-02-20T01:28:49Z"
        },
        {
            "id": "RkReoWaEZI3x22NwGIH4",
            "first_name": "Jane",
            "last_name": "Smith",
            "location_ids": ["LOCATION_ID"],
            "status": "ACTIVE",
            "created_at": "2019-02-20T01:28:49Z",
            "updated_at": "2019-02-20T01:28:49Z"
        },

        {
            "id": "m_Omc4Z7dswgz5pLrD6z",
             ...
        },
        {
            "id": "r4nBW_BWnCqoRqVKbdOR",
            ...
        },
        ...
    ],
    "cursor": "0:7UwZq_TWrobq7kcgHUP1"
}

Get the next page

To get the next page of results, make the following request, appending the cursor from the previous response:

curl https://connect.squareup.com/v2/employees?location_id=LOCATION_ID&status=ACTIVE&limit=20&cursor=0:7UwZq_TWrobq7kcgHUP1 \
 -H 'Content-Type: application/json'                       \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'

List details of each employee returned in the result set. Details include:

  • First name

  • Last name