FotoNotes API Documentation

 

Confidential – Please do not distribute – FotoNotes 2021

Overview

This document describes the Application Programming Interface (API) for the FotoNotes application, which is a REST style API that uses the JSON format. The first section below describes the FotoNotes data model; the second section provides general information about making API calls; the third section provides details on the particular types of requests that are available.

FotoNotes Data Model

For the purposes of API users, the FotoNotes data model can be described as follows:

  •     The key objects are users and projects
  •     Projects contain sections, which are groups of customer-defined fields that may have attached media
  •     Different levels of access can be granted to users on each project

Projects

Each project is identified by the unique identifier project_id, which is an alphanumeric value generated by the FotoNotes system.

Projects have the following properties:

Property Description Value Nullable?
project_id the unique identifier an alphanumeric value No
status the project status e.g. “NEW”, “COMPLETE” (template contains allowed values) Yes
latitude the latitude of the project location a decimal value, e.g. 41.839682 Yes
longitude the longitude of the project location a decimal value, e.g. -71.388375 Yes
date_created the timestamp of when the project was created e.g. 2010-03-01T16:46:51Z No
priority the priority of the project one of: “none”, “low”, “medium”, “high”, “critical” No
due_date the due date of the project e.g. “2014-10-11” No

 

A project may contain other projects (for example, a property that contains work orders). These are identified by the property “contained_items”. Similarly, if one project is contained within another, that will be indicated by the element “container_id”.

Projects also include sections, which are collections of fields. A section is identified by:

Property Description Value Nullable?
key the unique identifier for the section an alphanumeric value No

 

Each section is a collection of customer-defined fields, which have the following properties:

Property Description Value Nullable?
key the unique identifier for the field an alphanumeric value No
value the value that has been assigned to the field an alphanumeric value Yes
comment explanatory text that provides more information about the field a string up to 255 characters in length Yes
text a block of text used for special-purpose fields like Agreement and Barcode a string up to 10,000 characters in length Yes
conditionally_hidden a boolean value that specifies whether this field is currently hidden by conditional logic true or false Yes
last_updated the timestamp of when the field was last updated e.g. 2010-03-01T15:31:23Z Yes

 

A field can also contain any number of media, which are photos taken in the mobile app or uploaded through the web portal.
Media have the following properties:

Property Description Value Nullable?
id the unique identifier of the media an alphanumeric value No
date_created the timestamp of when the media was created e.g. 2010-03-01T16:46:51Z No
date_captured the timestamp of when the media was captured by the mobile app e.g. 2010-03-01T15:31:23Z Yes
caption the caption associated with the media a string up to 255 characters in length, e.g. “roof damage” Yes
latitude the latitude of the location where the media was captured a decimal value, e.g. 39.34964 Yes
longitude the longitude of the location where the media was captured a decimal value, e.g. -120.2547 Yes

 

If your portal has the “Advanced photo meta-data” feature turned on, the following properties are also included:

Property Description Value Nullable?
height the height of the media in pixels an integer No
width the width of the media in pixels an integer No
azimuth the azimuth of the media a decimal value Yes
elevation_angle the elevation angle of the media a decimal value Yes
altitude the altitude of the location where the media was captured a decimal value Yes

 

Users

Users are represented by the unique identifier user_id, which is an alphanumeric value generated by the FotoNotes system.

Users have the following properties:

Property Description Value Nullable?
id the user’s unique identifier in FotoNotes an alphanumeric value No
external_id the user’s unique identifier in the external (customer) system an alphanumeric value Yes
username the user’s unique identifier for logging in to FotoNotes an alphanumeric value No
email the user’s email an email address No
role the user’s role in FotoNotes one of: “USER”, “ADMIN” No
enabled whether the user can log in true or false No

 

Access

Each user can be assigned a certain level of access to each project.

Level Description
none The user does not have access to the project. This is the default level of access when not otherwise specified.
read The user can view project information but can not edit it.
write he user can edit any project fields except those that have been designated “is_admin_only”.
admin The user can edit any project fields including those designated as “admin only”. The user can also delete the project, or change the access levels to the project for other users.

General API Information

Base URL

All API endpoints referred to in this documentation use the placeholder: <base-url>
This placeholder should be replaced with the current production version of the FotoNotes API URL, which is: api.fotonotes.com

Protocol

All calls to the FotoNotes API are made using the HTTPS protocol, using either GET or POST. In general, the GET method is used to retrieve data, while the POST method is used to create or update data.

Format

Requests to the FotoNotes API should be made using the JSON format. Responses from the server will also be in this format.

Request

Authentication

The FotoNotes API uses Basic Authentication to authenticate each incoming request. Every request to the FotoNotes API must include an Authorization header containing standard Basic Authentication credentials. For more on Basic Authentication, see  http://www.w3.org/Protocols/HTTP/1.0/draft-ietf-http-spec.html#BasicAA.

API_KEY Header

In addition to the “Authorization” header required for Basic Authentication, each request must also include a header with the name “API_KEY”. The value of this header will be provided to the customer by Fotobabble.

Response

All successful calls to the FotoNotes API will return an HTTP status code of “200”. Whether or not there is anything returned in the body of the response depends on the method being called. For example, methods to set a user’s access on a project or update project data do not return any text in the body. Methods that create or retrieve data will return responses in JSON format, as described in the details below.

When an API call results in an error, one of the following status codes will be returned:

  • 400 The request can not be completed due to bad syntax.
  • 401 The user is not authorized due to bad credentials or an incorrect API key.
  • 403 The user does not have permission to make this request.
    (For example, the user does not have write access to a project.)
  • 404 The request refers to a resource that can not be found.
    (For example, a non-existent project.)
  • 500 The request can not be completed due to a server error.
    (Please contact support if this error persists.)

When errors are encountered, they will be returned in JSON format in the body of the response. For example:

    
{
  "errors": [
    "Value of field with key [property_type] is not a valid option: [none] ",
    "Value of field with key [list_price] is not a valid money value: [67.8] ",
    "Value of field with key [inspection_date] is not a valid date: [20121344] ",
    "Value of field with key [days_on_market] exceeds [255] characters",
    "Comment on field with key [days_on_market] exceeds [255] characters"
  ]
}      
  

API Methods

Project Methods

Creating A Project

A new project can be created by passing in the key of a project template that already exists in FotoNotes. The response will contain the ID of the newly created project. An optional container_id parameter can also be included, indicating the containing project underneath which the new project should be created. The most common use of this parameter is when a work order or inspection is being created underneath a property.

