### Common API Endpoints Examples

Source: https://developers.fieldwire.com/docs/index

Examples of common API requests for retrieving and manipulating project data.

```APIDOC
## 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}'
```

### Get the bubbles (comments, photos) in a task
```
curl -X GET '/api/v3/projects/{project_id}/tasks/{task_id}/bubbles'
```
```

--------------------------------

### Fieldwire API cURL Examples

Source: https://developers.fieldwire.com/docs/index

Demonstrates common API operations using cURL, including retrieving projects, attachments, creating tasks, updating markups, and accessing nested resources like bubbles within tasks.

```shell
# 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}'

# Get the bubbles (comments, photos) in a task
curl -X GET '/api/v3/projects/{project_id}/tasks/{task_id}/bubbles'
```

--------------------------------

### API Endpoints Overview

Source: https://developers.fieldwire.com/docs/getting-started

This section provides examples of common API endpoints for interacting with Fieldwire projects, including getting project details, attachments, creating tasks, and updating markups.

```APIDOC
## GET /api/v3/projects/{project_id}

### Description
Retrieves a specific project by its ID.

### Method
GET

### Endpoint
`/api/v3/projects/{project_id}`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

### Request Example
```bash
curl -X GET '/api/v3/projects/{project_id}'
```

## GET /api/v3/projects/{project_id}/attachments

### Description
Retrieves all attachments within a specific project.

### Method
GET

### Endpoint
`/api/v3/projects/{project_id}/attachments`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

### Request Example
```bash
curl -X GET '/api/v3/projects/{project_id}/attachments'
```

## POST /api/v3/projects/{project_id}/tasks

### Description
Creates a new task within a specific project.

### Method
POST

### Endpoint
`/api/v3/projects/{project_id}/tasks`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

#### Request Body
- **task_details** (object) - Required - The details of the task to be created.

### Request Example
```bash
curl -X POST '/api/v3/projects/{project_id}/tasks'
```

## PATCH /api/v3/projects/{project_id}/markups/{markup_id}

### Description
Updates an existing markup for a plan within a project.

### Method
PATCH

### Endpoint
`/api/v3/projects/{project_id}/markups/{markup_id}`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.
- **markup_id** (string) - Required - The unique identifier of the markup.

#### Request Body
- **markup_updates** (object) - Required - The fields to update for the markup.

### Request Example
```bash
curl -X PATCH '/api/v3/projects/{project_id}/markups/{markup_id}'
```

## GET /api/v3/projects/{project_id}/tasks/{task_id}/bubbles

### Description
Retrieves the bubbles (comments, photos, files) associated with a specific task in a project.

### Method
GET

### Endpoint
`/api/v3/projects/{project_id}/tasks/{task_id}/bubbles`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.
- **task_id** (string) - Required - The unique identifier of the task.

### Request Example
```bash
curl -X GET '/api/v3/projects/{project_id}/tasks/{task_id}/bubbles'
```
```

--------------------------------

### Fieldwire API URL Overview Examples

Source: https://developers.fieldwire.com/docs/getting-started

Illustrates common API operations using cURL, including retrieving projects, attachments, creating tasks, updating markups, and accessing nested entities like bubbles within tasks.

```curl
# 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}'

# Example: Get the bubbles (comments, photos) in a task
curl -X GET '/api/v3/projects/{project_id}/tasks/{task_id}/bubbles'
```

--------------------------------

### Authenticated API Call Example

Source: https://developers.fieldwire.com/docs/authentication

This example demonstrates how to make an authenticated API call to fetch project details using a generated access token.

```APIDOC
## GET /api/v3/projects/{project_id}

### Description
Fetches details for a specific project using an authenticated request.

### Method
GET

### Endpoint
https://client-api.us.fieldwire.com/api/v3/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project to retrieve.

#### Headers
- **Fieldwire-Version** (string) - Required - The API version date (e.g., "2023-11-30").
- **authorization** (string) - Required - The JWT access token, prefixed with "Bearer ".
- **accept** (string) - Optional - Specifies the acceptable response format, usually "application/json".

### Request Example
```curl
curl --request GET \
     --url https://client-api.us.fieldwire.com/api/v3/projects/d2e57ef9-5315-4fdb-bc56-8c56983788ce \
     --header 'Fieldwire-Version: 2023-11-30' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <access_token>'
```

