Getting Started with Fieldwire

Introduction

Welcome to the Fieldwire API! You can use our API to access your Fieldwire projects.

📘

Current API endpoint: https://console.fieldwire.net/api/v3

Sample Apps

Would you like diving into the code & learning from that? Wonderful! We have 2 sample applications that demonstrate this flow: creating a new project, inviting a user, updating after creating a task & finally uploading a plan to the project

• Ruby
• Java

Entities Hierarchy

The high-level hierarchy of the Fieldwire entities is as follows:

- Account
  - Project
    - User
    - Floorplan
      - Sheet
        - Attachment
        - Hyperlink
        - Markup
    - Task
      - TaskCheckItem
      - Bubble (comments, photos, files)
        - BubbleMarkup
    - Form
      - FormSection
        - FormSectionRecord
          - FormSectionRecordInput
          - FormSectionRecordValue
            - FormSectionRecordInputValue

The relationship between these entities is codified by the children carrying the ID of their immediate parents.

📘

Note

This list isn't comprehensive & is only meant to give a taste of how the entities are organized. There are more entities & even a few entities present here can also take other places in the hierarchy. For example, an Attachment can belong to a Project without being on a Sheet

Authentication

Fieldwire uses API tokens to allow access to the API. You can acquire a new token from your account page.

Fieldwire expects for the API token to be included in all API requests to the server in a header that looks like Authorization: Token api=[api token].

🚧

You must replace [api token] with your API token.

GET /projects HTTP/2
Authorization: Token api=[api token]

Paging

The number of returned items can be controlled by setting Fieldwire-Per-Page header.

After the first response, additional pages can be requested utilizing the returned value of X-Last-Synced-At.

The following is an example of how to retrieve 150 projects using a page size of 100 projects per request.

GET /projects HTTP/1.1
Authorization: Token api=[api token]
Fieldwire-Per-Page: 100

HTTP/1.1 200 OK
Content-Type: application/json
X-Count: 100
X-Has-More: true
X-Last-Synced-At: 2019-01-01T00:00:00.000Z

[
  ...99 projects...,
  {
    "id": "b5c08097-74f1-4a8f-a9a8-52e16295f6a4",
    "name": "Project 100",
    "updated_at": "2019-01-01T00:00:00.000Z",
  }
]

Utilizing the X-Last-Synced-At from the previous call we can make another call to get the next page of 100 items.

GET /projects?last_synced_at=2019-01-01T00:00:00.000Z HTTP/1.1
Authorization: Token api=[api token]
Fieldwire-Per-Page: 100

HTTP/1.1 200 OK
Content-Type: application/json
X-Count: 50
X-Has-More: false
X-Last-Synced-At: 2019-02-01T00:00:00.000Z

[
  ...49 projects...,
  {
    "id": "37b9103e-e3eb-438f-8c38-5f2736a952dd",
    "name": "Project 150",
    "updated_at": "2019-02-01T00:00:00.000Z",
  }
]

Errors

The Fieldwire API uses conventional HTTP status codes to indicate success or failure of an API request.

Additionally, if the request fails validation checks errors are returned in the described format.

URL Overview

A vast majority of the entities are scoped to a project and this is reflected in the URLs. There are some cases where we allow further nesting in the URL to facilitate filtering

# Get a project by ID
curl -X GET '/api/v3/projects/{project_id}'

# Get the attachments in a project
curl -X GET '/api/v3/projects/{project_id}/attachments'

# Create a task in a project
curl -X POST '/api/v3/projects/{project_id}/tasks'

# Update a plan markup
curl -X PATCH '/api/v3/projects/{project_id}/markups/{markup_id}'

# For convenience, in addition to project scoped URLs, 
# further scoping is allowed for easier filtering.
# Example: Get the bubbles (comments, photos) in a task
curl -X GET '/api/v3/projects/{project_id}/tasks/{task_id}/bubbles'