GoCanvas MCP by usefulapi

The user who owns the connected OAuth application: id, login, company id and name, default department and role. Use it to learn the default department id.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Forms (mobile form definitions) the connected user can see: id, name, status, version, department. Paged, 100 per page. Use gocanvas_get_form for a form's fields (entries).

{
  "type": "object",
  "properties": {
    "assigned": {
      "description": "true = only the user's assigned, active forms (only has an effect for users who can manage forms).",
      "type": "boolean"
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One form definition, including its screens and entries (field ids and labels). Use format 'flat' for the simplest list of fields (what you need to read submissions or create a dispatch), 'nested' (default) for the full structure, 'metadata' or 'minimal' for less.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The form id (from gocanvas_list_forms)."
    },
    "format": {
      "description": "Definition format (default nested).",
      "type": "string",
      "enum": [
        "nested",
        "flat",
        "minimal",
        "metadata"
      ]
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The report (PDF) definitions attached to a form: id, name, format, whether emailed by default. Paged.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The form id."
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Completed forms (submissions): id, form, number, created time, department, user, status. At least one of form_id, user_id or user_email is required (user_id and user_email cannot be combined). Default status is completed. Dates filter created_at. Paged, 100 per page. Use gocanvas_get_submission for the answers.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Form id; matches every version of the form."
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The user who created the submission."
    },
    "user_email": {
      "description": "Email (login) of the user who created the submission; not with user_id.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department id (default: the user's default department)."
    },
    "status": {
      "description": "Status filter (default completed). handed-off needs hand_off; custom needs custom_status.",
      "type": "string",
      "enum": [
        "all",
        "completed",
        "deleted",
        "in-progress",
        "overdue",
        "rejected",
        "handed-off",
        "assigned",
        "unassigned",
        "custom",
        "saved-to-cloud",
        "unfinished"
      ]
    },
    "hand_off": {
      "description": "Workflow handoff state name; required for status handed-off.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "custom_status": {
      "description": "Custom status label; required for status custom.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "start_date": {
      "description": "Created at or after (ISO-8601).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "end_date": {
      "description": "Created at or before (ISO-8601).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One submission with all its responses (entry id, label, type, value). Accepts the numeric submission id or the client GUID.

{
  "type": "object",
  "properties": {
    "submission_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Numeric submission id (e.g. 691911) or client GUID (e.g. 02ED5FB2-9C61-4F18-AB17-543547DF899B)."
    }
  },
  "required": [
    "submission_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The revision history of a submission (who changed it and when). Paged.

{
  "type": "object",
  "properties": {
    "submission_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Numeric submission id or client GUID."
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "required": [
    "submission_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Users of the company: id, name, email, enabled. Paged, 100 per page.

{
  "type": "object",
  "properties": {
    "enabled": {
      "description": "true = only enabled users, false = only disabled (default: both).",
      "type": "boolean"
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One user by id: name, login, contact data, default department and role.

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The user id (from gocanvas_list_users)."
    }
  },
  "required": [
    "user_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Departments of the company: id, name, description. The pseudo department -1 'All' is included.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The users in one department with their department role.

{
  "type": "object",
  "properties": {
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The department id (from gocanvas_list_departments)."
    }
  },
  "required": [
    "department_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Dispatches (jobs sent to field workers): id, form, assignee, status, schedule. At least one of user_id, department_id or form_id is required. Dates are ISO-8601. Paged.

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The user the dispatch is assigned to."
    },
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The department."
    },
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The form."
    },
    "project_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only dispatches assigned to this project."
    },
    "status": {
      "description": "unassigned, assigned, received or ready (ready ignores the date filters and is scoped to the connected user).",
      "type": "string",
      "enum": [
        "unassigned",
        "assigned",
        "received",
        "ready"
      ]
    },
    "start_date": {
      "description": "Created at or after.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "end_date": {
      "description": "Created at or before.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "scheduled_start_date": {
      "description": "Scheduled at or after.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "scheduled_end_date": {
      "description": "Scheduled end at or before.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$"
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One dispatch by id with its pre-filled responses, schedule and status.

{
  "type": "object",
  "properties": {
    "dispatch_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The dispatch id (from gocanvas_list_dispatches)."
    }
  },
  "required": [
    "dispatch_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Customers (contacts of the Project Management view): individuals or businesses, optionally tied to a site. Paged.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Projects of the Project Management view. Paged.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Sites (job locations) of the Project Management view. Paged.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Reference data (lookup tables used by forms): id, name, columns, version. Without department_id the user's default department is used.

{
  "type": "object",
  "properties": {
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department id."
    },
    "assigned": {
      "description": "true = only reference data used by forms assigned to the user.",
      "type": "boolean"
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One reference data set with its rows.

{
  "type": "object",
  "properties": {
    "reference_data_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The reference data id (from gocanvas_list_reference_data)."
    }
  },
  "required": [
    "reference_data_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

User groups: id, name, and the forms and users assigned. Paged.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Workflows (handoff chains between users) the connected user takes part in, with their handoff states and the count of tasks available to claim. Paged.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

GPS location events of field users (needs the tracker feature). start_date and end_date are required and may span at most 7 days. Omit user_id for all users of the company. Paged.

{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "Start of the window (ISO-8601; a bare date means 00:00:00)."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2})?(Z|[+-]\\d{2}:\\d{2})?)?$",
      "description": "End of the window (ISO-8601; a bare date means 23:59:59). At most 7 days after start_date."
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Limit to one user."
    },
    "use_created_at": {
      "description": "true = filter by upload time (created_at) instead of recorded_at.",
      "type": "boolean"
    },
    "page": {
      "description": "Page number, 1-based (default 1). Use next_page from the previous reply. 100 results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "required": [
    "start_date",
    "end_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: creates a dispatch, a job that appears on the assignee's mobile device (immediate_dispatch is sent at once, with a push notification when send_notification is true; scheduled_dispatch needs scheduled_at and scheduled_end). Responses pre-fill the assignee's form (entry ids from gocanvas_get_form). Without assignee_id the dispatch stays unassigned. Not idempotent: calling twice creates two dispatches. Media fields cannot be pre-filled.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The form to dispatch (from gocanvas_list_forms)."
    },
    "dispatch_type": {
      "type": "string",
      "enum": [
        "immediate_dispatch",
        "scheduled_dispatch"
      ],
      "description": "immediate_dispatch is sent now; scheduled_dispatch at scheduled_at."
    },
    "assignee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The user who gets the dispatch (from gocanvas_list_users); omit to leave it unassigned."
    },
    "name": {
      "description": "Short name shown on the dispatch calendar.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description": {
      "description": "Description shown on the assignee's device.",
      "type": "string",
      "maxLength": 2000
    },
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department; default is the user's default department."
    },
    "responses": {
      "description": "Pre-filled answers.",
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entry_id": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "The form entry id (from gocanvas_get_form)."
          },
          "value": {
            "type": "string",
            "maxLength": 5000,
            "description": "The value to pre-fill, as text."
          },
          "multi_key": {
            "description": "Only for looped forms: reference to the looped value (one key per loop row).",
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        },
        "required": [
          "entry_id",
          "value"
        ]
      }
    },
    "send_notification": {
      "description": "Immediate dispatches: send a push notification to the mobile app.",
      "type": "boolean"
    },
    "scheduled_at": {
      "description": "Scheduled dispatches: start, in the format MM/DD/YYYY h:mm:ss AM, e.g. 12/1/2024 8:00:00 AM.",
      "type": "string",
      "minLength": 6,
      "maxLength": 40
    },
    "scheduled_end": {
      "description": "Scheduled dispatches: end, same format.",
      "type": "string",
      "minLength": 6,
      "maxLength": 40
    },
    "reminder_interval": {
      "description": "Scheduled dispatches: minutes before the start to send a reminder.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    },
    "send_calendar_invite": {
      "description": "Scheduled dispatches: send a calendar invite.",
      "type": "boolean"
    }
  },
  "required": [
    "form_id",
    "dispatch_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: acknowledges a dispatch (status becomes received). Only works for a dispatch in the assigned state that is assigned to the connected user; repeating it is refused by GoCanvas.

{
  "type": "object",
  "properties": {
    "dispatch_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The dispatch id."
    }
  },
  "required": [
    "dispatch_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}