### Response
#### Success Response (200)
- **deleted_at** (string | null) - Timestamp of deletion, or null if not deleted.
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.
- **account_id** (integer) - The ID of the associated account.
- **code** (string | null) - Project code, if any.
- **color** (string) - Project color code.
- **id** (string) - The unique ID of the project.
- **name** (string) - The name of the project.
- **plan_name** (string) - The subscription plan name for the project.
- ... (other project fields)

#### Response Example
```json
{
  "deleted_at": null,
  "created_at": "2023-11-08T03:45:19.829Z",
  "updated_at": "2023-11-08T03:45:19.842Z",
  "account_id": 1234,
  "code": null,
  "color": "#F9CD39",
  "id": "d2e57ef9-5315-4fdb-bc56-8c56983788ce",
  "name": "Example project - 1",
  "plan_name": "Enterprise",
  ...
}
```
```

--------------------------------

### Fieldwire API Entity Hierarchy

Source: https://developers.fieldwire.com/docs/index

Illustrates the hierarchical structure of Fieldwire API entities, showing the relationships between Account, Project, User, Floorplan, Task, Form, and their sub-entities. This helps understand how data is organized and related.

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

--------------------------------

### Fieldwire Entities Hierarchy

Source: https://developers.fieldwire.com/docs/index

The high-level hierarchy of Fieldwire entities, showing the parent-child relationships.

```APIDOC
## 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)
    - Form
      - FormSection
        - FormSectionRecord
          - FormSectionRecordInput
          - FormSectionRecordValue
            - FormSectionRecordInputValue
```

The relationship between these entities is codified by the children carrying the ID of their immediate parents. Note that this list isn't comprehensive and is only meant to give a taste of how entities are organized. Some entities can also exist independently or belong to different parts of the hierarchy (e.g., an `Attachment` can belong to a `Project` directly without being on a `Sheet`).
```

--------------------------------

### Fieldwire API Base URLs

Source: https://developers.fieldwire.com/docs/index

The base URL for Fieldwire API endpoints depends on whether you are accessing regionalized project data or non-regionalized account data.

```APIDOC
## Base URL

The Fieldwire API is a group of API endpoints for accessing and interacting with project and account data.

**Account data (non-regionalized):**
`https://client-api.super.fieldwire.com/`

**Project data (regionalized):**
*   **US projects:** `https://client-api.us.fieldwire.com/api/v3`
*   **EU projects:** `https://client-api.eu.fieldwire.com/api/v3`
```

--------------------------------

### Fieldwire API Base URLs

Source: https://developers.fieldwire.com/docs/getting-started

Defines the base URLs for accessing Fieldwire API endpoints. Account data uses a non-regionalized URL, while project data is regionalized based on the project's location (US or EU).

```text
Account data: https://client-api.super.fieldwire.com/
US projects: https://client-api.us.fieldwire.com/api/v3
EU projects: https://client-api.eu.fieldwire.com/api/v3
```

--------------------------------

### Get Single Subscription Response (JSON)

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Example JSON response for a single subscription. It provides detailed information about a specific subscription, including its configuration and status.

```json
{
  "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
  "subscription_name": "Example Webhook Subscription",
  "description": "This is a demo subscription",
  "post_url": "https://Example.com/test",
  "subscription_status": "enabled",
  "account_id": "<account_id>",
  "internal": false,
  "entity_filters": [],
  "project_filters": []
}
```

--------------------------------

### Get All Subscriptions Response (JSON)

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Example JSON response when successfully retrieving all subscriptions. It returns an array of subscription objects, each containing details like ID, name, status, and configuration.

```json
[
  {
    "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
    "subscription_name": "Example Webhook Subscription",
    "description": "This is a demo subscription",
    "post_url": "https://Example.com/test",
    "subscription_status": "enabled",
    "account_id": "<account_id>",
    "internal": false,
    "entity_filters": [],
    "project_filters": []
  }
]
```

--------------------------------

### Fieldwire API Pagination Example

Source: https://developers.fieldwire.com/docs/pagination

Demonstrates how to retrieve paginated data from Fieldwire API endpoints. It shows the structure of HTTP requests and responses, including the use of 'Fieldwire-Per-Page', 'X-Count', 'X-Has-More', and 'X-Last-Synced-At' headers to fetch multiple pages of results. The 'last_synced_at' query parameter is used to specify the starting point for subsequent requests.

```http
GET /projects HTTP/1.1
Authorization: Bearer <access_token>
Fieldwire-Per-Page: 100
Fieldwire-Version: 2023-12-25
```

```http
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",
  }
]
```

```http
GET /projects?last_synced_at=2019-01-01T00:00:00.000Z HTTP/1.1
Authorization: Bearer <access_token>
Fieldwire-Per-Page: 100
Fieldwire-Version: 2023-12-25
```

```http
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",
  }
]
```

--------------------------------

### Example JSON Response for Form Job - Fieldwire API

Source: https://developers.fieldwire.com/docs/getting-form-data

An example of the response received after initiating a full form data job. It contains a 'jid' (job ID) which is crucial for the next step in retrieving the actual form data.

```json
{
  "jid": "221d6504-d50b-408f-ade3-769102920f29"
}
```

--------------------------------

### Example API Filter Query

Source: https://developers.fieldwire.com/docs/filtering

Demonstrates how to filter floorplans by tag and creation date using the Fieldwire API. This involves constructing a URL with query parameters for multiple filters.

```text
/api/v3/projects/<project_id>/floorplans/?filters[tag_eq]=foo&filters[created_at_gt]=2022-01-01
```

--------------------------------

### Create Fieldwire Webhook Subscription using cURL

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Example of how to create a webhook subscription using a cURL command. It demonstrates sending a POST request with JSON payload to the subscriptions endpoint, including authentication headers and required subscription details.

```curl
curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/<Account ID>/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{
    "subscription_name": "Example Webhook Subscription",
    "description": "This is a demo subscription",
    "post_url": "https://Example.com/test",
    "subscription_status": "enabled"
  }'