Note: When a project is created underneath a container, fields in the new project that have the same type and key as the containing project will inherit the values of the containing project’s fields. For example, if the container project is a property with fields that include “address”, “city”, and “state”, the corresponding fields in the new project will inherit these values from the container.

URL https://<base-url>/customer_api/1_0/project
HTTP Method POST
BODY template_key, optional container_id
RESPONSE 200 OK Body contains the full representation of the project.

 

Property Description Required?
template_key the unique identifier of a project template that already exists in FotoNotes Yes
container_id the ID of a container project that already exists in FotoNotes No

 

Example for creating a new project from the template identified by standard_template.

REQUEST: POST https://<base-url>/customer_api/1_0/project
 	 
 {	 
  "template_key": "standard_template"	 
 }	 
 

RESPONSE: 200 OK
	 
 {	 
  "id": "123"	 
 }	 
 

Retrieving A Project By ID

All data for a project can be retrieved by issuing a GET command with the project’s unique identifier.

URL https://<base-url>/customer_api/2_0/project/<project_id>
HTTP Method GET
BODY NONE
RESPONSE 200 OK    Body contains the full representation of the project.

Note: All user ids in the JSON response are external (customer-defined) ids.
Please ensure that all users have external ids specified.
The external id can be used to retrieve the user details using the Retrieving a Single User method below.

Example for retrieving data for the project with id “123”:

REQUEST: GET https://<base-url>/customer_api/2_0/project/123
RESPONSE: 200 OK
 
{
  "id": "85312",
  "display_line1": "API Test Project",
  "display_line2": "25 Laurel Ave.",
  "display_line3": "Providence, RI 02906",
  "display_line4": null,
  "status": "IN_PROGRESS",
  "creator": "sida",
  "assigned_user": "jdoenice",
  "assigned_user_id": "1234",
  "assigned_company_key": null,
  "assigned_manager_external_id": "manager-123",
  "assigned_customer_external_id": "customer-456",
  "priority": "high",
  "date_created": "2019-07-23T15:10:05-07:00",
  "due_date": "2019-10-01",
  "last_updated": "2019-09-02T10:01:42-07:00",
  "status_last_updated": "2019-09-02T10:00:37-07:00",
  "latitude": 40.7083159,
  "longitude": -74.36293979999999,
  "type": "Work Order",
  "template_id": 481,
  "template_key": "service-line-item",
  "container_id": null,
  "archived": false,
  "contained_items": [],
  "documents": [],
  "tags": [
        "plumbing",
        "leak"
    ],
  "fields": [
    {
      "key": "address",
      "value": "25 Laurel Ave.",
      "display_value": "25 Laurel Ave.",
      "name": "Street Address",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": []
    },
    {
      "key": "city_state_zip",
      "value": "Providence, RI 02906",
      "display_value": "Providence, RI 02906",
      "name": "City, State, Zip",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": []
    },
    {
      "key": "customer_name",
      "value": null,
      "display_value": null,
      "name": "Customer Name",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": []
    },
    {
      "key": "customer_phone_number",
      "value": null,
      "display_value": null,
      "name": "Customer Phone Number",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": []
    },
    {
      "key": "project_id",
      "value": null,
      "display_value": null,
      "name": "Project Id",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": []
    },
    {
      "key": "project_name",
      "value": "API Test Project",
      "display_value": "API Test Project",
      "name": "Project name",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": []
    },
    {
      "key": "property_photo",
      "value": null,
      "display_value": null,
      "name": "Property photo",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": [
        {
          "id": 5124,
          "date_created": "2019-08-22T16:36:12Z",
          "date_captured": "2014-01-17T12:31:45Z",
          "caption": "Here is a caption",
          "latitude": 37.7,
          "longitude": -122.44,
          "height": 542,
          "width": 600,
          "azimuth": null,
          "elevation_angle": null,
          "altitude": null,
          "make": null,
          "model": null
        },
        {
          "id": 5125,
          "date_created": "2019-08-22T16:40:33Z",
          "date_captured": "2014-01-17T12:31:45Z",
          "caption": "This is from the customer",
          "latitude": 37.7,
          "longitude": -122.44,
          "height": 338,
          "width": 600,
          "azimuth": null,
          "elevation_angle": null,
          "altitude": null,
          "make": null,
          "model": null
        }
      ]
    },
    {
      "key": "total_estimated_cost",
      "value": "1400.00",
      "display_value": "$1400.00",
      "name": "Total Estimated Cost",
      "comment": null,
      "text": null,
      "conditionally_hidden": false,
      "last_updated": "2019-10-14T19:59:40Z",
      "media": []
    }
  ],
  "field_groups": [
    {
      "name": "Line Items",
      "fields": [
        {
          "key": "description",
          "value": null,
          "display_value": null,
          "name": "Description",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190730094732392-2484",
          "media": []
        },
        {
          "key": "photos",
          "value": null,
          "display_value": null,
          "name": "Photos",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190730094732392-2484",
          "media": [
            {
              "id": 5094,
              "date_created": "2019-07-30T16:48:33Z",
              "date_captured": null,
              "caption": null,
              "latitude": null,
              "longitude": null,
              "height": 333,
              "width": 333,
              "azimuth": null,
              "elevation_angle": null,
              "altitude": null,
              "make": null,
              "model": null
            },
            {
              "id": 5095,
              "date_created": "2019-07-30T16:48:35Z",
              "date_captured": null,
              "caption": null,
              "latitude": null,
              "longitude": null,
              "height": 333,
              "width": 333,
              "azimuth": null,
              "elevation_angle": null,
              "altitude": null,
              "make": null,
              "model": null
            }
          ]
        },
        {
          "key": "room",
          "value": "Kitchen",
          "display_value": "Kitchen",
          "name": "Room",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190730094732392-2484",
          "media": []
        },
        {
          "key": "service",
          "value": "carpet",
          "display_value": "Carpet",
          "name": "Service",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190730094732392-2484",
          "media": []
        },
        {
          "key": "service_cost",
          "value": "390.00",
          "display_value": "$390.00",
          "name": "Estimated Cost",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190730094732392-2484",
          "media": []
        },
        {
          "key": "units",
          "value": "3",
          "display_value": "3",
          "name": "Service Units",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190730094732392-2484",
          "media": []
        },
        {
          "key": "description",
          "value": "Updated via API",
          "display_value": "Updated via API",
          "name": "Description",
          "comment": "Testing 2",
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190813083653260-2484",
          "media": []
        },
        {
          "key": "photos",
          "value": null,
          "display_value": null,
          "name": "Photos",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190813083653260-2484",
          "media": []
        },
        {
          "key": "room",
          "value": "Basement",
          "display_value": "Basement",
          "name": "Room",
          "comment": "Basement Comment",
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190813083653260-2484",
          "media": [
            {
              "id": 5129,
              "date_created": "2019-08-22T18:17:22Z",
              "date_captured": "2014-01-17T12:31:45Z",
              "caption": "Good test",
              "latitude": 37.7,
              "longitude": -122.44,
              "height": 338,
              "width": 600,
              "azimuth": null,
              "elevation_angle": null,
              "altitude": null,
              "make": null,
              "model": null
            },
            {
              "id": 5126,
              "date_created": "2019-08-22T17:34:59Z",
              "date_captured": "2014-01-17T12:31:45Z",
              "caption": "Another attempt",
              "latitude": 37.7,
              "longitude": -122.44,
              "height": 338,
              "width": 600,
              "azimuth": null,
              "elevation_angle": null,
              "altitude": null,
              "make": null,
              "model": null
            },
            {
              "id": 5127,
              "date_created": "2019-08-22T18:15:17Z",
              "date_captured": "2014-01-17T12:31:45Z",
              "caption": "Good test",
              "latitude": 37.7,
              "longitude": -122.44,
              "height": 338,
              "width": 600,
              "azimuth": null,
              "elevation_angle": null,
              "altitude": null,
              "make": null,
              "model": null
            }
          ]
        },
        {
          "key": "service",
          "value": "paint",
          "display_value": "Paint",
          "name": "Service",
          "comment": "Paint Comment",
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190813083653260-2484",
          "media": []
        },
        {
          "key": "service_cost",
          "value": "1010.00",
          "display_value": "$1010.00",
          "name": "Estimated Cost",
          "comment": null,
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190813083653260-2484",
          "media": []
        },
        {
          "key": "units",
          "value": "91",
          "display_value": "91",
          "name": "Service Units",
          "comment": "Comment with 91",
          "text": null,
          "conditionally_hidden": false,
          "group_entry_uuid": "85312-4-20190813083653260-2484",
          "media": []
        }
      ]
    }
  ]
}
    

