CitoHRCitoHR
API Reference

Forms API

Create, distribute, and manage custom forms and surveys through the CitoHR API.

Get Forms

Retrieve forms with pagination and filtering. Requires ADMIN role.

GET /api/forms

Query parameters:

  • page - Page number (default: 1)
  • limit - Items per page (default: 10)
  • status - Filter by status: DRAFT, PUBLISHED, CLOSED (optional)
  • search - Search forms by title (optional)

Create Form

Create a new custom form. Requires ADMIN role.

POST /api/forms

Request body: 

{
  "title": "Employee Satisfaction Survey",
  "description": "Annual employee feedback survey",
  "isAnonymous": false,
  "requireAuthentication": true,
  "allowMultipleSubmissions": false,
  "maxSubmissions": 1,
  "openDate": "2024-01-15T00:00:00.000Z",
  "closeDate": "2024-02-15T00:00:00.000Z"
}

Get Form by ID

Retrieve a specific form by ID. Requires ADMIN role.

GET /api/forms/{id}

Update Form

Update an existing form. Requires ADMIN role.

PUT /api/forms/{id}

Delete Form

Delete a form. Requires ADMIN role.

DELETE /api/forms/{id}

Get Form Questions

Retrieve questions for a specific form.

GET /api/forms/{id}/questions

Submit Form Response

Submit a response to a form.

POST /api/forms/submit/{formId}

Request body: 

{
  "answers": [
    {
      "questionId": "question-id",
      "value": "Answer text"
    }
  ]
}

Get Form Responses

Retrieve responses for a form. Requires ADMIN role.

GET /api/forms/{id}/responses

Query parameters:

  • page - Page number (default: 1)
  • limit - Items per page (default: 10)

Get Form Analytics

Retrieve analytics and statistics for a form. Requires ADMIN role.

GET /api/forms/{id}/analytics

Distribute Form

Distribute a form to users. Requires ADMIN role.

POST /api/forms/{id}/distribute

Get Public Form

Retrieve a public form (does not require authentication).

GET /api/forms/public/{id}