```

--------------------------------

### Create a new form

Source: https://developers.fieldwire.com/docs/working-with-project-forms

Creates a new form record within a project. This is the first step in creating a form from a template.

```APIDOC
## POST /api/forms

### Description
Creates a new form record in a project. This record serves as the top-level container for a form and is a prerequisite for generating the form from a template.

### Method
POST

### Endpoint
/api/forms

### Parameters
#### Request Body
- **creator_user_id** (integer) - Required - The ID of the user creating the form.
- **last_editor_user_id** (integer) - Required - The ID of the user who last edited the form.
- **owner_user_id** (integer) - Required - The ID of the user who owns the form (form assignee).
- **form_template_id** (string) - Required - The ID of the form template to be used.
- **checksum** (string) - Required - The checksum of the form template.
- **name** (string) - Required - The name of the form.

### Request Example
```json
{
  "creator_user_id": 12345,
  "last_editor_user_id": 12345,
  "owner_user_id": 12345,
  "form_template_id": "tmpl_abc123",
  "checksum": "a1b2c3d4e5f6",
  "name": "My New Project Form"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the newly created form.

#### Response Example
```json
{
  "id": "form_xyz789"
}
```
```

--------------------------------

### Fieldwire Webhook Subscription Creation Response

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Example JSON response received after successfully creating a webhook subscription. It includes the unique subscription ID, name, description, post URL, status, account ID, and empty arrays for filters if none were specified.

```json
{
  "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
  "subscription_name": "Example Webhook Subscription",
  "description": "This is a demo subscription",
  "post_url": "https://Example.com/test",
  "subscription_status": "enabled",
  "account_id": "<account_id>",
  "internal": false,
  "entity_filters": [],
	"project_filters": []
}
```

--------------------------------

### Get All Subscriptions (cURL)

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Retrieves all subscriptions for an account. This cURL command sends a GET request to the subscriptions endpoint with necessary headers for authentication and content type.

```curl
curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>'
```

--------------------------------

### Example cURL Request with Fieldwire-Version Header

Source: https://developers.fieldwire.com/docs/versioning

This cURL example demonstrates how to make an API request to Fieldwire, specifying a particular version using the 'Fieldwire-Version' header. It includes common headers like 'accept', 'authorization', and 'content-type'. This is useful for compatibility when using older API versions.

```curl
curl --request POST \
  --url /api/v3/projects \
  --header 'accept: application/json' \
  --header 'authorization: Authorization <access_token>' \
  --header 'content-type: application/json'\
  --header 'Fieldwire-Version: 2020-06-23'
```

--------------------------------