Retrieving Selected Projects

The following method can be used to retrieve all projects with a given status value that have been updated within a given time range.

URL https://<baseurl>/customer_api/2_0/projects
HTTP Method GET
BODY  NONE
RESPONSE 200 OK    Body contains a list of projects, represented as in the previous method.
URL parameters status    Body contains the full representation of the project.(Optional)
last_updated_after and last_updated_before timestamps use the yyyyMMddHHmmss format and Coordinated Universal Time (UTC). For example: 20121030123046. The two parameters may be used together, individually, or not at all.(Optional)
max The maximum number of results to returned.  Used in combination with offset to allow paging through results.(Optional)
offset The start number for the result set from the first value (Optional)
type The Type of the projects to be retrieved. This should be the type name (URL encoded) (Optional)
search  The text string to search on.  This searches the display fields (Optional)
exact_text true or false, indicates whether the text search should be an exact match (Optional, default is false)
summary_only true or false. If true, only summary data is returned for each project (Optional, default is false)
is_archived true or false. If true, only archived projects are returned (Optional, default is false)
container_id The ID of the containing project (usually a Property) (Optional)
client_id The ID of the organization that owns the project, if different from that of the API user (Optional)

Example for retrieving all projects that have a COMPLETE status and were last updated between October 30, 2012 at 10:00:00 UTC and October 31, 2012 at 10:00:00 UTC

REQUEST: GET https://<base-url>/customer_api/1_0/projects?status=COMPLETE&last_updated_after=20121030100000&last_updated_before=20121031100000
RESPONSE: 200 OK

Example for retrieving all projects that have a COMPLETE status and are of type Rehab

REQUEST: GET https://<base-url>/customer_api/1_0/projects?status=COMPLETE&type=Rehab
RESPONSE: 200 OK

NOTES:

All three URL parameters are optional, but by defaults the number of results returned is restricted to 100, so it is recommended that callers choose query criteria that do not produce large result sets. In particular, it should be possible to restrict the size of the time range so that a small number of results are returned.

In the call to retrieve multiple projects, the offset parameter can be specified in combination with the max parameter to page through results. The offset is the start number for the result set from the first value.

For example, to retrieve the first 20 results use an “offset=0” and “max=20”. To retrieve the second 20 results use an “offset=20” and “max=20”

projects?last_updated_after=20150730204744&last_updated_before=20150730204944&max=20&offset=0</code >

projects?last_updated_after=20150730204744&max=20&offset=20

Retrieving A Project Report

A PDF report for a project can be retrieved by issuing a GET command with the project ID.

URL https://<base-url>/customer_api/1_0/project/report/<project_id>
HTTP Method GET
BODY NONE
RESPONSE 200 OK Body contains the report stream.
URL Parameters role – Set to the role that report should be generated for. Values can be CUSTOMER, WORKER or ADMIN. Optional
timestampedPhotos – Set to true to have the capture timestamp on the photos. Optional
flaggedPhotos – Set to true to only include flagged photos in report. Optional
report_view – FotoNotes support can provide options for your account. Optional

Example: Retrieving a report for the project with ID “123”.

REQUEST: GET https://<base-url>/customer_api/1_0/project/report/123
RESPONSE: 200 OK

Updating a Project

This method can be used for updating both project-level and customer-defined fields.

URL https://<base-url>/customer_api/2_0/project/<project_id>
HTTP Method POST
BODY Properties to be set on the project, including a parameter named “fields”, which is a list of customer-defined field elements.

 

Project properties:

Property Description Required?
status the new value for the project status No
latitude the new value for the project latitude No
longitude the new value for the project longitude No
priority the new value for the project priority No
due_date the new value for the project due date No
market_key the new value for the project market No
tags a list of tags to be added to the project No
container_id the FotoNotes ID of the “container” project to which this project should be added No
fields a list of updates to customer-defined fields No

 

Properties within fields:

Property Description Required?
key the unique identifier of the customer-defined field Yes
group_entry_uuid the unique identifier of the particular item in a field group Required for dynamically added items (items in field groups)
value the new value to be assigned to the field No
comment the comment associated with the field No

 

Example: Setting properties and customer-defined fields on a project with ID “123”.

