Skip to main content

/files (GET)

Call the Files with the /files route to get an array of paginated files, based on your search criteria.

Parameters​

reference optional (string)

The used file reference, as a string. This represents the barcode (scan code) value used in the barcode scanner, as well as the value used on the platform.

Example value: reference=76543234567

find optional (string)

Finds the used file based on a partial match of a file reference. For example. Example value: find=765432 Would match 123765432123 for there is a partial match.

closed optional (string)

Finds the used file based on a partial match of a file reference. For example. Example values: closed=1 will return only files that are closed. closed=0 will return only files that are open. Omitting this parameter will return all files, regardless if open or closed.

startdate optional (string)

A date/time field of the file. The API will return the files that were active at the time of the filedate. The date/time format must be ISO-8601 (YYYY-MM-DD hh:mm:ss), and the time zone should be UTC. The time field is optional; we will assume the start of the day in the UTC time zone. Example value: startdate=2023-04-24T11:22:15Z

enddate optional (string)

A date/time field of the file. The API will return the file that was active at the time of the filedate. The date/time format must be ISO-8601 (YYYY-MM-DD hh:mm:ss), and the time zone should be UTC. The time field is optional; we will assume the end of the day in the UTC time zone. Example value: enddate=2023-04-24T11:22:15Z

updated_start optional (string)

A date/time field of the file. The API will return the file that was have been updated after the said date. The date/time format must be ISO-8601 (YYYY-MM-DD hh:mm:ss), and the time zone should be UTC. The time field is optional; we will assume the start of the day in the UTC time zone. Example value: startdate=2023-04-24T11:22:15Z

updated_end optional (string)

A date/time field of the file. The API will return the file that was active at the time of the filedate. If filedate is not supplied and multiple files exist, each instance of the file will be supplied as separate object in the response. Separate instances of the file may be recognised by having a different "file_id" value. The date/time format must be ISO-8601 (YYYY-MM-DD hh:mm:ss), and the time zone should be UTC. The time field is optional; we will assume the end of the day in the UTC time zone. Example value: startdate=2023-04-24T11:22:15Z

Limit optional, default = 50, max = 250 (integer)

Limits the response to a certain number of fields. Note: if there are more records available, the response will be paginated. The response code will contain data about the number of available pages and the “next_page_url” will indicate how to obtain the next set of data.

include[] optional (string)

Possible values:

  • uploads -> includes individual uploads (will increase filesize!)
  • geocoding -> if uploads are included, will include geocoding data
  • forms -> includes submitted forms
  • fields -> includes custom fields
  • locations -> includes information about the location settings of the device(s) used to create the file
  • workflows -> includes information about the workflows that were executed and which items in the file came in which step (as well as showing any skipped steps)

The include switch may be repeated multiple times: for example, if you need uploads and forms in the response, include include[]=uploads&include[]=forms in the get statement. Warning: including these switches will lead to slower response times and higher data traffic. Please only include items you know you will need!

field_id[ id ] optional (integer)

Filter to show only files containing Fields in the Cargosnap platform. The ID of the field can be obtained from the platform, under Global Settings -> Fields -> Select the field. You can now derive the id of the field from the url:

Find the ID of a field

Response values​

The response body of this endpoint is always an ARRAY collected in the 'data' field (even if there is only 1 file in the reponse. Note it may be multiple files, because of the 'find' behaviour of this endpoint). All response values, except Boolean and Integers, are provided as string values and are appropriately escaped. The content of the response will depend on the query parameters, the implemented features on Cargosnap as well as the actual available data. The most common data fields are:

id (int)

Unique ID of the Cargosnap file.

scan_code (string)

String value, of the file number which is queried: your reference code.

scan_code_format (string)

In case a barcode was scanned to provide the file number, this value displays the type of barcode that was scanned.

created_at (date)

Date/timestamp of the time the first Cargosnap or Form was uploaded and registered in the platform, in the time zone UTC.

data.uploads: (array)

  • id: Unique ID of the Cargosnap image/upload.
  • device_id : Unique ID of the Cargosnap device, used to take the image.
  • created_at : Date/timestamp of the time the Cargosnap was uploaded and registered in the platform, in the time zone UTC.
  • scan_date_time: Date/timestamp of the time the Cargosnap was taken on the app, in the time zone UTC.
  • upload_type: String representation of the type of data. Possible values include “snap”, “manual” and “document”.
  • damage_type_desc: Indicates if the Cargosnap app user indicated if any damage is to be seen on the image. The value will be displayed in text, in the language provided in the lang parameter (if available and if supplied).
  • has_damage: Indicates if the Cargosnap app user indicated if any damage is to be seen on the image. Value=1 indicates such a case.
  • document_type_desc: Indicates the selected type of document, in case the user selected to create a document scan.
  • latitude: Latitude of the user, when creating the Cargosnap.
  • longitude: Longitude of the user, when creating the Cargosnap.
  • image_name: Filename of the Snap
  • image_mime: Snap Image type. Typically the image/jpeg
  • comment: If available, provides the comment the Cargosnap app user provided with the Cargosnap.
  • image_url: URL path of the full, uncompressed, original image.
  • image_thumb: URL path of ‘thumbnail’ of the image. The thumbnail contains the full content of the file, but is significantly reduced in filesize, making the presentation to the end-user significantly more responsive on most internet connections.
  • workflow_id: If the image was taken as a part of a workflow, a unique identifyer of the workflow is indicated here.
  • workflow_description: If the image was taken as a part of a workflow, the description -as given in the platform- of the workflow is indicated here.
  • workflow_step_id: If the image was taken as a part of a workflow, a unique identifyer of the specific step in the workflow is indicated here.
  • workflow_step_description: If the image was taken as a part of a workflow, the description of the specific step -as given in the platform- of the workflow is indicated here.

data.form_submits[] (array):

  • id: Unique reference for the data to the submitted form.
  • form.id: Unique number of the specific form that was filled in, at the specific submit
  • form.title: Title of the form, as given
  • fields.label & id: Label of the specific question, for the specific ID
  • answers.value & id: Title of the form, as filled in, for the specific ID

data.fields[] (array):

  • id (note: this field is currently depricated! The value is incorrectly mapped. The functionality of this field will be corrected/changed in a target release on Jan 1st, 2023)
  • field_id: the unique ID given to the field
  • donotuse : well... please do not use this value. it is for temporary use in a internal use case. In the future this value will be transferred to the ID field of the same object
  • name: Field name, as given
  • value: Value, as submitted
  • snap_id: in case the value was 'scanned' from an image, this value may contain the ID of the specific snap the value was scanned from

Example Request​

GET https://api.cargosnap.com/api/v2/files?format=json&token=[MY-API-TOKEN]&limit=10&include[]=uploads&include[]=forms&include[]=fields&field_id[1]=Apple&startdate=2019-01-15&enddate=2019-01-23

This query would:

  • list up to 10 results in JSON format
  • for files created between Jan 15, 2019 and Jan 23rd, 2019
  • Include details of uploads, forms and fields
  • Select the specific fields (tags) where the tag id 1 has the value “Apple”