### Get All Subscriptions

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Retrieves all webhook subscriptions associated with a given account. This endpoint returns an array of subscription objects.

```APIDOC
## GET /webhook/account/{{account_id}}/subscriptions

### Description
Retrieves all webhook subscriptions present on the account.

### Method
GET

### Endpoint
`https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions`

### Query Parameters
- **account_id** (string) - Required - The ID of the account for which to retrieve subscriptions.

### Request Headers
- **Content-Type**: `application/json`
- **Authorization**: `Bearer <access_token>`

### Response
#### Success Response (200)
An array of JSON objects, where each object represents a subscription.

- **subscription_id** (string) - The unique identifier for the subscription.
- **subscription_name** (string) - The name of the subscription.
- **description** (string) - A description of the subscription.
- **post_url** (string) - The URL where webhook events will be posted.
- **subscription_status** (string) - The current status of the subscription (e.g., 'enabled').
- **account_id** (string) - The ID of the account associated with the subscription.
- **internal** (boolean) - Indicates if the subscription is internal.
- **entity_filters** (array) - Filters applied to entity events.
- **project_filters** (array) - Filters applied to project events.

### Response Example (200)
```json
[
  {
    "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
    "subscription_name": "Example Webhook Subscription",
    "description": "This is a demo subscription",
    "post_url": "https://Example.com/test",
    "subscription_status": "enabled",
    "account_id": "<account_id>",
    "internal": false,
    "entity_filters": [],
    "project_filters": []
  }
]
```
```

--------------------------------

### GET /api/v3/projects/{project_id}/forms/{id}/full?jid={jid}

Source: https://developers.fieldwire.com/docs/getting-form-data

Retrieves the complete form data once the job initiated by the /full endpoint is complete. If the form data is not ready, polling this endpoint with the same jid may be required.