Note that the first two entries in the “fields” array are standard fields, while the third is a dynamic item and thus
requires the use of the “group_entry_uuid” parameter.

REQUEST POST https://<base-url>/customer_api/2_0/project/123

{
  "status": "IN_PROGRESS",
  "latitude": 137.68,
  "longitude": -38.75,
  "priority": "medium",
  "due_date": "2014-10-11",
  "tags": ["plumbing", "leak"],
  "fields": [
    {
      "key": "address",
      "value": "25 Laurel Ave.",
      "comment": "Top floor of duplex"
    },
    {
      "key": "city",
      "value": "Providence"
    },
    {
      "key": "service",
      "value": "paint",
      "group_entry_uuid": "85312-4-20190813083653260-2484"
    }
  ]
}
       
RESPONSE: 200 OK

Archiving a Project

A project can be archived by issuing a POST command with the project ID.

URL https://<base-url>/customer_api/1_0/project/archive/<project_id>
HTTP Method POST
BODY  NONE
RESPONSE 200 OK

Example: Archiving a project with ID “456”

REQUEST: GET https://<base-url>/customer_api/1_0/project/archive/456
RESPONSE: 200 OK

Un-archiving a Project

A project can be un-archived by issuing a POST command with the project ID.

URL https://<base-url>/customer_api/1_0/project/unarchive/<project_id>
HTTP Method POST
BODY  NONE
RESPONSE 200 OK

Example: Un-archiving a project with ID “456”

REQUEST: GET https://<base-url>/customer_api/1_0/project/unarchive/456
RESPONSE: 200 OK

Retrieving Project Activity

A list of project activity entries can be retrieved by passing the project ID.

URL https://<base-url>/customer_api/2_0/project/log/<project_id>
HTTP Method GET
BODY empty
RESPONSE 200 OK Body contains list of project activities

Example: Retrieving activities for the project with ID 490161

REQUEST GET https://<base-url>/customer_api/2_0/project/log/490161
RESPONSE 200 OK

[
  {
    "date": "2021-03-09T18:54:53Z",
    "username": "janedoe",
    "project_id": 490161,
    "activity": "project_add_document",
    "message": "Site_Assessment.docx",
    "latitude": null,
    "longitude": null,
    "timestamp": null
  },
  {
    "date": "2021-03-09T18:55:15Z",
    "username": "janedoe",
    "project_id": 490161,
    "activity": "project_assign",
    "message": "msmith",
    "latitude": null,
    "longitude": null,
    "timestamp": null
  },
  {
    "date": "2021-03-09T18:55:17Z",
    "username": "janedoe",
    "project_id": 490161,
    "activity": "project_change_status",
    "message": "IN_PROGRESS",
    "latitude": null,
    "longitude": null,
    "timestamp": null
  },
  {
    "date": "2021-03-09T18:55:20Z",
    "username": "janedoe",
    "project_id": 490161,
    "activity": "project_change_status",
    "message": "COMPLETE",
    "latitude": null,
    "longitude": null,
    "timestamp": null
  },
  {
    "date": "2021-03-09T19:54:21Z",
    "username": "dana",
    "project_id": 490161,
    "activity": "project_archive",
    "message": "",
    "latitude": null,
    "longitude": null,
    "timestamp": null
  }
]
      

Copying a Project

Create a copy of an existing project, using a different template (by specifying a template key), or the same template (by default).
All data is copied to the new project; media is only copied if the “copy_media” parameter is set to true.

URL https://<base-url>/customer_api/2_0/project/copy/<project_id>
HTTP Method POST
BODY See parameters below.
RESPONSE 200 OK Body contains the full representation of the project.

 

Copy parameters:

Property Description Required?
template_key the key of the template to be used to create the new project, if different from that of the source project No
copy_media true or false. The default is false. No

 

Example: Copying a project with ID “123” to a new project using the template whose key is “other_template_key”, and copying the media also.

REQUEST POST https://<base-url>/customer_api/2_0/project/copy/123

{
  "template_key": "other_template_key",
  "copy_media": true
}
    
RESPONSE: 200 OK

Adding Tags to a Project

This method can be used to add a set of tags to a project.

URL https://<base-url>/customer_api/2_0/project/add_tags/<project_id>
HTTP Method POST
BODY tags
RESPONSE 200 OK

 

Property Description Required?
tags a list of tags Yes

 

Example for adding tags “inspection” and “northwest”

REQUEST: POST https://<base-url>/customer_api/2_0/project/add_tags/999
   
{
  "tags": ["inspection", "northwest"]
}
RESPONSE: 200 OK

Removing Tags from a Project

This method can be used to remove a set of tags from a project.

URL https://<base-url>/customer_api/2_0/project/remove_tags/<project_id>
HTTP Method POST
BODY tags
RESPONSE 200 OK

 

Property Description Required?
tags a list of tags Yes

 

Example for removing tags “gutter” and “roof”

REQUEST: POST https://<base-url>/customer_api/2_0/project/remove_tags/999
   
{
  "tags": ["gutter", "roof"]
}
RESPONSE: 200 OK

Dynamic Item Methods

Adding a New Item to a Field Group

This method is used to create a new item in a field group. The unique identifier of the field group is appended to the URL as the parameter “field_group_key”. The new item may contain multiple fields, where each field is identified by its unique key.

URL https://<base-url>/customer_api/2_0/project/add_group_item/<project_id>?field_group_key=<field_group_key>
HTTP Method POST
BODY A list of maps, one for each field in the new item, where each map contains the properties below.
RESPONSE 200 OK    Body contains a complete list of fields in the newly added item.
URL parameters field_group_key The unique identifier of the field_group where the item will be added.

 

Properties of each field in the new item:

valuethe value to be assigned to this field in the new itemNo

Property Description Required?
key the unique identifier of the field within the group Yes
comment the comment associated with the field No

 

Example: Adding a new item with 3 fields into the field group “line_items” on a project with ID “123”.

REQUEST POST https://<base-url>/customer_api/2_0/project/add_group_item/123?field_group_key=line_items

[
  {
    "key": "room",
    "value": "Kitchen",
    "comment": "room comment"
  },
  {
    "key": "service",
    "value": "paint",
    "comment": "service comment"
  },
  {
    "key": "units",
    "value": "5"
  }
]
  
RESPONSE: 200 OK

