Getting Started with Fieldwire

This page will help you get started with Fieldwire. You'll be up and running in a jiffy!

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

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

Request Header

Description

Fieldwire-Per-Page

Number of items returned (default: 50, max: 1000)

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

Response Header

Description

X-Count

Number of entities in response

X-Has-More

Boolean indicating if additional entities exist

X-Last-Synced-At

UTC time indicating exactly how up to date the client is after processing/storing these entities

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'

Updated 15 days ago

Getting Started with Fieldwire


This page will help you get started with Fieldwire. You'll be up and running in a jiffy!

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.