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
Property | Type | Required | Readonly | Description |
---|---|---|---|---|
form_id | string | yes | yes | The form ID |
latitude | number | yes | no | The record latitude in WGS 84 decimal degrees. |
longitude | number | yes | no | The record longitude in WGS 84 decimal degrees. |
form_values | object | yes | no | Must 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). |
status | string | no | no | Sets the color of the marker. |
version | number | no | yes | Autoincremented version of the record for history tracking. |
id | string | no | yes | The id of the record. |
created_at | string | no | yes | Timestamp when the record was synced to the cloud. |
updated_at | string | no | yes | Timestamp when the record was last synced to or processed while in the cloud. |
client_created_at | string | no | no | Timestamp when the user first created the record. |
client_updated_at | string | no | no | Timestamp when the record was last modified by the user. |
created_by | string | no | yes | The name of user who created the record. |
created_by_id | string | no | yes | The id of user who created the record. |
updated_by | string | no | yes | The name of user who last updated the record. |
updated_by_id | string | no | yes | The id of user who last updated the record. |
changeset_id | string | no | no | The id of the changeset associated with the record. |
project_id | string | no | no | The id of the project tagged to the record. |
assigned_to | string | no | yes | The name of the user the record is assigned to. |
assigned_to_id | string | no | no | The id of the user the record is assigned to (user_id ). |
created_duration | number | no | no | The number of seconds spent creating the record. |
updated_duration | number | no | no | The number of seconds spent updating the record. |
edited_duration | number | no | no | The total cumulative seconds spent editing the record (creating + all updates). |
created_location | object | no | no | The location of where the record was created from. It has 4 number attributes: latitude , longitude , altitude , horizontal_accuracy |
updated_location | object | no | no | The location of where the record was updated from. It has 4 number attributes: latitude , longitude , altitude , horizontal_accuracy |
altitude | number | no | yes | Meters above/below (+/-) sea level. |
speed | number | no | yes | Meters per second. |
course | number | no | yes | Only 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_accuracy | number | no | yes | Accuracy of the latitude and longitude in meters. |
vertical_accuracy | number | no | yes | Accuracy of the altitude value in meters. |
Form Value Field Types
Field | Type | Example |
---|---|---|
Text | string | "Hello world!" |
Numeric | string | "50" |
Yes/No | string | "yes" |
Date | string | "2015-12-31" |
Time | string | "13:50" |
Barcode | string | "123456789" |
Hyperlink | string | "https://www.fulcrumapp.com" |
Calculation | string | "6" |
Single Choice | object with the following keys: choice_values (array of selected options) other values (array, empty or with values) | {"choice_values": ["Red"],"other_values": []} |
Multiple Choice | object with the following keys: choice_values (array of selected options) other values (array, empty or with values) | {"choice_values": ["Red","White"],"other_values": []} |
Classification | object with the following keys: choice_values (array of selected options) other values (array, empty or with values) | {"choice_values": ["Ford","Mustang"],"other_values": []} |
Address | address object | {"sub_thoroughfare": "360","thoroughfare": "Central Ave","suite": "","locality": "St. Petersburg","sub_admin_area": "","admin_area": "FL","postal_code": "33701","country": "United States"} |
Photo | array of photo objects | [{"photo_id":"a8d1df96-44e5-75e9-7312-7e2c5e902496,"caption": ""}] |
Video | array of video objects | [{"video_id":"712850b4-4de2-4d66-a6cc-034201245b52,"caption": ""}] |
Audio | array of audio objects | [{"audio_id":"f81d51b5-1ce9-465b-be0b-27f1eca41e2c,"caption": ""}] |
Signature | signature object | {"timestamp": "2015-07-09T14:54:04Z","signature_id": "9855e3f2-85a5-4b9f-9e62-0b1bbcfef091"} |
Record Link | array of record objects | [{"record_id": "988b963c-896c-4f50-be7b-5b5d151f2ed7"},{"record_id": "8a91ba6c-f99e-47a1-8246-807b4a44b28a"}] |
Repeatable | array 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
Property | Type | Description | Example |
---|---|---|---|
form_id | string | The form ID. | "7a0c3378-b63a-4707-b459-df499698f23c" |
latitude | number | The record latitude in WGS 84 decimal degrees. | 27.770787 |
longitude | number | The record longitude in WGS 84 decimal degrees. | -82.638039 |
form_values | object | Must 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
}
}