[
  {
    "key": "description",
    "value": null,
    "display_value": null,
    "name": "Description",
    "comment": null,
    "text": null,
    "conditionally_hidden": false,
    "group_entry_uuid": "85312-4-20190902104814061-2484",
    "media": []
  },
  {
    "key": "photos",
    "value": null,
    "display_value": null,
    "name": "Photos",
    "comment": null,
    "text": null,
    "conditionally_hidden": false,
    "group_entry_uuid": "85312-4-20190902104814061-2484",
    "media": []
  },
  {
    "key": "room",
    "value": "Kitchen",
    "display_value": "Kitchen",
    "name": "Room",
    "comment": "room comment",
    "text": null,
    "conditionally_hidden": false,
    "group_entry_uuid": "85312-4-20190902104814061-2484",
    "media": []
  },
  {
    "key": "service",
    "value": "paint",
    "display_value": "Paint",
    "name": "Service",
    "comment": "service comment",
    "text": null,
    "conditionally_hidden": false,
    "group_entry_uuid": "85312-4-20190902104814061-2484",
    "media": []
  },
  {
    "key": "service_cost",
    "value": "150.00",
    "display_value": "$150.00",
    "name": "Estimated Cost",
    "comment": null,
    "text": null,
    "conditionally_hidden": false,
    "group_entry_uuid": "85312-4-20190902104814061-2484",
    "media": []
  },
  {
    "key": "units",
    "value": "5",
    "display_value": "5",
    "name": "Service Units",
    "comment": "units comment",
    "text": null,
    "conditionally_hidden": false,
    "group_entry_uuid": "85312-4-20190902104814061-2484",
    "media": []
  }
]
  

Deleting an Item from a Field Group

This method is used to delete an item from a field group. The unique identifier of the item is appended to the URL as the parameter “group_entry_uuid”.

URL https://<base-url>/customer_api/2_0/project/delete_group_item/<project_id>?group_entry_uuid=<group_entry_uuid>
HTTP Method POST
BODY empty
RESPONSE 200 OK  empty body
URL parameters group_entry_uuid The unique identifier of the item to be deleted.

Example: Deleting an item with unique identifier “85312-4-20190902104814061-2484” from a project with ID “123”.

REQUEST POST https://<base-url>/customer_api/2_0/project/delete_group_item/123?group_entry_uuid=85312-4-20190902104814061-2484
RESPONSE: 200 OK

Media Methods

Retrieving an Image

Images associated with a project can be retrieved by issuing a GET command with the unique identifier of the media, as provided in the field metadata described above.

URL https://<base-url>/customer_api/1_0/media/image/<media_id>
HTTP Method GET
BODY  NONE
RESPONSE 200 OK    Body contains the image stream.
URL Parameters timestamp Set to true to have timestamps on photos. Optional.

Example: Retrieving an image for the media with id “987”

REQUEST: GET https://<base-url>/customer_api/1_0/media/image/987
RESPONSE: 200 OK

Adding an Image to a Project Field

This method can be used to add an image and accompanying metadata to a project field.

URL https://<base-url>/customer_api/2_0/project/add_media/<project_id>
HTTP  Method POST
BODY  multipart/form-data containing the parameters below
RESPONSE 200 OK
FORM parameters image is the binary representation of the image (required)
field_key is the unique identifier of the field (required)
group_entry_uuid is the unique identifier of an item in a field group  (required for dynamic items)
caption is the text caption for the image
capture_date is the timestamp when the image was captured.
It should use the yyyyMMddHHmmss format and Coordinated Universal Time (UTC). For example: 20121030123046
latitude is the latitude of the gps coordinates of the image location
longitude is the latitude of the gps coordinates of the image location

 

Retrieving a Zip File of Project Images

A zip file containing images for a project can be retrieved by issuing a GET command with the project ID.

URL https://<base-url>/customer_api/1_0/project/images/<project_id>
HTTP Method GET
BODY NONE
RESPONSE 200 OK Body contains the the zip file as a stream.
URL Parameters timestampedPhotos – Set to true to have the capture timestamp on the photos. Optional
originals – Set to true to only include original photos (high res) in the zip. Optional
folders – Set to true to have the photo organized into folders. Optional
dataFile – Set to true to include a csv containing project data in the zip. Optional

Example: Retrieving a zip file of images for the project with ID “123”.

REQUEST: GET https://<base-url>/customer_api/1_0/project/images/123
RESPONSE: 200 OK

Adding a Document to a Project

This method can be used to add a document to a project.

URL https://<base-url>/customer_api/2_0/project/add_document/<project_id>
HTTP Method POST
BODY  multipart/form-data containing the parameters below
RESPONSE 200 OK
FORM parameters document is the binary representation of the document file (required)
name is the name that will be used to identify the document in the FotoNotes application  (required)
owner is the username of the FotoNotes user who should own the document (optional)
hide_from_field_user is a boolean flag indicating whether the document should be hidden (optional)

If the “owner” parameter is not included, the document will be owned by the user under which the API call is being made.

The “hide_from_field_user” parameter should be set to “true” if the document should be hidden — any other value (or not including the parameter) is equivalent to passing “false”.

Project Access Methods

Retrieving Project Access

The method below allows the caller to retrieve the set of users who have access to a given project, and each user’s level of access. Note that retrieving access levels on a project requires that the user making the API call is an admin user or has “admin” access to the given project.

URL https://<base-url>/customer_api/1_0/projectaccess/<PROJECT_ID>
HTTP Method GET
BODY NONE
RESPONSE 200 OK Body contains user attributes (id, external_id, username, real_name) and access level (read, write, or admin).

Example: Retrieving the users with access to the project with id “123”.

REQUEST GET https://<base-url>/customer_api/1_0/projectaccess/123
RESPONSE 200 OK
    
[
  {
    "id": 2490,
    "external_id": "user_19",
    "username": "jdoe",
    "real_name": "John Doe",
    "access": "read"
  },
  {
    "id": 2489,
    "external_id": "user_23",
    "username": "ssmith",
    "real_name": "Sam Smith",
    "access": "write"
  },
  {
    "id": 2553,
    "external_id": "user_87",
    "username": "mjones",
    "real_name": "Mary Jones",
    "access": "admin"
  }
]
        

Updating Project Access

Access to a particular project can be set by passing in its unique identifier, the user’s identifier, and the access level that is being granted to that user. The new level of access will overwrite any previous access that had been granted. Note that setting or updating access levels on a project requires that the user making the API call is an admin user or has “admin” access to the given project.