```APIDOC
## GET /api/v3/projects/{project_id}/forms/{id}/full?jid={jid}

### Description
Retrieves the complete form data once the job initiated by the /full endpoint is complete. If the form data is not ready, polling this endpoint with the same jid may be required.

### Method
GET

### Endpoint
`/api/v3/projects/{project_id}/forms/{id}/full`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **id** (string) - Required - The ID of the form.

#### Query Parameters
- **jid** (string) - Required - The job ID obtained from the initial call to the /full endpoint.

### Request Example
```
GET /api/v3/projects/12345/forms/abcde/full?jid=221d6504-d50b-408f-ade3-769102920f29
```

### Response
#### Success Response (200)
- **form_data** (object) - Contains all the data for the form instance, including sections, inputs, and values.

#### Response Example
(Response structure can be complex and varies based on form template. See Form Parsing section in the main documentation for details.)
```json
{
  "form_data": {
    "form_sections": [
      {
        "id": "section1",
        "name": "Section Name",
        "type": "text",
        "ordinal": 1,
        "form_section_records": [
          {
            "id": "record1",
            "name": "Record Name",
            "ordinal": 1,
            "form_section_record_inputs": [
              {
                "id": "input1",
                "name": "Input Name"
              }
            ],
            "form_section_record_values": [
              {
                "id": "value1",
                "form_section_record_input_id": "input1",
                "data": {
                  "text": "User input text"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### GET /projects - List Projects with Pagination

Source: https://developers.fieldwire.com/docs/pagination

This endpoint retrieves a list of projects. Pagination is controlled using the `Fieldwire-Per-Page` request header and the `X-Last-Synced-At` query parameter for subsequent requests.

```APIDOC
## GET /projects

### Description
Retrieves a list of projects with support for pagination.

### Method
GET

### Endpoint
/projects

### Parameters
#### Request Headers
- **Fieldwire-Per-Page** (integer) - Optional - Number of items to return per page. Defaults to 50, max 1000.
- **Authorization** (string) - Required - Bearer token for authentication.
- **Fieldwire-Version** (string) - Required - API version.

#### Query Parameters
- **last_synced_at** (string) - Optional - UTC timestamp to fetch items updated after this time. Used for subsequent page requests.

### Request Example (First Page)
```http
GET /projects HTTP/1.1
Authorization: Bearer <access_token>
Fieldwire-Per-Page: 100
Fieldwire-Version: 2023-12-25
```

### Response
#### Success Response (200)
- **X-Count** (integer) - Number of entities in the response.
- **X-Has-More** (boolean) - Indicates if additional entities exist.
- **X-Last-Synced-At** (string) - UTC timestamp for use in the `last_synced_at` query parameter for the next request.

#### Response Example (First Page)
```json
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"
  }
]
```

### Request Example (Second Page)
```http
GET /projects?last_synced_at=2019-01-01T00:00:00.000Z HTTP/1.1
Authorization: Bearer <access_token>
Fieldwire-Per-Page: 100
Fieldwire-Version: 2023-12-25
```

### Response Example (Second Page)
```json
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"
  }
]
```
```

--------------------------------

### Get Single Subscription (cURL)

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Retrieves details for a specific subscription. This cURL command sends a GET request to the subscriptions endpoint, including the subscription ID and authentication token.

```curl
curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/<account_id>/subscriptions/<subscription_id>' \
  --header 'Authorization: Bearer <access_token>'
```

--------------------------------

### Generate a new form by ID

Source: https://developers.fieldwire.com/docs/working-with-project-forms

Generates a form from a form template using the form record ID obtained from the 'Create a new form' endpoint.

```APIDOC
## POST /api/forms/{form_id}/generate

### Description
Generates the actual form content from a previously created form record and its associated form template. This step populates the form with data fields based on the template.

### Method
POST

### Endpoint
/api/forms/{form_id}/generate

### Parameters
#### Path Parameters
- **form_id** (string) - Required - The ID of the form record created via the 'Create a new form' endpoint.

### Request Example
(No request body is typically required for this operation)

### Response
#### Success Response (200 OK)
- **status** (string) - Indicates the success of the generation process (e.g., "generated").

#### Response Example
```json
{
  "status": "generated"
}
```
```

--------------------------------

### Example API Query with Multiple Values for a Filter

Source: https://developers.fieldwire.com/docs/filtering

Illustrates how to filter tasks by multiple status values using the Fieldwire API. This allows for retrieving records that match any of the specified values for a given filter.

```text
/api/v3/projects/<project_id>/tasks/?filters[status_eq][]=requested&filters[status_eq][]=waiting
```

--------------------------------

### Generate Access Token

Source: https://developers.fieldwire.com/docs/authentication

This endpoint is used to generate a JWT access token using an acquired refresh token (API key).

```APIDOC
## POST /api_keys/jwt

### Description
Generates a JWT access token using a refresh token.

### Method
POST

### Endpoint
https://client-api.super.fieldwire.com/api_keys/jwt

### Parameters
#### Request Body
- **api_token** (string) - Required - The refresh token or API key.

### Request Example
```json
{
  "api_token": "<refresh_token or api_token>"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The generated JWT access token.

#### Response Example
```json
{
  "access_token": "<access_token>"
}
```
```

--------------------------------

### Update Fieldwire Webhook Subscription using cURL

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Example of how to update a webhook subscription using a cURL command. It demonstrates sending a PATCH request with a JSON payload to the specific subscription endpoint, allowing partial updates to the subscription details.

```curl
curl --location --request PATCH 'https://webhook-api.us.fieldwire.com/webhook/account/<Account ID>/subscriptions/<Subscription ID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{
    "subscription_name": "Updated Subscription Name"
  }'
```

--------------------------------

### Get Task Attributes for a Specific Task

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Retrieves the custom task attribute values for a particular task.

```APIDOC
## GET /api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/

### Description
Retrieves the custom task attribute values that have been set for a specific task. If an attribute has not been populated, it will not appear in the response.

### Method
GET

### Endpoint
`/api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier for the project.
- **task_id** (string) - Required - The unique identifier for the task.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the task attribute instance on the task.
- **task_type_attribute_id** (string) - The ID of the custom task attribute definition.
- **task_type** (string) - The ID of the task type.
- **text_value** (string) - The text value of the attribute (if applicable).
- **number_value** (number) - The number value of the attribute (if applicable).
- **uuid_value** (string) - The UUID value of the attribute (if applicable, for list types).

#### Response Example
```json
[
  {
    "id": "<task_attribute_id>",
    "task_type_attribute_id": "<task_type_attribute_id>",
    "task_type": "<task_type>",
    "text_value": "Example Text"
  }
]
```
```

--------------------------------

### Get All Task Attributes for a Project

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Retrieves all custom task attribute values for all tasks within a project.

```APIDOC
## GET /api/v3/projects/<project_id>/task_attributes

### Description
Retrieves all custom task attribute values for all tasks within a specified project. This provides a comprehensive view of all CTA data across the project.

### Method
GET

### Endpoint
`/api/v3/projects/<project_id>/task_attributes`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier for the project.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the task attribute instance on a task.
- **task_id** (string) - The ID of the task the attribute belongs to.
- **task_type_attribute_id** (string) - The ID of the custom task attribute definition.
- **task_type** (string) - The ID of the task type.
- **text_value** (string) - The text value of the attribute (if applicable).
- **number_value** (number) - The number value of the attribute (if applicable).
- **uuid_value** (string) - The UUID value of the attribute (if applicable, for list types).

#### Response Example
```json
[
  {
    "id": "<task_attribute_id>",
    "task_id": "<task_id>",
    "task_type_attribute_id": "<task_type_attribute_id>",
    "task_type": "<task_type>",
    "text_value": "Example Text"
  }
]
```
```

--------------------------------

### Get Project Task Type Attributes

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Retrieves the list of custom task attributes configured for a specific project.

```APIDOC
## GET /api/v3/projects/<project_id>/task_type_attributes

### Description
Retrieves a list of all custom task attributes configured for a given project. This is the first step in managing or retrieving CTA values.

### Method
GET

### Endpoint
`/api/v3/projects/<project_id>/task_type_attributes`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier for the project.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the task type attribute.
- **task_type_id** (string) - The identifier for the task type this attribute belongs to.
- **name** (string) - The name of the custom task attribute.
- **attribute_type** (string) - The type of the attribute (e.g., 'short_text', 'number', 'list').

#### Response Example
```json
[
  {
    "id": "<task_type_attribute_id>",
    "task_type_id": "<task_type>",
    "name": "Attribute Name",
    "attribute_type": "short_text"
  }
]
```
```

--------------------------------

### Get All Task Attributes for a Project

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Retrieves all custom task attribute values for all tasks within a given project. This provides a comprehensive overview of CTAs across the project. Note that attributes not yet populated on any task will not be included.

```text
GET /api/v3/projects/<project_id>/task_attributes
```

--------------------------------

### Get Task Attributes for a Specific Task

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Fetches the custom task attribute values for a single, specified task within a project. If a CTA has not been populated for the task, it will not appear in the response. List attribute values are returned as UUIDs.

```text
GET /api/v3/projects/<project_id>/tasks/<task_id>/task_attributes/
```

--------------------------------

### Create Form Record (JSON)

Source: https://developers.fieldwire.com/docs/working-with-project-forms

This snippet shows the minimum required JSON body to create a new form record via the API. It includes essential user IDs, the form template ID, checksum, and a name for the form. The response from this POST request provides an 'id' used in subsequent generation steps.

```json
{
  "creator_user_id": <user_id>,
  "last_editor_user_id": <user_id>,
  "owner_user_id": <user_id>,
  "form_template_id": "<form_template_id>",
  "checksum": "<form_template_checksum>",
  "name": "<name>"
}
```

--------------------------------

### Uploading Spec Books

Source: https://developers.fieldwire.com/docs/working-with-specifications

Upload a spec book to a Fieldwire project. This requires generating an AWS token, uploading the file to S3, and then making a POST request to Fieldwire.

```APIDOC
## POST /api/projects/{project_id}/specifications/upload

### Description
Initiates the upload process for a specification book to a project after the file has been uploaded to S3.

### Method
POST

### Endpoint
`/api/projects/{project_id}/specifications/upload`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier for the project.

#### Query Parameters
None

#### Request Body
- **file_url** (string) - Required - The URL of the spec book file previously uploaded to S3.
- **filename** (string) - Required - The name of the spec book file.

### Request Example
```json
{
  "file_url": "https://your-s3-bucket.s3.amazonaws.com/spec_book.pdf",
  "filename": "Project Spec Book"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the spec book upload job.
- **status** (string) - The current status of the upload process (e.g., "processing", "completed").

#### Response Example
```json
{
  "id": "spec_upload_12345",
  "status": "processing"
}
```
```

--------------------------------

### Get Project Task Type Attributes

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Retrieves a list of all custom task attributes configured for a specific project. This is a prerequisite for setting or updating CTA values. The response contains attribute IDs and types needed for subsequent API calls.

```text
GET /api/v3/projects/<project_id>/task_type_attributes
```

--------------------------------

### Create Webhook Subscription

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Creates a new webhook subscription to receive notifications when changes occur in Fieldwire projects. Requires a callback URL for receiving event data.

```APIDOC
## POST /webhook/account/{account_id}/subscriptions

### Description
Creates a new webhook subscription to receive notifications for project changes in Fieldwire. You must provide a `post_url` where event data will be sent.

### Method
POST

### Endpoint
`/webhook/account/{account_id}/subscriptions`

### Parameters
#### Path Parameters
- **account_id** (string) - Required - The ID of the account for which to create the subscription.

#### Query Parameters
None

#### Request Body
- **subscription_name** (string) - Required - Name of the subscription (max 50 characters).
- **description** (string) - Required - Description of the subscription (max 200 characters).
- **post_url** (string) - Required - The URL to which event data will be posted.
- **subscription_status** (string) - Required - The status of the subscription, either "enabled" or "disabled".
- **entity_filters** (array) - Optional - Filters events by entity type and action (max 20 entries).
- **project_filters** (array) - Optional - Filters events by project IDs (max 100 entries).

### Request Example
```curl
curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/<Account ID>/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{
    "subscription_name": "Example Webhook Subscription",
    "description": "This is a demo subscription",
    "post_url": "https://Example.com/test",
    "subscription_status": "enabled"
  }'
```

### Response
#### Success Response (201)
- **subscription_id** (string) - The unique identifier for the created subscription.
- **subscription_name** (string) - The name of the subscription.
- **description** (string) - The description of the subscription.
- **post_url** (string) - The callback URL for the subscription.
- **subscription_status** (string) - The status of the subscription ("enabled" or "disabled").
- **account_id** (string) - The ID of the account associated with the subscription.
- **internal** (boolean) - Indicates if the subscription is internal to Fieldwire.
- **entity_filters** (array) - The entity filters applied to the subscription.
- **project_filters** (array) - The project filters applied to the subscription.

#### Response Example
```json
{
  "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
  "subscription_name": "Example Webhook Subscription",
  "description": "This is a demo subscription",
  "post_url": "https://Example.com/test",
  "subscription_status": "enabled",
  "account_id": "<account_id>",
  "internal": false,
  "entity_filters": [],
  "project_filters": []
}
```
```

--------------------------------

### Set Number Custom Task Attribute Value

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Example JSON payload for setting a 'number' type custom task attribute on a task. Requires the numeric value, the attribute's ID, the task's type, and the creator's user ID.

```json
{
  "number_value": 1234567,
  "task_type_attribute_id":"<task_type_attribute_id>",
  "task_type":"<task_type>",
  "creator_user_id":<user_id>
}
```

--------------------------------

### Set List Custom Task Attribute Value

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Example JSON payload for setting a 'list' type custom task attribute on a task. Requires the UUID of the selected list item, the attribute's ID, the task's type, and the creator's user ID.

```json
{
  "uuid_value": <list value uuid>,
  "task_type_attribute_id":"<task_type_attribute_id>",
  "task_type":"<task_type>",
  "creator_user_id":<user_id>
}
```

--------------------------------

### API Terminology Mapping

Source: https://developers.fieldwire.com/docs/api-translation-guide

This section outlines the mapping between Fieldwire application names and their corresponding API names, along with notes and links to relevant API documentation.

```APIDOC
## API Terminology Mapping

This guide helps translate Fieldwire app terminology to Fieldwire API terminology.

### Mapping Table

| Fieldwire App name     | Fieldwire API name                                                                                                                                                                                                         |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Task Category          | [Teams](https://developers.fieldwire.com/reference/get_teams_in_project) - `task.team_id`                                                                                                                                  |
| Task Assignee          | `task.owner_user_id`                                                                                                                                                                                                       |
| Task Messages          | [Bubbles](https://developers.fieldwire.com/reference/get_bubbles_in_project)                                                                                                                                               |
| Tags                   | [Entity Tags](https://developers.fieldwire.com/reference/get_entity_tags_in_project) & [Entity Taggings](https://developers.fieldwire.com/reference/get_entity_taggings_in_project)                                        |
| Custom Task Attributes | [Task Type Attributes](https://developers.fieldwire.com/reference/get_task_type_attributes_in_project) & [Task Attributes](https://developers.fieldwire.com/reference/get_task_attributes_in_project)                      |
| Project Labels         | [Project Attributes](https://developers.fieldwire.com/reference/get_project_attributes_in_account) &  [Projects Project Attributes](https://developers.fieldwire.com/reference/get_projects_project_attributes_in_project) |
| Photos                 | [Attachments](https://developers.fieldwire.com/reference/get_attachment_by_id)                                                                                                                                             |

### Notes

- **Task Category**: Corresponds to `task.team_id` in the API.
- **Task Assignee**: Refers to `task.owner_user_id` in the API.
- **Task Messages**: Mapped to 'Bubbles' in the API. See [get_bubbles_in_project](https://developers.fieldwire.com/reference/get_bubbles_in_project).
- **Tags**: Represented by 'Entity Tags' and 'Entity Taggings' in the API. Refer to [get_entity_tags_in_project](https://developers.fieldwire.com/reference/get_entity_tags_in_project) and [get_entity_taggings_in_project](https://developers.fieldwire.com/reference/get_entity_taggings_in_project).
- **Custom Task Attributes**: Mapped to 'Task Type Attributes' and 'Task Attributes'. See [docs](https://developers.fieldwire.com/docs/custom-task-attributes) for more information.
- **Project Labels**: Corresponds to 'Project Attributes' and 'Projects Project Attributes'. See [Q&A](https://developers.fieldwire.com/discuss/63ff9cce0f35ab001fa616a4) for details.
- **Photos**: Are a type of 'Attachments' in the API. See [get_attachment_by_id](https://developers.fieldwire.com/reference/get_attachment_by_id).
```

--------------------------------

### Create Fieldwire Webhook Subscription Request Body

Source: https://developers.fieldwire.com/docs/beta-creating-webhook-configurations

Defines the structure for creating a new webhook subscription. Requires a name, description, a callback URL (post_url), and status. Optional filters can be applied to specific entities or projects. The callback URL is where Fieldwire will send notifications.

```json
{
  "subscription_name":{{subscription_name}},
  "description": {{description}},
  "post_url": {{post_url}},
  "subscription_status": {{subscription_status}},
	"entity_filters": [{{Entity.Action}}],
   "project_filters": [{{Project_ids}}]
}
```

--------------------------------

### Set Short Text Custom Task Attribute Value

Source: https://developers.fieldwire.com/docs/custom-task-attributes

Example JSON payload for setting a 'short text' type custom task attribute on a task. Requires the text value, the attribute's ID, the task's type, and the creator's user ID.

```json
{
  "text_value":"lorem ipsum dolor sit amet",
  "task_type_attribute_id":"<task_type_attribute_id>",
  "task_type":"<task_type>",
  "creator_user_id":<user_id>
}
```

--------------------------------

### Introduction to Filtering

Source: https://developers.fieldwire.com/docs/filtering

Fieldwire supports API filters as query parameters on select endpoints to help users retrieve only the necessary information. This section provides an overview of the filtering capabilities.

```APIDOC
## Filtering Overview

Fieldwire API supports filtering data as query parameters on specific endpoints. This allows users to retrieve precise information without unnecessary records.

### Purpose
To enable targeted data retrieval from the API.

### Usage
Filters are applied as query parameters in API calls. Multiple filters can be combined for more specific results.

### Note
This document assumes familiarity with the Fieldwire API.
```

--------------------------------

### Make Authenticated API Call with Access Token (curl)

Source: https://developers.fieldwire.com/docs/authentication

This snippet shows how to make an authenticated GET request to a Fieldwire API endpoint using a previously generated access token. The access token must be included in the 'Authorization' header as a Bearer token. This method is used for all subsequent API interactions until the access token expires.

```curl
curl --request GET \
     --url https://client-api.us.fieldwire.com/api/v3/projects/d2e57ef9-5315-4fdb-bc56-8c56983788ce \
     --header 'Fieldwire-Version: 2023-11-30' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <access_token>'
```

```json
{
  "deleted_at": null,
  "created_at": "2023-11-08T03:45:19.829Z",
  "updated_at": "2023-11-08T03:45:19.842Z",
  "account_id": 1234,
  "code": null,
  "color": "#F9CD39",
  "id": "d2e57ef9-5315-4fdb-bc56-8c56983788ce",
  "name": "Example project - 1",
  "plan_name": "Enterprise",
  ...
}
```