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