Field Representation

The following guidelines apply for the values of object fields in the API (see Field Types for the full list of field types supported by JourneyApps).

Type	Format returned in API response	Format accepted for create and update
text	The text in standard JSON. Example: "Nokia"	Any string in standard JSON format. Example: "Nokia"
integer	The number in standard JSON format. Example: 42.	Any integer in standard JSON format. Example: 42.
number	The number in standard JSON format. Example: 3.1428.	Any decimal number in standard JSON format. Example: 3.1428.
date	A date in the format YYYY-MM-DD, as defined by the ISO 8601 specification. Example: "2016-02-27".	Any valid date according to the ISO 8601 specification. Any time or timezone components will be stripped. The YYYY-MM-DD format is recommended. Example: "2016-02-27"
datetime	A date and time in the format YYYY-MM-DDTHH:MM:SSZ, as defined by the ISO 8601 specification. Note that the time is specified in the UTC/GMT timezone. Example: "2016-02-22T14:00:53Z".	Any valid date and time according to the ISO 8601 specification. The YYYY-MM-DDTHH:MM:SSZ format is recommended. Example: "2016-02-22T14:00:53Z".
single-choice	The key and display label of option. Example: {"key": "soccer", "display": "Soccer"}	The string key of the option. Example: "soccer"
single-choice-integer	The key and display label of option. Example: {"key": 3, "display": "Soccer"}	The integer key of the option. Example: 3
boolean	The key and display label of option. Example: {"key": true, "display": "Yes"}	The boolean key of the option. Example: true
multiple-choice	An array of keys and display labels of the selected options. Example: [{"key": "soccer", "display": "Soccer"}, {"key": "tennis", "display": "Tennis"}]	An array of keys, as explained above. Example: ["soccer", "tennis"].
multiple-choice-integer	An array of keys and display labels of the selected options. Example: [{"key": 3, "display": "Soccer"}, {"key": 4, "display": "Tennis"}]	An array of keys, as explained above. Example: [3, 4].
location	Hash with fields latitude, longitude, altitude, horizontal_accuracy, vertical_accuracy and timestamp. Note that altitude and vertical_accuracy are typically not reported by mobile devices, and only latitude and longitude can currently be edited on the JourneyApps Backend data browser. The timestamp is automatically populated when the location is captured. See: Location API Response Example	A hash with fields latitude and longitude (both decimal numbers), and optionally altitude, horizontal_accuracy, vertical_accuracy (all decimal numbers) and timestamp (a date and time in the format YYYY-MM-DDTHH:MM:SSZ, as defined by ISO 8601). Leaving the timestamp blank will cause the current time to be used. If you update an existing GPS location and omit the altitude, horizontal_accuracy or vertical_accuracy fields, any existing values in those fields will be set to null. See: Location API Update Object Example
attachment	A hash with fields state, id and original. The attachment's object id is a separate field, where the key is the attachment's field name plus _id. See: Attachment API Response Example	A hash with fields base64, containing the Base64 representation of the attachment file, and filename, containing the name of the file. See: Attachment API Update Object Example
Photos	A hash with fields state, thumbnail, fullscreen and original. The photo's object id is a separate field, where the key is the photo's field name plus _id. See: Photos API Response Example	A hash with fields base64, containing the Base64 representation of the attachment file, and filename, containing the name of the file. See: Photos and signatures API Update Object Example
Signatures	A hash with fields state, thumbnail, fullscreen, original and svg. The signature's object id is a separate field, where the key is the signature's field name plus _id. See: Signatures API Response Example	A hash with fields base64, containing the Base64 representation of the attachment file, and filename, containing the name of the file. See: Photos and signatures API Update Object Example
Relationships	Relationships use the relationship name plus _id as the key, with the related object id as the value. Only belongs to relationships are included in the object itself, has many relationships should be queried and/or set from the other side of the relationship. Example: building_id: "9913706a-179b-11e2-aaff-0026189d9dc0".	The same format is used for setting relationships. Example: building_id: "9913706a-179b-11e2-aaff-0026189d9dc0".

Examples

Location API Response Example

{
  "latitude": -33.913147447989644,
  "longitude": 18.882385137695337,
  "altitude": null,
  "horizontal_accuracy": null,
  "vertical_accuracy": null,
  "timestamp": "2013-02-22T14:00:53Z"
}

Location API Update Object Example

{
  "latitude": -33.913147447989644,
  "longitude": 18.882385137695337,
  "altitude": 16.43133544921875,
  "horizontal_accuracy": 10.0,
  "vertical_accuracy": 6.0,
  "timestamp": "2014-06-22T13:45:39Z"
}

Attachment API Response Example

"sample_file_id": "ffca93d4-690c-4563-9d38-42c97b51443b",
"sample_file": {
    "state": "uploaded",
    "original": "https://run.journeyapps.com/media/W1siZiI/sample.pdf?sha=ee3b"
}

Attachment API Update Object Example

sample_file: {
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    "filename": "cover-letter.pdf"
}

Note: base64 must not contain any newline characters.

Only the following characters are allowed in filename:

• Lowercase alphanumeric characters

• Under score (_), hyphen (-), period (.) and space ( )

Photos API Response Example

"sample_photo_id": "ffca93d4-690c-4563-9d38-42c97b51443b",
"sample_photo": {
    "state": "uploaded",
    "thumbnail": "https://run.journeyapps.com/media/W1siZd/photo-2021Z.jpg?sha=9b16",
    "fullscreen": "https://run.journeyapps.com/media/W1siZQ/photo-2021Z.jpg?sha=70dc",
    "original": "https://run.journeyapps.com/media/W1siZw/photo-2021Z.jpg?sha=5085"
}

Note: The state field can be uploaded,pending, missing, or untrusted. The thumbnail, fullscreen and original fields are only present if state is uploaded.

Signatures API Response Example

"sample_signature_id": "ffca93d4-690c-4563-9d38-42c97b51443b",
"sample_signature": {
    "state": "uploaded",
    "thumbnail": "https://run.journeyapps.com/media/W1siK0/signature-2021Z.svg?sha=48b3",
    "fullscreen": "https://run.journeyapps.com/media/W1siZiIsI/signature-2021Z.svg?sha=7231",
    "original": "https://run.journeyapps.com/media/W1siZiIsI/signature-2021Z.svg?sha=7231",
    "svg": "https://run.journeyapps.com/media/W1siZQ/signature-2021Z.svg?sha=28f"
}

Note: The state field can be uploaded or pending. The thumbnail, fullscreen, original and svg fields are only present if state is uploaded.

Photos and signatures API Update Object Example

photo: {
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    "filename": "small-red-dot.png"
}

Note: base64 must not contain any newline characters.

Only the following characters are allowed in filename:

• Lowercase alphanumeric characters

• Under score (_), hyphen (-), period (.) and space ( )

Values Not Present

When retrieving objects, a field not present should be interpreted the same as a null value for that field. This applies to all field types, as well as relationships.

When updating an object with Update a Single Object, setting the field to null will clear that field. On the other hand, omitting the field will leave its value unchanged. This applies to all field types, as well as relationships.