URL https://<base-url>/customer_api/1_0/projectaccess
HTTP Method POST
BODY The project_id, user_id, and access level.
Property Description Required?
project_id the unique identifier for the project Yes
user_id the unique identifier for the user (either the FotoNotes id or the customer’s external id) Yes
access the level of access being granted (read, write, admin, or none) Yes

 

RESPONSE 200 OK empty body

Example: Granting write access on the project with id “123” to the user with id “789”

REQUEST: POST https://<base-url>/customer_api/1_0/projectaccess
   
{
  "project_id": "123",
  "user_id": "789",
  "access": "write"
}
       
RESPONSE: 200 OK

Assigning a User or Vendor to a Project

The methods above allow full control over granting users particular levels of access to a project.
FotoNotes also provides methods to support a common use case, in which there is a single “assigned” user or vendor company for each project. (Assignment to vendors is only available to FotoNotes customers who have the “Vendor Management” feature.) The assignee is displayed in the FotoNotes UI, and is automatically granted “write” access to the project.

Assignment through the API is done by passing a project ID and the unique identifier of the user or vendor being assigned.

An optional boolean parameter can be used to indicate whether or not the previous assignee (if there was one)
should have their access removed from the project. By default, the previous assignee’s access will be removed.

An optional boolean parameter can be used to indicate whether an email notification should be sent to the new assignee. By default, an email is sent.

URL https://<base-url>/customer_api/1_0/project/assign
HTTP Method POST
BODY The project_id and either a user_id or company_id (for assignment to a vendor company), an optional parameter remove_previous_assignee_access, which is true by default, and an optional parameter notify_user, also true by default.
Property Description Required?
project_id the unique identifier for the project Yes
user_id the unique identifier for the user (either the FotoNotes id or the customer’s external id) No
company_id the unique identifier for the vendor company (the vendor key) No
remove_previous_assignee_access true or false. The default is true. No
notify_user true or false. The default is true. No

NOTE: Either the user_id or the company_id parameter must be present.

RESPONSE 200 OK empty body

Example: Assigning the project with id “123” to the user with id “789”

REQUEST POST https://<base-url>/customer_api/1_0/project/assign
   
{
  "project_id": "123",
  "user_id": "789"
}
   
RESPONSE: 200 OK

Un-Assigning a User or Vendor from a Project

If one user or vendor is assigned to a project, assigning a different user or vendor will automatically un-assign the current assignee. There is also a case where the goal may be to un-assign the current assignee without making a new assignment.
This can be done with the unassign API method, whose only required parameter is the project ID.
The optional remove_previous_assignee_access parameter specifies whether or not to also remove
access to the project for the user or vendor who is being unassigned. By default, all access is removed when un-assignment occurs.

URL https://<base-url>/customer_api/1_0/project/unassign
HTTP Method POST
BODY The project_id, and an optional remove_previous_assignee_access, which is true by default.
Property Description Required?
project_id the unique identifier for the project Yes
remove_previous_assignee_access true or false. The default is true. No

 

RESPONSE 200 OK empty body

Example: Un-assigning the current assignee from the project with id “123”.

This example shows the use of the optional parameter, which allows the user to retain access to the project, even though they are no longer the assignee.

REQUEST POST https://<base-url>/customer_api/1_0/project/unassign
   
{
  "project_id": "123",
  "remove_previous_assignee_access": false
}
 
RESPONSE: 200 OK

Assigning a Manager to a Project

In addition to assigning a user through the API, it is possible to assign a manager. This is done by passing a project ID and the unique identifier of the user to be assigned as manager.

URL https://<base-url>/customer_api/1_0/project/assign_manager
HTTP Method POST
BODY The project_id and the user_id.
Property Description Required?
project_id the unique identifier for the project Yes
user_id the unique identifier for the user (either the FotoNotes id or the customer’s external id) No
RESPONSE 200 OK empty body

Example: Assigningthe user with id “789” as the manager to the project with id “123”

REQUEST POST https://<base-url>/customer_api/1_0/project/assign_manager
  
{
  "project_id": "123",
  "user_id": "789"
}
 
RESPONSE: 200 OK

Un-Assigning a Manager from a Project

If a user is assigned as a manager on a project, assigning a different user will automatically un-assign the current assignee. There is also a case where the goal may be to un-assign the current assignee without making a new assignment.
This can be done with the unassign_manager API method, whose only required parameter is the project ID.

URL https://<base-url>/customer_api/1_0/project/unassign_manager
HTTP Method POST
BODY The project_id.
Property Description Required?
project_id the unique identifier for the project Yes

 

RESPONSE 200 OK empty body

Example: Un-assigning the current manager for the project with id “123”.

REQUEST POST https://<base-url>/customer_api/1_0/project/unassign_manager
   
{
  "project_id": "123"
}
 
RESPONSE: 200 OK

User Methods

Creating a User

A new user can be created by passing in all required parameters. If the call is successful, the user’s parameters are returned, including the FotoNotes ID.

URL https://<base-url>/customer_api/1_0/user
HTTP Method POST
BODY The parameters of the user to be created.

 

Property Description Required?
external_id the unique identifier for the user No
username the username (login) for the user Yes
real_name the user’s full name Yes
email the user’s email address Yes
password the user’s password Yes
is_admin true if the user should be created as an administrative user No

 

Example: Creating a new user with external ID “999”.

REQUEST POST https://<base-url>/customer_api/1_0/user
   
{
  "external_id": "999",
  "username": "jdoe",
  "real_name": "John Doe",
  "email": "jdoe@example.com",
  "password": "temppass"
}
 
RESPONSE: 200 OK
   
{
  "id": 2488,
  "external_id": "999",
  "username": "jdoe",
  "real_name": "John Doe",
  "email": "jdoe@example.com",
  "is_admin": "false",
  "enabled": "true"
}

Updating a User

An existing FotoNotes user can be updated by passing either the external id or the FotoNotes user ID in the URL, and the new user parameters in the json body. Note that the FotoNotes username can not be updated.

URL https://<base-url>/customer_api/1_0/user/<USER_ID>
HTTP Method POST
BODY The parameters of the user to be updated.

 

Property Description Required?
external_id the unique customer identifier for the user No
real_name the user’s full name No
email the user’s email address No
password the user’s password No
is_admin true if the user should be made an administrative user No
enabled false to disable a user (prevent login) No

 

Example: Updating a user with FotoNotes ID “123”.

REQUEST POST https://<base-url>/customer_api/1_0/user/123
   
{
  "external_id": "999",
  "username": "jdoe",
  "real_name": "John Doe",
  "email": "jdoe@example.com",
  "password": "temppass"
}
 
