Users API

Field Squared supports a RESTful API that handles both single object and list operations.

Users in Field Squared are written to the API as either a single user or a list of user objects. For most integrations we recommend doing batch updates of users (create, update) as array operations.

For additional rules around API data types and data handling, please see the API Usage Notes article. All requests to our API must be authenticated with our authentication service. Please read our article on Authenticated HTTP headers and the correct HTTP methods.

User Object Payload

A user has the following structure by default. We'll explore the makeup of a user throughout this article.

{
        "ExternalId": "7a6a8fa2-b3d0-4c47-aae3-c5ee3de3b6a8",
        "Name": "John Smith",
        "Initials": "JS",
        "Phone": "303 555 5555",
        "Email": "john@fieldsquared.com",
        "UserType": "ViewOnly",
        "Image": "GwO4zZBUjLD4ghsz5s6SEg.jpg",
        "Lat":39.749911,
        "Lon":-105.000026,
        "StreetAddress": "1514 Blake St",
        "Unit": "Suite 200",
        "City": "Denver",
        "State": "CO",
        "Zip": "80202-1322",
        "SkillTags": [
            "TruckLicense"
        ],
        "Enabled": true,
        "Data": {
            "TextArea": "HELLO",
            "AUTO_NUM": "VVX74",
            "Number": "1234",
            "TIME": "00:30:00",
            "Date": "2017-01-23",
            "DateTime": "2017-01-27T19:14:46Z",
            "Barcode": "234234esfs"
        },
        "Teams": [
            "jTZv6YcMaStulDcIMOrs4AAA4A"
        ],
        "LastUpdated": "2017-01-30T18:43:22Z",
        "Created": "2017-01-30T18:43:22Z"
    }

Working with Single Users

For single user updates, Field Squared supports the HTTP methods GET, POST and DELETE.

Methods Supported: GET|POST|DELETE
URL: https://api.fieldsquared.com/workspace/api/user/externalid

Where workspace is the unique company ID issued to your company and External Id is the ID of the record in your existing system. Callers to this API must be authenticated and use the X-Auth-Token in the HTTP headers or the request will be rejected by the Field Squared firewall.

Example 1
GET https://api.fieldsquared.com/10/api/user/1234
will retrieve the user 1234 from workspace 10. The structure of the User returned will look like the payload above.

Example 2:
POST https://api.fieldsquared.com/10/api/user/4567
Creates or updates the user 4567 for workspace 10. Note that all required fields for the user must be populated for the create to be successful. The User object sent to us should look like the payload above.

Example 3:
DELETE https://api.fieldsquared.com/10/api/user/4567
Removes user 4567 from workspace 10. The user is not deleted permanently and is moved to the archived objects collection and can be restored from the recycle bin.

Working with Lists of Users

For list/array operations (eg. bulk read and write), Field Squared supports GET and POST operations. DELETE is not supported for list operations.

Methods Supported: GET|POST
URL: https://api.fieldsquared.com/workspace/api/user

Where workspace is the ID we assign to your company.

We support the following query parameters for GET operations:

• modifiedsince – returns all records modified/edited/created within the Field Squared platform since a given date and time. Dates are an ISO-8901 format date string in UTC time.

The User Class is extensible with custom fields (see below), therefore the API generation tool in App Builder should be used to create the exact API payload that is required for the User Class.

The payload for a list of users is simply an array of user objects like the example below.

[
  {
    "Name": "John Smith",
    "ExternalId": "1234",
    "UserType": "Dispatcher"
  },
  {
    "Name": "Mary Brown",
    "ExternalId": "1235",
    "UserType" : "Supervisor"
 }
]

Field Squared supports batch updates of multiple users, or sending through just a single user object in a request within a list.

Example 1
GET https://api.fieldsquared.com/10/api/user
This retrieves an array of user objects (see below) through the API. Query parameters for this API are supported to add filters to the request.

Example 2
POST https://api.fieldsquared.com/10/api/user
This example can bulk create or update users of type Boat where each item in the request will be created/updated in the Field Squared database.

Setting up the Message Body

See corresponding section under 'Task API'.  The User Object Type works identically.

Updating Records using the ExternalID

See corresponding section under 'Task API'.  The User Object Type works identically.

User API Properties

Core Properties

The core properties of a user are:

• Name (required) – the name of the user
• ExternalId (optional) – the unique ID of the record in your system. If omitted all items in the API request will result in a new record being created.
• User Type (required) – the type of this user.  The four user types available are "SubscriptionAdmin", "Dispatcher", "Supervisor", "Standard" and "ViewOnly".  The user type determines the level of access.  The permissions for each user type are configurable under App Builder->Workspace->Security as shown in the screenshot below:

• Name (required) – Full name for user.
• Initials (required) – User Initials (Shown in place of User Image if not assigned).
• Phone (optional) – User Mobile Number (Used for notification messages)
• Email (required) – Used for login as well as email notifications.
• Image (optional) – User Image (Used through the App to denote when user is assigned to Tasks, Teams etc).  Note that the image needs to be uploaded through the app.
• SkillTags (optional) – Skills Tags are defined in the app.  The SkillTags property is a list of strings.  Skill tags are used on both the User class and Task Class to enable a Dispatcher to find an available Field Worker with the skills required to complete a Task.
• Enabled – (required) – true/false boolean to indicate if the user is enabled and can login to the app.
• Teams – (optional) – List of ExternalID's of teams that the user is assigned to.  Teams control the visibility that the user has on Tasks, Assets and Contacts.
• IMPORTANT NOTE – User Password cannot be set through the public API.  It must be set through the application.

Minimum JSON body to create a single user

[
 {
   "Name": "John Smith",
   "Initials" : "JS",
   "Email" : "john.smith@company.com"
   "ExternalId": "1234",
   "UserType": "ViewOnly",
   "Enabled": true
   }
]

Minimum XML User body to create a single user

<ArrayOfUser>
  <User>
    <Name>John Smith</Name>
    <Initials>JS</Initials>
    <Email>john.smith@company.com</Email>
    <ExternalId>1234</ExternalId>
    <UserType>ViewOnly</UserType>
    <Enabled>true</Enabled>
  </User>
</ArrayOfUser>

Omitting Properties

See corresponding section under 'Task API'.  The User Object Type works identically.

Setting Custom Fields through the API

See corresponding section under 'Task API'.  The User Object Type works identically.

User Address Properties

See corresponding section under 'Task API'.  The User Object Type works identically.

Diff Updates using the Last Updated Field

See corresponding section under 'Task API'.  The User Object Type works identically.