Records API

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.

Properties

PropertyTypeRequiredReadonlyDescription
form_idstringyesyesThe form ID
latitudenumberyesnoThe record latitude in WGS 84 decimal degrees.
longitudenumberyesnoThe record longitude in WGS 84 decimal degrees.
form_valuesobjectyesnoMust be present and an object. The keys of this object must reflect the keys in the form schema. Different form types require different values (see table below).
statusstringnonoSets the color of the marker.
versionnumbernoyesAutoincremented version of the record for history tracking.
idstringnoyesThe id of the record.
created_atstringnoyesTimestamp when the record was synced to the cloud.
updated_atstringnoyesTimestamp when the record was last synced to or processed while in the cloud.
client_created_atstringnonoTimestamp when the user first created the record.
client_updated_atstringnonoTimestamp when the record was last modified by the user.
created_bystringnoyesThe name of user who created the record.
created_by_idstringnoyesThe id of user who created the record.
updated_bystringnoyesThe name of user who last updated the record.
updated_by_idstringnoyesThe id of user who last updated the record.
changeset_idstringnonoThe id of the changeset associated with the record.
project_idstringnonoThe id of the project tagged to the record.
assigned_tostringnoyesThe name of the user the record is assigned to.
assigned_to_idstringnonoThe id of the user the record is assigned to (user_id).
created_durationnumbernonoThe number of seconds spent creating the record.
updated_durationnumbernonoThe number of seconds spent updating the record.
edited_durationnumbernonoThe total cumulative seconds spent editing the record (creating + all updates).
created_locationobjectnonoThe location of where the record was created from. It has 4 number attributes: latitude, longitude, altitude, horizontal_accuracy
updated_locationobjectnonoThe location of where the record was updated from. It has 4 number attributes: latitude, longitude, altitude, horizontal_accuracy
altitudenumbernoyesMeters above/below (+/-) sea level.
speednumbernoyesMeters per second.
coursenumbernoyesOnly recorded if the device is moving and has no relation to how the device is oriented; course is in degrees (0.0-360); if no course can be determined then 0.0 will be returned.
horizontal_accuracynumbernoyesAccuracy of the latitude and longitude in meters.
vertical_accuracynumbernoyesAccuracy of the altitude value in meters.

Form Value Field Types

FieldTypeExample
Textstring"Hello world!"
Numericstring"50"
Yes/Nostring"yes"
Datestring"2015-12-31"
Timestring"13:50"
Barcodestring"123456789"
Hyperlinkstring"https://www.fulcrumapp.com"
Calculationstring"6"
Single Choiceobject with the following keys: choice_values (array of selected options) other values (array, empty or with values){"choice_values": ["Red"],"other_values": []}
Multiple Choiceobject with the following keys: choice_values (array of selected options) other values (array, empty or with values){"choice_values": ["Red","White"],"other_values": []}
Classificationobject with the following keys: choice_values (array of selected options) other values (array, empty or with values){"choice_values": ["Ford","Mustang"],"other_values": []}
Addressaddress object{"sub_thoroughfare": "360","thoroughfare": "Central Ave","suite": "","locality": "St. Petersburg","sub_admin_area": "","admin_area": "FL","postal_code": "33701","country": "United States"}
Photoarray of photo objects[{"photo_id":"a8d1df96-44e5-75e9-7312-7e2c5e902496,"caption": ""}]
Videoarray of video objects[{"video_id":"712850b4-4de2-4d66-a6cc-034201245b52,"caption": ""}]
Audioarray of audio objects[{"audio_id":"f81d51b5-1ce9-465b-be0b-27f1eca41e2c,"caption": ""}]
Signaturesignature object{"timestamp": "2015-07-09T14:54:04Z","signature_id": "9855e3f2-85a5-4b9f-9e62-0b1bbcfef091"}
Record Linkarray of record objects[{"record_id": "988b963c-896c-4f50-be7b-5b5d151f2ed7"},{"record_id": "8a91ba6c-f99e-47a1-8246-807b4a44b28a"}]
Repeatablearray of repeatable objects[{"id":"d67801a0-adc1-6f60-4b0d-ec3a7191b34b","geometry":{"type":"Point","coordinates":[-73.123456,42.123456]},"form_values": {"0129": "Hello world"}}]

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

PropertyTypeDescriptionExample
form_idstringThe form ID."7a0c3378-b63a-4707-b459-df499698f23c"
latitudenumberThe record latitude in WGS 84 decimal degrees.27.770787
longitudenumberThe record longitude in WGS 84 decimal degrees.-82.638039
form_valuesobjectMust be present and an object. The keys of this object must reflect the keys in the form schema. Different form types require different values (see table above).{"2832": "My string value","8373": {"choice_values": ["My choice value"]}}

Example validation response if the form_id is not included:

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

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.

  • 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
  }
}