RESPONSE: 200 OK
   
{
  "id": 123,
  "external_id": "999",
  "username": "jdoe",
  "real_name": "John Doe",
  "email": "jdoe@example.com",
  "is_admin": "false",
  "enabled": "true"
}

Retrieving Users

Users can be retrieved by role and/or “enabled” status.

URL https://<base-url>/customer_api/1_0/users
HTTP Method GET
BODY empty
RESPONSE 200 OK Body contains list of user descriptions.
URL parameters role Only users with the specified role, one of: portal_admin, user, field_user, customer, manager, basic_admin. (Optional)
enabled true or false. Limit to enabled or non-enabled users. (Optional)
tag Only users with the specified tag. (Optional)

Example: Retrieving all enabled field users

REQUEST GET https://<base-url>/customer_api/1_0/users?role=field_user&enabled=true
RESPONSE 200 OK
   
[
   {
     "id": 2488,
     "external_id": "999",
     "username": "jdoe",
     "real_name": "John Doe",
     "email": "jdoe@example.com",
     "is_admin": "false",
     "role": "field_user",
     "enabled": "true"
}
    {
        "id": "58631",
        "external_id": "ssmith",
        "username": "sarah_smith",
        "real_name": "Sarah Smith",
        "email": "sarah@example.com",
        "is_admin": "false",
        "role": "field_user",
        "enabled": true
    }
]  

Retrieving a User

A user can be retrieved by passing in either the external id or the FotoNotes user ID.

URL https://<base-url>/customer_api/1_0/user/<USER_ID>
HTTP Method GET
BODY empty
RESPONSE 200 OK Body contains user description.

Example: Retrieving a user with external ID “999”

REQUEST GET https://<base-url>/customer_api/1_0/user/999
RESPONSE 200 OK
   
{
  "id": 2488,
  "external_id": "999",
  "username": "jdoe",
  "real_name": "John Doe",
  "email": "jdoe@example.com",
  "is_admin": "false",
  "enabled": "true"
}
  

Deleting a User

A user can be deleted by passing in either the external id or the FotoNotes user ID.

URL https://<base-url>/customer_api/1_0/user/delete/<USER_ID>
HTTP Method POST
BODY empty
RESPONSE 200 OK Body contains user description.

Example: Deleting a user with external ID “999”

REQUEST GET https://<base-url>/customer_api/1_0/user/delete/999
RESPONSE 200 OK empty body

Service Methods

Creating a Service

A new service can be created by passing in all required parameters. If the call is successful, the service’s parameters are returned.

URL https://<base-url>/customer_api/3_0/add_service
HTTP Method POST
BODY The parameters of the service to be created.

 

Property Description Required?
name the name of the service Yes
service_key the unique key for the service – must be unique Yes
unit the unit for the service, e.g. “inches” Yes
unit_cost the full cost for the service, per unit No
unit_labor_cost the labor cost for the service, per unit No
unit_material_cost the material cost for the service, per unit No
can_set_cost whether costs can be overridden by a user (true or false) No
can_set_quantity whether the quantity can be overridden by a user (true or false) No
default_quantity the default quantity for the service (integer) No
description the description for the service No
category the category for the service No
market the market for the service No

 

Example: Creating a new Service with service_key “exterior_painting”

REQUEST POST https://<base-url>/customer_api/3_0/add_service

{
  "name": "Exterior Painting",
  "service_key": "exterior_painting",
  "unit": "square feet",
  "unit_cost": 5,
  "unit_labor_cost": 4,
  "unit_material_cost": 1,
  "can_set_cost": false,
  "can_set_quantity": true,
  "description": "Description for exterior painting",
  "category": "paint",
  "market": "WA"
}
  
RESPONSE: 200 OK

{
  "name": "Exterior Painting",
  "service_key": "exterior_painting",
  "unit": "square feet",
  "unit_cost": 5,
  "unit_labor_cost": 4,
  "unit_material_cost": 1,
  "can_set_cost": false,
  "can_set_quantity": true,
  "default_quantity": null,
  "description": "Description for exterior painting",
  "category": "paint",
  "market": "WA"
}

Updating a Service

An existing FotoNotes service can be updated by passing the service_key in the URL, and the new service parameters in the json body.

URL https://<base-url>/customer_api/3_0/update_service/<SERVICE_KEY>
HTTP Method POST
BODY The parameters of the service to be updated. The same as for creating a service, but the service_key is included in the URL only.

 

Example: Updating some attributes of a service with service_key “exterior_painting”

REQUEST POST https://<base-url>/customer_api/3_0/update_service/exterior_painting
 
{
  "name": "Exterior Paint",
  "unit_cost": 7,
  "description": "A new description"
}
 
RESPONSE: 200 OK

{
  "name": "Exterior Paint",
  "service_key": "exterior_painting",
  "unit": "square feet",
  "unit_cost": 7,
  "unit_labor_cost": 4,
  "unit_material_cost": 1,
  "can_set_cost": false,
  "can_set_quantity": true,
  "default_quantity": null,
  "description": "A new description",
  "category": "paint",
  "market": "WA"
}

Deleting a Service

A service can be deleted by passing in the service_key

URL https://<base-url>/customer_api/3_0/delete_service/<SERVICE_KEY>
HTTP Method POST
BODY empty
RESPONSE 200 OK Body contains service description.

Example: Deleting a service with service_key “exterior_paint”

REQUEST POST https://<base-url>/customer_api/3_0/delete_service/exterior_paint
RESPONSE 200 OK

Retrieving a Service

A service can be retrieved by passing the service_key in the URL.

URL https://<base-url>/customer_api/3_0/service/<SERVICE_KEY>
HTTP Method GET
BODY empty
RESPONSE 200 OK Body contains service description.

Example: Retrieving a service with service_key “exterior_paint”

REQUEST GET https://<base-url>/customer_api/3_0/service/exterior_paint
RESPONSE 200 OK

{
  "name": "Exterior Paint",
  "service_key": "exterior_painting",
  "unit": "square feet",
  "unit_cost": 7,
  "unit_labor_cost": 4,
  "unit_material_cost": 1,
  "can_set_cost": false,
  "can_set_quantity": true,
  "default_quantity": null,
  "description": "A new description",
  "category": "paint",
  "market": "WA"
}
    

Retrieving Services

A list of services can be retrieved by passing the search parameters described below.

