Fieldguide engagements API
Endpoints used to interact with Fieldguide Engagements
OpenAPI Specification
openapi: 3.0.0
info:
title: Fieldguide api engagements API
description: An API for interacting with the [Fieldguide](https://fieldguide.io) platform
version: v1
contact: {}
servers:
- url: https://api.fieldguide.io
description: Fieldguide API
security:
- bearer: []
tags:
- name: engagements
description: Endpoints used to interact with Fieldguide Engagements
paths:
/v1/companies/{uuid}/engagements:
get:
operationId: list_engagements_by_company_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Company to retrieve engagements from
schema:
format: uuid
type: string
- name: page
required: false
in: query
schema:
type: number
default: 1
nullable: true
- name: per_page
required: false
in: query
schema:
type: number
default: 50
nullable: true
minimum: 1
maximum: 200
- name: sort_order
required: false
in: query
description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
schema:
type: string
default: asc
enum:
- asc
- desc
responses:
'200':
description: The Engagements for the specified Company
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/EngagementRead'
- properties:
_links:
type: object
required:
- self
- first
- last
properties:
self:
type: object
description: The URL for the current page being fetched
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=2&per_page=50
first:
type: object
description: The URL for the first page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
last:
type: object
description: The URL for the last page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=10&per_page=50
previous:
type: object
description: The URL for the previous page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
next:
type: object
description: The URL for the next page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=3&per_page=50
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:read`)
'429':
description: Too many requests
summary: Get engagements for a given company
tags:
- engagements
x-required-scopes:
- engagements:read
/v1/engagements:
get:
operationId: list_engagements_v1
parameters:
- name: templates
required: false
in: query
description: Filter to include, exclude, or only show template engagements
schema:
$ref: '#/components/schemas/TemplatesQuery'
- name: uuids
required: false
in: query
description: Filter Engagements by UUID. Repeat the query parameter for multiple UUIDs.
schema:
type: array
items:
type: string
format: uuid
- name: engagement_lead_user_uuid
required: false
in: query
description: Filter Engagements by the UUID of their Engagement Lead User.
schema:
format: uuid
type: string
- name: client_owner_user_uuid
required: false
in: query
description: Filter Engagements by the UUID of their Client Owner User.
schema:
format: uuid
type: string
- name: statuses
required: false
in: query
description: Filter Engagements by status. Repeat the query parameter for multiple statuses.
schema:
type: array
items:
$ref: '#/components/schemas/EngagementsQueryStatusLabel'
- name: page
required: false
in: query
schema:
type: number
default: 1
nullable: true
- name: per_page
required: false
in: query
schema:
type: number
default: 50
nullable: true
minimum: 1
maximum: 200
- name: sort_order
required: false
in: query
description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
schema:
type: string
default: asc
enum:
- asc
- desc
responses:
'200':
description: The Engagements accessible by the user
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/EngagementRead'
- properties:
_links:
type: object
required:
- self
- first
- last
properties:
self:
type: object
description: The URL for the current page being fetched
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=2&per_page=50
first:
type: object
description: The URL for the first page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
last:
type: object
description: The URL for the last page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=10&per_page=50
previous:
type: object
description: The URL for the previous page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
next:
type: object
description: The URL for the next page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=3&per_page=50
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:read`)
'429':
description: Too many requests
summary: List available Engagements
tags:
- engagements
x-required-scopes:
- engagements:read
/v1/engagements/{uuid}:
get:
operationId: get_engagement_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to retrieve
schema:
format: uuid
type: string
responses:
'200':
description: The Engagement details
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: Fetch the specified Engagement
tags:
- engagements
x-required-scopes:
- engagements:read
patch:
operationId: update_engagement_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to update
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EngagementUpdate'
responses:
'200':
description: The updated Engagement data
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:write`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: Update the specified Engagement
tags:
- engagements
x-required-scopes:
- engagements:write
/v1/engagements/from-template:
post:
description: Creates a new Engagement based on an existing template Engagement. The request is accepted for asynchronous processing; the response returns the new Engagement's UUID, which may not be fully provisioned immediately.
operationId: create_engagement_from_template_v1
parameters: []
requestBody:
required: true
description: Engagement creation from template options
content:
application/json:
schema:
$ref: '#/components/schemas/EngagementCreateFromTemplate'
responses:
'202':
description: The Engagement creation has been accepted for processing
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementUuidRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: 'Forbidden (requires permission `[''insert'', ''engagements'']`)
Forbidden (requires scopes `engagements:write`)'
'429':
description: Too many requests
summary: Create a new Engagement from a template
tags:
- engagements
x-required-scopes:
- engagements:write
/v1/engagements/{uuid}/export:
post:
description: 'Begins a long-running process that will generate an Engagement binder as a zip file.
Use the Job ID that this endpoint returns with the appropriate [jobs endpoint](#/jobs/get_job_v1) to check its status and get its result.'
operationId: export_engagement_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to export
schema:
format: uuid
type: string
responses:
'202':
headers:
Location:
description: The URI to check the status of the job
schema:
type: string
example: https://api.fieldguide.io/v1/jobs/f2c75e84-6b42-452d-b52f-3bf1854432d6
Retry-After:
description: A date-time estimate of when the job will complete (if the job is still running)
schema:
type: string
format: date-time
example: '2025-04-04T12:30:00.000Z'
required: false
description: The Job UUID for the Engagement binder export
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/JobSubmittedRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: Export an Engagement binder
tags:
- engagements
x-required-scopes:
- engagements:read
/v1/engagements/exports/{uuid}:
get:
description: Returns the download URL and metadata for a completed Engagement binder export. Call this once the export Job returned by the export endpoint has finished.
operationId: get_engagement_export_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Job
schema:
format: uuid
type: string
responses:
'200':
description: The exported Engagement binder file metadata and download URL
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementExportRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: Fetch a generated Engagement binder report
tags:
- engagements
x-required-scopes:
- engagements:read
/v1/engagements/{uuid}/users:
get:
operationId: list_engagement_users_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to retrieve Users for
schema:
format: uuid
type: string
- name: page
required: false
in: query
schema:
type: number
default: 1
nullable: true
- name: per_page
required: false
in: query
schema:
type: number
default: 50
nullable: true
minimum: 1
maximum: 200
- name: sort_order
required: false
in: query
description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
schema:
type: string
default: asc
enum:
- asc
- desc
responses:
'200':
description: The users on the Engagement Team for the specified Engagement
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/EngagementUserRead'
- properties:
_links:
type: object
required:
- self
- first
- last
properties:
self:
type: object
description: The URL for the current page being fetched
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=2&per_page=50
first:
type: object
description: The URL for the first page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
last:
type: object
description: The URL for the last page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=10&per_page=50
previous:
type: object
description: The URL for the previous page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
next:
type: object
description: The URL for the next page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=3&per_page=50
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:read`, `users:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List the Engagement Team on an Engagement
tags:
- engagements
x-required-scopes:
- engagements:read
- users:read
patch:
operationId: add_engagement_users_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to add Users to
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EngagementUserCreate'
responses:
'204':
description: No content. The Users were added to the Engagement Team successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:write`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: Add Users to an Engagement Team
tags:
- engagements
x-required-scopes:
- engagements:write
delete:
operationId: remove_engagement_users_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement to delete Users from
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EngagementUserDelete'
responses:
'204':
description: No content. The Users were removed from the Engagement Team successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:write`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: Remove Users from an Engagement Team
tags:
- engagements
x-required-scopes:
- engagements:write
/v1/engagements/{uuid}/requests:
get:
operationId: list_requests_by_engagement_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the engagement to retrieve requests for
schema:
format: uuid
type: string
- name: statuses
required: false
in: query
description: Filter Requests by status. Repeat the query parameter for multiple statuses.
schema:
type: array
items:
$ref: '#/components/schemas/RequestStatus'
- name: client_owner_user_uuids
required: false
in: query
description: Filter Requests by the UUID of their Client Owner Users. Repeat the query parameter for multiple UUIDs.
schema:
type: array
items:
type: string
format: uuid
- name: due_date_before
required: false
in: query
description: Filter Requests to those with a due date before this date. Uses strict before semantics and excludes Requests with no due date.
schema:
format: date
example: '2024-05-01'
type: string
- name: page
required: false
in: query
schema:
type: number
default: 1
nullable: true
- name: per_page
required: false
in: query
schema:
type: number
default: 50
nullable: true
minimum: 1
maximum: 200
- name: sort_order
required: false
in: query
description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
schema:
type: string
default: asc
enum:
- asc
- desc
responses:
'200':
description: The Requests for the Engagement
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/RequestRead'
- properties:
_links:
type: object
required:
- self
- first
- last
properties:
self:
type: object
description: The URL for the current page being fetched
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=2&per_page=50
first:
type: object
description: The URL for the first page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
last:
type: object
description: The URL for the last page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=10&per_page=50
previous:
type: object
description: The URL for the previous page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
next:
type: object
description: The URL for the next page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=3&per_page=50
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `requests:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List Requests that belong to the specified Engagement
tags:
- engagements
x-required-scopes:
- requests:read
/v1/engagements/{uuid}/sheets:
get:
operationId: list_sheets_by_engagement_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement for which to get Sheets
schema:
format: uuid
type: string
- name: page
required: false
in: query
schema:
type: number
default: 1
nullable: true
- name: per_page
required: false
in: query
schema:
type: number
default: 50
nullable: true
minimum: 1
maximum: 200
- name: sort_order
required: false
in: query
description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
schema:
type: string
default: asc
enum:
- asc
- desc
responses:
'200':
description: The Sheets to which the Engagement is linked
content:
application/json:
schema:
allOf:
- properties:
data:
type: array
items:
$ref: '#/components/schemas/SheetRead'
- properties:
_links:
type: object
required:
- self
- first
- last
properties:
self:
type: object
description: The URL for the current page being fetched
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=2&per_page=50
first:
type: object
description: The URL for the first page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
last:
type: object
description: The URL for the last page of the set
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=10&per_page=50
previous:
type: object
description: The URL for the previous page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=1&per_page=50
next:
type: object
description: The URL for the next page in the set, if there is one
properties:
href:
type: string
example: https://api.fieldguide.io/v1/example?page=3&per_page=50
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements:read`, `sheets:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List Sheets that belong to the specified Engagement
tags:
- engagements
x-required-scopes:
- engagements:read
- sheets:read
/v1/engagements/{uuid}/folders:
get:
operationId: list_engagement_folders_v1
parameters:
- name: uuid
required: true
in: path
description: The UUID of the Engagement for which to get Folders
schema:
format: uuid
type: string
- name: parent_folder_uuid
required: false
in: query
description: An optional UUID of the parent folder
schema:
format: uuid
type: string
- name: page
required: false
in: query
schema:
type: number
default: 1
nullable: true
- name: per_page
required: false
in: query
schema:
type: number
default: 50
nullable: true
minimum: 1
maximum: 200
- name: sort_order
required: false
in: query
description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
schema:
type: string
default: asc
enum:
- asc
- desc
responses:
'200':
description: The list of Engagement Folders
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementFolderRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements.files:read`)
'404':
description: Resource not found
'429':
description: Too many requests
summary: List Folders that belong to the specified Engagement
tags:
- engagements
x-required-scopes:
- engagements.files:read
/v1/engagements/{engagement_uuid}/folders/{folder_uuid}:
get:
operationId: get_engagement_folder_v1
parameters:
- name: engagement_uuid
required: true
in: path
description: The UUID of the Engagement from which to get a Folder
schema:
format: uuid
type: string
- name: folder_uuid
required: true
in: path
description: The UUID of the folder to fetch
schema:
format: uuid
type: string
responses:
'200':
description: The Engagement Folder with the specified UUID
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/EngagementFolderRead'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden (requires scopes `engagements.files:read`)
'404':
description: Resource not found
'429':
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fieldguide/refs/heads/main/openapi/fieldguide-engagements-api-openapi.yml