The Records API gives you access to the data records that have been collected or imported into your Fulcrum account.

Filtering Between Dates

Using the before and since filters, you can retrieve records between a date range.

For instance, you can combine the client_created_since and client_created_before parameters to find the records that were created by your field crew between two dates.

When using the various created and updated time parameters, you must give the date since epoch in seconds: 2012-04-24 15:05:22 -0400 = 1335294322.

Records will still be ordered according to the updated_at column, even when filtering with the other before/since parameters.

Optional Headers

These headers work for create, update, and delete actions.

Note: These headers only work with the records API. Batch API calls will always use the configurations as set in the webhooks and workflows interface.

Properties

Form Value Field Types

Validations

The following properties must be included in order to create/update a record object in our system. Any validation errors will return a 422 and an object with a list of validation errors.

Required Properties

Example validation response if the form_id is not included:

{
  "record": {
    "errors": {
      "form_id": ["cannot be blank"]
    }
  }
}

Using the geometry field

Users have the option to send in a geometry field with their API call to set the location of a record. In return, the record’s latitude and longitude will be updated to reflect this new geometry value. Needs to be valid a GeoJSON. We accept Point, LineString, Polygon, MultiLineString, and MultiPolygon geometry types. When setting the coordinates of your geometry, remember that longitude is written before latitude. Here is an example of a Record JSON object with valid Point geometry:

{
  "form_id": "123",
  "form_values": {
    "6tgy": "My record",
    "765n": "876"
  },
  "geometry": {
  "type": "Point",
    "coordinates": [
      125.6,     // longitude
      10.1       // latitude
    ]
  }
}

If Fulcrum receives a Point geometry, the record’s latitude & longitude will be updated to reflect that new point.

If Fulcrum receives a LineString geometry, the record’s latitude & longitude will be updated to reflect the line’s midpoint.

If Fulcrum receives a Polygon geometry, the record’s latitude & longitude will be updated to reflect the polygon’s centroid.

If a user would prefer to set latitude and longitude themselves in addition to the geometry, they can send all three values: geometry, latitude, and longitude. Fulcrum will set all values it receives in this case.

Using latitude and longitude

Users can still forgo geometry and update a record’s location via the latitude and longitude attributes. If Fulcrum receives record JSON that contains ONLY latitude and longitude, it will set the record’s latitude and longitude as well as update the geometry to a Point reflecting the new coordinates.

Warning:
Providing two options to update a record’s location means that latitude and longitude are no longer required, nor is geometry. However, Fulcrum strongly recommends sending in complete location information when you want to create a record or make changes to an existing one. For example, if you only want to update a record’s latitude property, you should still send in a latitude and longitude pair or a GeoJSON geometry value which contains both coordinates.

If you do not wish to update a record’s location, there is no need to send in any location information - existing values will not change.

Notes

• The Records API does not enforce any validation against your custom form fields.

• The entire record object is required when making an update. Omitting fields with existing data will result in data loss! The typical workflow for updating an existing record is to fetch the record object, modify it, and then submit the PUT request.

• A repeatable's updated_at is only updated from device, similar to the client_updated_at in the parent record. A repeatable cannot have a server updated at different than its parent because they save/sync at the same time.

• If an assigned_to user does not exist in the organization, the record will be created with no assignee.

• If the project does not exist in the organization, the record will be created with no project.

Sample Response

{
  "record": {
    "status": "Red",
    "version": 1,
    "id": "4e1c33ad-5496-4818-826f-504e66239b4d",
    "created_at": "2015-05-30T15:47:19Z",
    "updated_at": "2015-05-30T15:47:19Z",
    "client_created_at": "2015-05-30T14:47:13Z",
    "client_updated_at": "2015-05-30T14:47:58Z",
    "created_by": "Bryan McBride",
    "created_by_id": "50633f84a934480d260001db",
    "updated_by": "Bryan McBride",
    "updated_by_id": "50633f84a934480d260001db",
    "form_id": "7a0c3378-b63a-4707-b459-df499698f23c",
    "project_id": null,
    "assigned_to": null,
    "assigned_to_id": null,
    "form_values": {
      "8373": {
        "choice_values": ["Pillar"],
        "other_values": []
      },
      "2832": "183",
      "57c9": "4",
      "193f": [{
        "photo_id": "da1f58f5-f31d-452f-81fc-233f94bcf48a",
        "caption": null
      }],
      "11f8": {
        "choice_values": ["Green Space"],
        "other_values": []
      }
    },
    "latitude": 42.8208336,
    "longitude": -73.8936123,
    "altitude": 98.0,
    "speed": null,
    "course": 170.0,
    "horizontal_accuracy": 3.9,
    "vertical_accuracy": null
  }
}