URL https://<base-url>/customer_api/3_0/services
HTTP Method GET
BODY empty
RESPONSE 200 OK Body contains list of services
Optional URL parameters search – text to search for
sort – the attribute to sort by
order – the sort order: either asc or desc
max – the maximum number of services to return
offset – the offset to start from; used with max to page through results

Example: Retrieving services with search string “paint”

REQUEST GET https://<base-url>/customer_api/3_0/services?search=paint&max=2&offset=0&sort=service_key&order=asc
RESPONSE 200 OK

[
  {
    "name": "Exterior Paint",
    "service_key": "exterior_painting",
    "unit": "square feet",
    "unit_cost": 6,
    "unit_labor_cost": 4.5,
    "unit_material_cost": 1.5,
    "can_set_cost": false,
    "can_set_quantity": true,
    "default_quantity": null,
    "description": "Description for exterior painting.",
    "category": "paint",
    "market": "WA"
  },
  {
    "name": "Interior Paint",
    "service_key": "interior_painting",
    "unit": "square yards",
    "unit_cost": 10,
    "unit_labor_cost": 7,
    "unit_material_cost": 3,
    "can_set_cost": true,
    "can_set_quantity": true,
    "default_quantity": null,
    "description": "Description for interior painting.",
    "category": "paint",
    "market": "WA"
  }
]
      

 

Vendor Methods

Retrieving a Vendor

A vendor can be retrieved by passing the vendor’s key in the URL.

URL https://<base-url>/customer_api/2_0/vendor/<VENDOR_KEY>
HTTP Method GET
BODY empty
RESPONSE 200 OK Body contains the vendor description.

Example: Retrieving a vendor with key “acme”

REQUEST GET https://<base-url>/customer_api/2_0/vendor/acme
RESPONSE 200 OK

{
  "name": "Acme Inc.",
  "address": "897 Jefferson Street",
  "city": "Mableton",
  "state": "GA",
  "zip": "30126",
  "contact_name": "Bob Deer",
  "contact_email": "bdeer@email.com",
  "contact_email2": null,
  "latitude": null,
  "longitude": null,
  "contact_phone": "555-555-5555",
  "contact_phone2": null,
  "key": "acme",
  "status": "ACTIVE",
  "connected": false,
  "distance": 0,
  "category": "general",
  "areas": [
    "GA",
    "SC",
    "FL"
  ],
  "service_notes": null,
  "general_notes": null,
  "insurance_valid_date": "2021-03-31",
  "documents_on_file": false,
  "rating": 3
}

      

 

Deprecated Methods

Retrieving A Project By ID

All data for a project can be retrieved by issuing a GET command with the project’s unique identifier.

URL https://<base-url>/customer_api/1_0/project/<project_id>
HTTP Method GET
BODY NONE
RESPONSE 200 OK    Body contains the full representation of the project.

Example for retrieving data for the project with id “123”:

REQUEST: GET https://<base-url>/customer_api/1_0/project/123
RESPONSE: 200 OK
   
{
  "id": "123",
  "date_created": "2012-07-24T16:03:51Z",
  "last_updated": "2012-07-24T16:03:51Z",
  "status": "NEW",
  "latitude": 137.68,
  "longitude": -38.75,
  "priority": "medium",
  "due_date": "2014-10-11",
  "sections": [
    {
      "key": "summary_information",
      "fields": [
        {
          "key": "address_line1",
          "value": "25 Laurel Ave."
        },
        {
          "key": "city",
          "value": "Springfield"
        },
        {
          "key": "state",
          "value": "MA"
        }
      ]
    },
    {
      "key": "adverse_factors",
      "fields": [
        {
          "key": "water_damage",
          "value": "minor",
          "comment": "There is some of mildew on the interior walls"
        },
        {
          "key": "traffic",
          "value": "heavy",
          "comment": "The street is a major thoroughfare",
          "media": [
            {
              "id": 83474,
              "date_created": "2018-05-25T16:38:43Z",
              "date_captured": "2018-05-25T11:07:21Z",
              "caption": null,
              "latitude": 39.34958,
              "longitude": -120.2545
            },
            {
              "id": 83475,
              "date_created": "2018-05-25T16:38:45Z",
              "date_captured": null,
              "caption": "view from the north",
              "latitude": null,
              "longitude": null
            }
          ]
        }
      ]
    }
  ]
}
  
  

Retrieving Projects By Status and Last-Update Timestamp

The following method can be used to retrieve all projects with a given status value that have been updated within a given time range.

URL https://<base-url>/customer_api/1_0/projects?status=<STATUS_VALUE>&last_updated_after=<TIME_RANGE_
START>&last_updated_before=<TIME_RANGE_END>
HTTP Method GET
BODY  NONE
RESPONSE 200 OK    Body contains the full representation of the project.
URL parameters status    Body contains the full representation of the project.
last_updated_after and last_updated_before timestamps use the yyyyMMddHHmmss format and Coordinated Universal Time (UTC). For example: 20121030123046. The two parameters may be used together, individually, or not at all.
max the maximum number of results to returned.  Used in combination with offset to allow paging through results.
offset is the start number for the result set from the first value
type is the Type of the projects to be retrieved. This should be the type name (URL encoded)

Updating a Project

This method can be used for updating both project-level and customer-defined fields.

URL https://<base-url>/customer_api/1_0/project/<project_id>
HTTP Method POST
BODY Properties to be set on the project, including a parameter named “fields”, which is a list of customer-defined field elements.

 

Project properties:

Property Description Required?
status the new value for the project status No
latitude the new value for the project latitude No
longitude the new value for the project longitude No
priority the new value for the project priority No
due_date the new value for the project due date No
container_id the FotoNotes ID of the “container” project to which this project should be added No
fields a list of updates to customer-defined fields No

 

Properties within fields:

Property Description Required?
key the unique identifier of the customer-defined field Yes
value the new value to be assigned to the field No
comment the comment associated with the field No

 

Example: Setting properties and customer-defined fields on a project with ID “123”.

REQUEST POST https://<base-url>/customer_api/1_0/project_fields/123

       {   
         "status": "IN_PROGRESS",
         "latitude": 137.68,
         "longitude": -38.75,
         "priority": "medium",
         "due_date": "2014-10-11",
         "fields": [
         {"key":"address",
         "value": "25 Laurel Ave."},
         {"key":"city",
         "value": "Springfield"},
         {"key":"state",
         "value": "MA"},
         {"key":"zip",
         "value": "02318"}
         ]
       }
     
RESPONSE: 200 OK