412 lines
16 KiB
Markdown
412 lines
16 KiB
Markdown
# List all Form Responses
|
|
|
|
|
|
|
|
#### Filtering
|
|
This endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).
|
|
|
|
|
|
#### OAuth Scope
|
|
This endpoint requires the following OAuth scope **read_forms**.
|
|
|
|
|
|
|
|
# OpenAPI definition
|
|
|
|
```json
|
|
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "ServiceM8 API",
|
|
"description": "Move your app forward with the ServiceM8 API\n\n\n\n## Limits and Throttling\nTo ensure continuous quality of service, API usage can be subject to throttling. The throttle will be applied once an API consumer reaches a certain \nthreshold in terms of a maximum number of requests per minute. Most clients will never hit this threshold, but those that do, will get met by a \nHTTP 429 Too Many Requests response code. \n \nThere is a limit of 180 requests per minute, if you reach this you will receive a HTTP 429 with a text body of \"Number of allowed API requests per minute exceeded\".\nThere is a limit of 20000 requests per day, if you reach this you will receive a HTTP 429 with a text body of \"Number of allowed API requests per day exceeded\".\n\nWe encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).\n\nLimits are per Addon per account.\n",
|
|
"termsOfService": "https://www.servicem8.com/terms-of-service",
|
|
"version": "1.0.0"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://api.servicem8.com/api_1.0"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"apiKey": []
|
|
},
|
|
{
|
|
"oauth2": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/formresponse.json": {
|
|
"get": {
|
|
"tags": [
|
|
"Form Responses"
|
|
],
|
|
"operationId": "listFormResponses",
|
|
"summary": "List all Form Responses",
|
|
"description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_forms**.\n\n\t\t\t",
|
|
"security": [
|
|
{
|
|
"apiKey": []
|
|
},
|
|
{
|
|
"oauth2": [
|
|
"read_forms"
|
|
]
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "An array of Form Responses",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/FormResponse"
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"value": [
|
|
{
|
|
"uuid": "123e4567-af16-4618-80c7-23f940cc449b",
|
|
"active": 1,
|
|
"edit_date": "2026-03-01 12:00:00",
|
|
"form_uuid": "123e4567-f8b2-4802-a8db-23f94cf50e1b",
|
|
"staff_uuid": "123e4567-5c89-4cb3-8dc0-23f94d75521b",
|
|
"regarding_object": "string",
|
|
"regarding_object_uuid": "123e4567-016e-482c-a3f7-23f943f6d72b",
|
|
"field_data": "string",
|
|
"timestamp": "2026-03-01 12:00:00",
|
|
"form_by_staff_uuid": "123e4567-44e8-448d-925c-23f9435b205b",
|
|
"document_attachment_uuid": "123e4567-2f15-479f-8791-23f94c0fbbbb",
|
|
"asset_uuid": "123e4567-89f4-4183-ae1e-23f94832e59b"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Bad Request - The request is malformed or contains invalid parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"examples": {
|
|
"badRequest": {
|
|
"value": {
|
|
"errorCode": "1000",
|
|
"message": "An error occurred completing your request"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"description": "Unauthorized - Authentication credentials are missing or invalid",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AuthenticationError"
|
|
},
|
|
"examples": {
|
|
"unauthorized": {
|
|
"value": {
|
|
"errorCode": "401",
|
|
"message": "Authentication failed. Please check your API key or OAuth token."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "Forbidden - You don't have permission to access this resource",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ForbiddenError"
|
|
},
|
|
"examples": {
|
|
"forbidden": {
|
|
"value": {
|
|
"errorCode": "403",
|
|
"message": "Access forbidden. You don't have permission to access this resource."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "Too Many Requests - You have exceeded the rate limit",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RateLimitError"
|
|
},
|
|
"examples": {
|
|
"rateLimitMinute": {
|
|
"value": {
|
|
"errorCode": 429,
|
|
"message": "Number of allowed API requests per minute exceeded"
|
|
}
|
|
},
|
|
"rateLimitDay": {
|
|
"value": {
|
|
"errorCode": 429,
|
|
"message": "Number of allowed API requests per day exceeded"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal Server Error - An unexpected error occurred on the server",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
},
|
|
"examples": {
|
|
"serverError": {
|
|
"value": {
|
|
"errorCode": 500,
|
|
"message": "An unexpected error occurred. Please try again later."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"apiKey": {
|
|
"type": "apiKey",
|
|
"name": "X-Api-Key",
|
|
"in": "header"
|
|
},
|
|
"oauth2": {
|
|
"type": "oauth2",
|
|
"flows": {
|
|
"authorizationCode": {
|
|
"authorizationUrl": "https://api.servicem8.com/oauth/authorize",
|
|
"tokenUrl": "https://api.servicem8.com/oauth/access_token",
|
|
"scopes": {
|
|
"staff_locations": "Access to real-time GPS information about staff",
|
|
"staff_activity": "Access to clock on, lunch break and clock off information about staff",
|
|
"publish_sms": "Access to send SMS messages to customers and/or staff on your behalf. Note sending SMS messages will incur account charges.",
|
|
"publish_email": "Access to send Email messages to customers and/or staff on your behalf",
|
|
"vendor": "Access to basic account information",
|
|
"vendor_logo": "Access to account logo",
|
|
"vendor_email": "Access to account holder email address",
|
|
"read_locations": "Read-only access to Location Endpoint",
|
|
"manage_locations": "Full access to Location Endpoint",
|
|
"read_staff": "Read-only access to Staff Endpoint",
|
|
"manage_staff": "Full access to Staff Endpoint",
|
|
"read_customers": "Read-only access to Company Endpoint",
|
|
"manage_customers": "Full access to Company Endpoint",
|
|
"read_customer_contacts": "Read-only access to CompanyContact Endpoint",
|
|
"manage_customer_contacts": "Full access to CompanyContact Endpoint",
|
|
"read_jobs": "Read-only access to Job Endpoint",
|
|
"manage_jobs": "Full access to Job Endpoint",
|
|
"create_jobs": "Ability to create jobs on behalf of account. Note creating jobs may incur account charges.",
|
|
"read_job_contacts": "Read-only access to JobContact Endpoint",
|
|
"manage_job_contacts": "Full access to JobContact Endpoint",
|
|
"read_job_materials": "Read-only access to JobMaterials Endpoint",
|
|
"manage_job_materials": "Full access to JobMaterials Endpoint",
|
|
"read_job_categories": "Read-only access to Categories Endpoint",
|
|
"manage_job_categories": "Full access to Categories Endpoint",
|
|
"read_job_queues": "Read-only access to Job Queues Endpoint",
|
|
"manage_job_queues": "Full access to Job Queues Endpoint",
|
|
"read_tasks": "Read-only access to Tasks Endpoint",
|
|
"manage_tasks": "Full access to Tasks Endpoint",
|
|
"read_schedule": "Read-only access to JobActivity Endpoint",
|
|
"manage_schedule": "Full access to JobActivity Endpoint",
|
|
"read_inventory": "Read-only access to Materials Endpoint",
|
|
"manage_inventory": "Full access to Materials Endpoint",
|
|
"read_job_notes": "Read-only access to job notes",
|
|
"publish_job_notes": "Ability to add new job notes",
|
|
"read_job_photos": "Read-only access to job photos",
|
|
"publish_job_photos": "Ability to add new job photos",
|
|
"read_attachments": "Read-only access to Attachments Endpoint",
|
|
"manage_attachments": "Full access to Attachments Endpoint",
|
|
"read_inbox": "Read-only access to inbox messages",
|
|
"read_messages": "Read-only access to staff messages",
|
|
"manage_notifications": "Ability to read notifications and mark as read",
|
|
"manage_templates": "Full-access to email, sms and document templates",
|
|
"manage_badges": "Full-access to create/modify job badges",
|
|
"read_assets": "Read-only access to Assets Endpoint",
|
|
"manage_assets": "Full access to Assets Endpoint",
|
|
"read_knowledge_base": "Read-only access to Knowledge Base Endpoint",
|
|
"manage_knowledge_base": "Full access to Knowledge Base Endpoint"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"schemas": {
|
|
"Error": {
|
|
"type": "object",
|
|
"properties": {
|
|
"errorCode": {
|
|
"type": "number",
|
|
"format": "int32",
|
|
"example": "1000"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "An error occurred completing your request"
|
|
}
|
|
}
|
|
},
|
|
"RateLimitError": {
|
|
"type": "object",
|
|
"properties": {
|
|
"errorCode": {
|
|
"type": "number",
|
|
"format": "int32",
|
|
"example": "429"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Number of allowed API requests per minute exceeded"
|
|
}
|
|
}
|
|
},
|
|
"AuthenticationError": {
|
|
"type": "object",
|
|
"properties": {
|
|
"errorCode": {
|
|
"type": "number",
|
|
"format": "int32",
|
|
"example": "401"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Authentication failed. Please check your API key or OAuth token."
|
|
}
|
|
}
|
|
},
|
|
"ForbiddenError": {
|
|
"type": "object",
|
|
"properties": {
|
|
"errorCode": {
|
|
"type": "number",
|
|
"format": "int32",
|
|
"example": "403"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Access forbidden. You don't have permission to access this resource."
|
|
}
|
|
}
|
|
},
|
|
"FormResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"form_uuid": {
|
|
"description": "UUID of the form used to generate this form response. Links to a specific form in the system that defines the fields to be gathered.",
|
|
"format": "uuid",
|
|
"example": "123e4567-8f59-4273-9bb2-23f94e3071eb",
|
|
"type": "string"
|
|
},
|
|
"staff_uuid": {
|
|
"description": "UUID of the staff member who completed this FormResponse.",
|
|
"format": "uuid",
|
|
"example": "123e4567-068f-433c-a2e6-23f94e815bdb",
|
|
"type": "string"
|
|
},
|
|
"regarding_object": {
|
|
"description": "The object type that this form response is associated with. Common values include 'job', 'asset', or 'company'. Works in conjunction with regarding_object_uuid to link this form response to a specific record in the system.",
|
|
"type": "string"
|
|
},
|
|
"regarding_object_uuid": {
|
|
"description": "UUID of the specific record this form response is linked to. For example, if regarding_object is 'job', this will be the UUID of the specific job. This creates a relationship between the form response and the object it refers to.",
|
|
"format": "uuid",
|
|
"example": "123e4567-41ee-4ea3-8ca2-23f94fe918eb",
|
|
"type": "string"
|
|
},
|
|
"field_data": {
|
|
"description": "JSON array of form answers captured at submission time.",
|
|
"type": "string"
|
|
},
|
|
"timestamp": {
|
|
"description": "Date and time when the form was submitted/completed. Used for sorting and displaying form responses chronologically. Format is YYYY-MM-DD HH:MM:SS in UTC timezone.",
|
|
"type": "string",
|
|
"example": "2026-03-01 12:00:00"
|
|
},
|
|
"form_by_staff_uuid": {
|
|
"description": "UUID of the staff member who completed or submitted this form. Identifies which user filled out the form. Used for tracking form submission history and staff accountability.",
|
|
"format": "uuid",
|
|
"example": "123e4567-0230-4fe1-83c9-23f94429362b",
|
|
"type": "string"
|
|
},
|
|
"document_attachment_uuid": {
|
|
"description": "UUID of the document attachment generated from this form response. When a form is completed, it can generate a PDF document which is stored as an attachment. This field links to that generated document attachment.",
|
|
"format": "uuid",
|
|
"example": "123e4567-ff79-499a-8ef4-23f94a981a6b",
|
|
"type": "string"
|
|
},
|
|
"asset_uuid": {
|
|
"description": "UUID of the Asset this form response is related to. Used when the FormResponsepertains to a specific asset, such as equipment inspections, maintenance checklists, or asset condition reports.",
|
|
"format": "uuid",
|
|
"example": "123e4567-fc2c-4a3d-a278-23f942d7f62b",
|
|
"type": "string"
|
|
},
|
|
"uuid": {
|
|
"format": "uuid",
|
|
"description": "Unique identifier for this record",
|
|
"example": "123e4567-faa3-4649-8ea5-23f94011885b",
|
|
"type": "string"
|
|
},
|
|
"active": {
|
|
"enum": [
|
|
0,
|
|
1
|
|
],
|
|
"type": "integer",
|
|
"default": 1,
|
|
"description": "Record active/deleted flag. Valid values are [0,1]"
|
|
},
|
|
"edit_date": {
|
|
"example": "2026-03-01 12:00:00",
|
|
"readOnly": true,
|
|
"description": "Timestamp at which record was last modified"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-speakeasy-retries": {
|
|
"strategy": "backoff",
|
|
"backoff": {
|
|
"initialInterval": 500,
|
|
"maxInterval": 60000,
|
|
"maxElapsedTime": 3600000,
|
|
"exponent": 1.5
|
|
},
|
|
"statusCodes": [
|
|
"5XX",
|
|
"429"
|
|
],
|
|
"retryConnectionErrors": true
|
|
},
|
|
"tags": [
|
|
{
|
|
"name": "Form Responses",
|
|
"description": "Operations related to Form Responses"
|
|
}
|
|
]
|
|
}
|
|
```
|