Contacts API

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

Contacts in Field Squared are written to the API as either a single contact or a list of contact objects. For most integrations we recommend doing batch updates of contacts (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.

Contact Object Payload

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

{
        "ExternalId": "7a6a8fa2-b3d0-4c47-aae3-c5ee3de3b6a8",
        "ContactName": "John Smith",
        "Company": "Smith Enterprises",
        "MobilePhone": "303 555 5555",
        "WorkPhone" : "303 111 1111",
        "HomePhone" : "303 222 2222",
        "Email": "john@fieldsquared.com",
        "Lat":39.749911,
        "Lon":-105.000026,
        "StreetAddress": "1514 Blake St",
        "Unit": "Suite 200",
        "City": "Denver",
        "State": "CO",
        "Zip": "80202-1322",
        "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"
        },
        "Team": "jTZv6YcMaStulDcIMOrs4AAA4A",
        "Tasks": [
            "-14vBsBhR5GDMj-xS_ZAicDSDA"
        ],
        "LastUpdated": "2017-01-30T18:43:22Z",
        "Created": "2017-01-30T18:43:22Z" 
}

Working with Single Contacts

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

Methods Supported: GET|POST|DELETE
URL: https://api.fieldsquared.com/workspace/api/contact/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/contact/1234
will retrieve the contact 1234 from workspace 10. The structure of the Contact returned will look like the payload above.

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

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

Working with Lists of Contacts

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/contact

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 Contact 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 Contact Class.

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

[
  {
    "ContactName": "John Smith",
    "ExternalId": "1234",
  },
  {
    "ContactName": "Mary Brown",
    "ExternalId": "1235",
 }
]

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

Example 1
GET https://api.fieldsquared.com/10/api/contact
This retrieves an array of contact 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/contact
This example can bulk create or update contacts 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 Contact Object Type works identically.

Updating Records using the ExternalID

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

Contact API Properties

Core Properties

The core properties of a contact are:

• Name (required) – the name of the contact
• 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.
• ContactName (optional) – Full name for contact.
• Company (optional) – Company Name for contact
• MobilePhone (optional) – Mobile (Cell) Phone for contact
• WorkPhone (optional) – Work Phone for contact
• HomePhone (optional) – Home Phone for contact
• Email (optional) – Email address for contact (used for sending documents and notifications to contact)
• Enabled (required) – true/false boolean to indicate if the contact is enabled.
• Tasks (optional) – List of ExternalID's of related tasks.
• Team (optional) – ExternalID of team that the contact is assigned to.  Teams control the visibility of the contact to users of the system.  i.e. A contact may be tagged with a Team that is responsible for a specific geographic region.  Only Field Squared users that are part of that team will see that contact within the Field Squared mobile app.

Minimum JSON body to create a single contact

[
 {
   "ContactName": "John Smith",
   "ExternalId": "1234",
   "Enabled": true
   }
]

Minimum XML Contact body to create a single contact

<ArrayOfContact>
  <Contact>
    <ContactName>John Smith</ContactName>
    <ExternalId>1234</ExternalId>
    <Enabled>true</Enabled>
  </Contact>
</ArrayOfContact>

Omitting Properties

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

Setting Custom Fields through the API

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

Contact Address Properties

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

Diff Updates using the Last Updated Field

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