SiteCapture API Documentation

Overview

SiteCapture Data Model
- Projects
- Users
- Access

General API Information

API Methods

Confidential – Please do not distribute – SiteCapture 2021

Overview

This document describes the Application Programming Interface (API) for the SiteCapture application, which is a REST style API that uses the JSON format. The first section below describes the SiteCapture 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.

SiteCapture Data Model

For the purposes of API users, the SiteCapture 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 SiteCapture 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 SiteCapture system.

Users have the following properties:

Property	Description	Value	Nullable?
`id`	the user’s unique identifier in SiteCapture	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 SiteCapture	an alphanumeric value	No
`email`	the user’s email	an email address	No
`role`	the user’s role in SiteCapture	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 SiteCapture API URL, which is: api.sitecapture.com

Protocol

All calls to the SiteCapture 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 SiteCapture API should be made using the JSON format. Responses from the server will also be in this format.

Request

Authentication

The SiteCapture API uses Basic Authentication to authenticate each incoming request. Every request to the SiteCapture 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 SiteCapture 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 SiteCapture. 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 SiteCapture	Yes
`container_id`	the ID of a container project that already exists in SiteCapture	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 Project Fields

A subset of specific field data for a project can be retrieved by issuing a GET command with the project’s unique identifier and a comma-separated list of keys for the desired fields.

URL	`https://<base-url>/customer_api/2_0/project/fields/<project_id>`
HTTP Method	`GET`
BODY	`NONE`
RESPONSE	`200 OK` Body contains selected data from the project.
URL parameters	`field_keys` A comma-separated list of field keys (Optional) `include_project_summary` true or false. If true, project-level data is also returned (Optional, default is false) `include_media`true or false. If true, image metadata is returned for each specified field (Optional, default is false)

Example for retrieving data for the project with id “123” on two specific fields:

REQUEST:	`GET https://<base-url>/customer_api/2_0/project/fields/123?field_keys=name,address`
RESPONSE:	`200 OK`

 
{
    "id": "123",
    "fields": [
        {
            "key": "name",
            "section_key": "summary",
            "value": "John Doe",
            "display_value": "John Doe",
            "name": "Full Name",
            "comment": null,
            "text": null,
            "conditionally_hidden": false,
            "last_updated": "2022-05-28T17:54:40Z",
            "last_updated_by": "doe@test.com"
        },
        {
            "key": "address",
            "section_key": "summary",
            "value": "24 Elm Street",
            "display_value": "24 Elm Street",
            "name": "Street Address",
            "comment": null,
            "text": null,
            "conditionally_hidden": false,
            "last_updated": "2022-05-28T17:54:40Z",
            "last_updated_by": "admin@test.com"
        }
    ]
}

Retrieving Selected Projects

The following method can be used to retrieve full data for a set of projects that are determined by a combination of criteria including status, last-update time, template, type, etc.

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` The status value to filter on (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 default 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 Fields for Selected Projects

The following method can be used to retrieve a subset of specific field data for a set of projects that are determined by a combination of criteria including status, last-update time, template, etc.

URL	`https://<base-url>/customer_api/2_0/projects/fields`
HTTP Method	`GET`
BODY	`NONE`
RESPONSE	`200 OK` Body contains selected data from the project.
URL parameters	The parameters include any of those specified in the following two methods which are detailed above: Retrieving Project Fields Retrieving Selected Projects

Example for retrieving two specific fields from 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/2_0/project/fields?status=COMPLETE&last_updated_after=20121030100000&last_updated_before=20121031100000&field_keys=name,address`
RESPONSE:	`200 OK`

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_key` – Displayed in Report UI, or available from SiteCapture support. 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 SiteCapture 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 SiteCapture application (required) `owner` is the username of the SiteCapture 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 SiteCapture 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.
SiteCapture 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 SiteCapture customers who have the “Vendor Management” feature.) The assignee is displayed in the SiteCapture 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 SiteCapture 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 SiteCapture 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 SiteCapture 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 SiteCapture user can be updated by passing either the external id or the SiteCapture user ID in the URL, and the new user parameters in the json body. Note that the SiteCapture 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 SiteCapture 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 SiteCapture 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 SiteCapture 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 SiteCapture 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 SiteCapture 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`

SiteCapture API Documentation

Confidential – Please do not distribute – SiteCapture 2021

Overview

SiteCapture Data Model

Projects

Users

Access

General API Information

Base URL

Protocol

Format

Request

Authentication

API_KEY Header

Response

API Methods

Project Methods

Creating A Project

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

Retrieving A Project By ID

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

Retrieving Project Fields

Example for retrieving data for the project with id “123” on two specific fields:

Retrieving Selected Projects

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

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

Retrieving Fields for Selected Projects

Example for retrieving two specific fields from 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

Retrieving A Project Report

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

Updating a Project

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

Archiving a Project

Example: Archiving a project with ID “456”

Un-archiving a Project

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

Retrieving Project Activity

Example: Retrieving activities for the project with ID 490161

Copying a Project

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.

Adding Tags to a Project

Example for adding tags “inspection” and “northwest”

Removing Tags from a Project

Example for removing tags “gutter” and “roof”

Dynamic Item Methods

Adding a New Item to a Field Group

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

Deleting an Item from a Field Group

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

Media Methods

Retrieving an Image

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

Adding an Image to a Project Field

Retrieving a Zip File of Project Images

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

Adding a Document to a Project

Project Access Methods

Retrieving Project Access

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

Updating Project Access

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

Assigning a User or Vendor to a Project

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

Un-Assigning a User or Vendor from a Project

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

Assigning a Manager to a Project

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

Un-Assigning a Manager from a Project

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

User Methods

Creating a User

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

Updating a User

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

Retrieving Users

Example: Retrieving all enabled field users

Retrieving a User

Example: Retrieving a user with external ID “999”

Deleting a User

Example: Deleting a user with external ID “999”

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