Jotform

Jotform

Jotform is an online form builder. The API provides full CRUD access to forms, submissions, questions, webhooks, reports, labels, and account settings.

Data Model

• User — account info (name, email, username), account type (BRONZE/SILVER/GOLD/ENTERPRISE), and avatar URL.
• Usage — current billing period stats: submission counts (total, SSL, mobile, payment), form count, API calls used, upload storage consumed, and AI usage (conversations, phone calls, agents).
• Settings — account preferences: time zone (e.g. 'America/New_York'), language (e.g. 'en-US'), region (US/EU), 2FA status, HIPAA compliance flag.
• History — activity log: form creation/modification/deletion, account logins, and other account events. Each entry has type, timestamp, IP, and username.
• Forms — form definitions identified by form_id (numeric string, visible in the builder URL). Each form has questions, properties, submissions, webhooks, and reports. Key fields: id, title, status (ENABLED/DISABLED/DELETED), created_at, updated_at, new (unread count), count (total submissions), url (live form URL).
• Questions — field definitions on a form, identified by qid (question ID, numeric string). Each has:
  • type — control type: control_textbox, control_textarea, control_dropdown, control_radio, control_checkbox, control_email, control_fullname, control_phone, control_address, control_datetime, control_number, control_fileupload, control_head (section header), control_scale, control_rating, control_spinner, control_matrix, control_signature.
  • text — the question label displayed to users.
  • required — 'Yes' or 'No'.
  • options — pipe-separated choices for dropdown/radio/checkbox (e.g. 'Red|Green|Blue').
  • Type-specific props: sublabels (compound field sub-labels), defaultValue, validation, maxsize (file upload).
• Submissions — respondent answers tied to a form. Each submission has id, form_id, created_at, status (ACTIVE/DELETED), ip, answers. The answers object is keyed by question ID; each answer has name, text (question label), type, and answer (the value). Compound fields (name, address) store subfields like first, last, addr_line1, city, state, postal, country.
• Reports — exportable views of submission data. Types: csv, excel, grid, table, rss. Each report has id, form_id, title, url, created_at, status, list_type.
• Webhooks — URLs that receive POST requests with submission data when a form is submitted. Keyed by numeric index (0, 1, 2...). Each webhook is a URL string.
• Labels — organizational tags for forms (replaced the deprecated folders API). Each label has id, name, color (hex), created_at, owner. Support nesting via sublabels. Use labels endpoints, not the deprecated folders API.
• Form Properties — form-level settings: title, status, activeRedirect (redirect after submit), thankurl (thank-you page URL), limitSubmission (max submissions), sendpostdata (yes/no), formWidth, labelWidth, styles, fonts.
• Form Files — files uploaded through file upload fields. Each file has name, URL, size, and the submission it belongs to.

Entity Relationships

• User → owns many Forms, Labels, Reports
• Form → has many Questions (keyed by qid)
• Form → has many Submissions (each contains answers keyed by qid)
• Form → has many Webhooks (keyed by index 0, 1, 2...)
• Form → has many Reports (CSV, Excel, etc.)
• Form → has Properties (title, limits, styling)
• Form → has uploaded Files
• Label → contains many Forms (many-to-many; a form can belong to multiple labels)

Key Patterns

• form_id is central: Most operations require a form_id. Get it from listing forms or from the form builder URL.
• Question IDs for submissions: To create/edit submissions, first get questions to find qid values, then submit answers keyed by qid.
• Compound field format: When submitting answers for compound fields, use qid_subfield format: name fields use qid_first, qid_last; address fields use qid_addr_line1, qid_city, qid_state, qid_postal, qid_country.
• Filtering: Pass JSON filter objects like {"status":"ACTIVE"} or {"created_at:gt":"2024-01-01"} on list endpoints.
• Pagination: Use offset + limit (max 1000) for paginated lists of forms, submissions.
• Webhook lifecycle: Create webhooks to receive real-time notifications, get webhooks to audit, delete by webhook index (not URL).
• Form properties: Control title, submission limits, thank-you page, redirect URL, styles via set form properties.
• Labels replace folders: The folders API is deprecated and returns an error. Use labels for organizing forms.

Common Workflows

1. Create a form: Create form with questions → optionally set properties (title, limits) → share the form URL
2. Collect and review data: List forms → get submissions for a form → filter by status → export via report
3. Modify a form: Get questions → add/edit/delete questions → update form properties
4. Set up integrations: Create webhooks on a form → submissions trigger POST to your URL
5. Organize forms: Create labels → add forms to labels → list label resources
6. Monitor account: Get usage stats → review history log → check settings