> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit a form > Submits a filled-in form for a template. Required fields (also in follow-ups that are shown) and sections' minAnswers are checked. With jobId the submission is added to the job's submitted forms. The form-submitted notification is sent as when a phone submits. Workers may call it for templates they can see and only as themselves. Answers 200. ## OpenAPI ````yaml v1/openapi.json POST /forms/submissions openapi: 3.1.0 info: title: Hellotracks REST API version: '1' description: >- Plain REST resources over HTTPS, for tools, automations and services. The ht command line is built on it. contact: email: api@hellotracks.com servers: - url: https://api.hellotracks.com/v1 security: - ApiKey: [] tags: - name: Sign-up and sign-in description: >- Create a company or get an API key by an emailed code, without a key; and check which account a key belongs to. - name: Company description: The company the API key belongs to, with its settings and teams. - name: Members description: 'The people in the company: admins, operators and workers.' - name: API keys description: 'The company''s API keys: list, create, revoke and delete.' - name: Jobs description: 'Jobs: work at a location on a date, assigned to a member.' - name: Places description: 'Places: customer sites and other saved locations with a check-in radius.' - name: Zones description: 'Zones: the company''s geofences.' - name: Routing description: Route optimization for one member's day. - name: ETA pages description: >- Live ETA pages (eta.page links) that show a job's recipient when the worker arrives. - name: Maps description: Rendered maps as GeoJSON, and public map share links. - name: Timesheets description: Clock-in and clock-out entries of members, with totals, and editing them. - name: Forms description: >- Form templates, submitted forms, attachments for file and image fields, and forms linked to places and jobs. - name: Alerts description: >- Alert rules (configs) that watch members, places and zones, and the alerts (instances) they raised. - name: Reports description: >- Reports: the newer reporting API (catalog, preview, run, saved) and the older one (types, generate, jobs, uploads, recurring). - name: Webhooks description: URLs Hellotracks calls when jobs, check-ins, clock-ins or alerts happen. paths: /forms/submissions: post: tags: - Forms summary: Submit a form description: >- Submits a filled-in form for a template. Required fields (also in follow-ups that are shown) and sections' minAnswers are checked. With jobId the submission is added to the job's submitted forms. The form-submitted notification is sent as when a phone submits. Workers may call it for templates they can see and only as themselves. Answers 200. operationId: createFormSubmission requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FormSubmissionCreate' example: templateId: 3f2b8c1e-0000-4000-8000-000000000001 values: Site clean: 'Yes' memberId: a1b2c3 jobId: '650000000000000000000001' location: lat: 37.7749 lng: -122.4194 responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' properties: data: type: object properties: submission: $ref: '#/components/schemas/FormSubmission' example: data: submission: id: '1761901234567' submissionId: 1761901234567 submissionUid: '1761901234567' templateId: 3f2b8c1e-0000-4000-8000-000000000001 title: Site check createdAt: 1761901234567 createdTs: 1761901234567 submittedBy: Driver 1 creatorUid: a1b2c3 jobId: '650000000000000000000001' placeId: d4e5f6 location: lat: 37.7749 lng: -122.4194 content: id: 3f2b8c1e-0000-4000-8000-000000000001 title: Site check description: '' timestamp: 1761901234000 content: - type: section name: Arrival options: [] value: '' required: false conditionals: [] - type: radio name: Site clean options: - 'Yes' - 'No' value: '' required: true conditionals: - equalsTo: 'No' content: - type: paragraph name: What was wrong options: [] value: '' required: true - type: image name: Photo options: [] value: '' required: false conditionals: [] answers: Arrival.Site clean: 'Yes' Arrival.Photo: '' completion: answered: 1 total: 2 error: null meta: path: /v1/forms/submissions method: POST '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: FormSubmissionCreate: type: object additionalProperties: false description: >- Send either values (answers by field name, filled into the template) or a complete content; not both. properties: templateId: type: string description: Required unless content.id names the template. values: type: object additionalProperties: true description: Field name (case-insensitive) to value. Unknown names are refused. content: $ref: '#/components/schemas/FormContent' memberId: type: string description: >- Submit for this member (admins); defaults to the caller. A worker may only submit as himself. jobId: type: string description: >- Job the submission belongs to; it is added to the job's submitted forms. placeId: type: string description: Place; defaults to the job's place. location: type: object properties: lat: type: number lng: type: number Envelope: type: object properties: data: description: The payload. error: type: 'null' meta: $ref: '#/components/schemas/Meta' FormSubmission: type: object properties: id: type: string description: Numeric submission id, as a string. submissionId: type: integer format: int64 submissionUid: type: string templateId: type: string title: type: string createdAt: type: integer format: int64 description: Milliseconds since the epoch. createdTs: type: integer format: int64 description: Milliseconds since the epoch. submittedBy: type: string description: Name of the member who submitted. creatorUid: type: string description: Member id who submitted. jobId: type: - string - 'null' placeId: type: - string - 'null' location: type: object properties: lat: type: number lng: type: number content: $ref: '#/components/schemas/FormContent' answers: type: object additionalProperties: true description: >- Answers by field name, as "Section.Field" inside a section; repeated names get " 2", " 3". completion: type: object properties: answered: type: integer total: type: integer FormContent: type: object properties: id: type: string description: The template id (set by the server). title: type: string description: type: string timestamp: type: integer format: int64 description: Milliseconds since the epoch. content: type: array items: $ref: '#/components/schemas/FormItem' Meta: type: object properties: path: type: string description: The request path, without /v1. example: /jobs method: type: string example: GET ErrorEnvelope: type: object properties: data: type: 'null' error: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/Meta' FormItem: type: object description: >- One field of a form. form_title, form_description, section and label are headers without a value. required: - type properties: type: type: string enum: - form_title - form_description - section - label - text - paragraph - checkbox - number - decimal - radio - dropdown - file - image - signature description: Case-insensitive on input. name: type: string description: >- Required for input fields; unique (case-insensitive) within a template. Also the question text. label: type: string description: Accepted on input but not stored. options: type: array items: type: string description: Choices; required for radio and dropdown. value: description: >- The answer (empty in a template). For file and image fields, the value from POST /forms/attachments. required: type: boolean default: false minAnswers: type: integer minimum: 0 description: 'Sections only: how many questions of the section must be answered.' index: type: integer description: Accepted on input but not stored. conditionals: type: array description: >- Follow-up fields shown when this field's value equals equalsTo (number, decimal, checkbox, radio, dropdown only). items: type: object additionalProperties: false properties: equalsTo: type: string content: type: array items: $ref: '#/components/schemas/FormItem' Error: type: object required: - code - message properties: code: type: string description: Stable error code for programs. enum: - invalid_request - invalid_format - invalid_data - invalid_api_key - unknown_user - authentication_failed - forbidden - not_found - already_exists - throttled - not_ready - clock_invalid - force_logout - internal_error - unknown_error message: type: string description: Why it failed, for people. responses: BadRequest: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: invalid_request message: date must be YYYY-MM-DD meta: path: /jobs method: GET Unauthorized: description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: invalid_api_key message: Invalid Hellotracks API key. meta: path: /jobs method: GET Forbidden: description: The key may not do this. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: forbidden message: No permission. meta: path: /jobs method: GET TooManyRequests: description: Too many requests; slow down. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: throttled message: Too many requests. meta: path: /jobs method: GET ServerError: description: Hellotracks failed; retry later. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: data: null error: code: internal_error message: Hellotracks API is temporarily unavailable. meta: path: /jobs method: GET securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: >- Your API key, from More → API & Integrations in the dashboard, or from ht signup / ht auth login. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.