CSAT API

API endpoints for the CSAT module. All endpoints require JWT authentication and are prefixed with /csat.

Authentication

All endpoints require a valid JWT token:

Authorization: Bearer <token>

Role-based access is enforced per endpoint (see the Auth column).

Endpoints

Method	Path	Description	Auth
GET	/csat	List ratings with filters and pagination	menu-csat
GET	/csat/{id}	Get full details for a single rating	menu-csat
GET	/csat/ticket/{ticketId}	Get rating details by ticket ID	menu-csat or company-request-view
POST	/csat/comments	Add admin follow-up comment	csat-add-comments
PUT	/csat/comments	Update admin follow-up comment	csat-update-comments
GET	/csat/agents/list	List available agents for filtering	menu-csat

GET /csat

Returns a paginated, filterable list of CSAT ratings for the DataTable component.

Query Parameters

Param	Type	Required	Description
start	number	No	Pagination offset (default: 0)
length	number	No	Items per page (default: 100)
sortBy	string	No	Sort column: reference, rating, companyId, ratingDate, source
sortType	string	No	Sort direction: ASC or DESC
report	boolean	No	If true, returns streaming chunked response for export
localeId	any	No	Locale filter (resolved by middleware)
companyId	string	No	Comma-separated company IDs
source	string	No	Comma-separated source types: ticket, carrier, shop
sourcePlatform	string	No	Comma-separated platforms: platform, whatsapp
rating	string	No	Filter by rating value
score	string	No	Comma-separated star scores: 1, 2, 3, 4, 5
startDate	string	No	Date range start (YYYY-MM-DD)
endDate	string	No	Date range end (YYYY-MM-DD)
agents	string	No	Comma-separated agent IDs
carrier	string	No	Comma-separated carrier names

Response (200)

{
  "data": [
    {
      "rating_id": 1234,
      "rating": 4,
      "comment": "Good service, fast delivery",
      "source_platform": "platform",
      "rating_date": "2026-04-10T14:30:00Z",
      "source": "ticket",
      "reference_id": 5678,
      "company_id": 100,
      "company_name": "Acme Corp",
      "country": "MX",
      "country_img": "https://s3.../mx.svg",
      "ticket_type": "overweight",
      "ticket_type_description": "Overweight",
      "ticketsStatusDescription": "Accepted",
      "ticketsStatusColor": "#28a745",
      "carrier": "FedEx",
      "carrier_name": "FedEx",
      "logo": "https://s3.../FedEx.svg",
      "follow_up_comments": null,
      "follow_up_created_by": null
    }
  ],
  "draw": 50,
  "recordsTotal": 1250,
  "recordsFiltered": 1250
}

Report Mode

When report=true, the response uses Transfer-Encoding: chunked streaming. The backend iterates through all matching ratings in batches (1000 per chunk) and writes each batch as a JSON array to the stream.

GET /csat/{id}

Returns full details for a single rating, including resolution agent and resolution time.

Path Parameters

Param	Type	Required	Description
id	number	Yes	Rating ID

Response (200)

{
  "details": {
    "rating_id": 1234,
    "rating": 4,
    "comment": "Good service",
    "rating_date": "2026-04-10T14:30:00Z",
    "source": "ticket",
    "reference_id": 5678,
    "company_id": 100,
    "company_name": "Acme Corp",
    "country": "MX",
    "ticket_type": "overweight",
    "ticket_type_description": "Overweight",
    "user_name": "John Customer",
    "admin_name": "Admin User",
    "admin_solution_name": "Support Agent",
    "diff_hours": 12,
    "latest_comment_date": "2026-04-10T14:00:00Z",
    "follow_up_comments": "Issue resolved successfully",
    "follow_up_created_at": "2026-04-11T10:00:00Z",
    "follow_up_created_by": 42
  }
}

GET /csat/ticket/{ticketId}

Returns CSAT rating details for a specific ticket. Used by the inline CsatSurveyCard component in the ticket chat view.

Path Parameters

Param	Type	Required	Description
ticketId	number	Yes	Ticket ID

Response (200)

Same structure as GET /csat/{id}, but looks up by ticket_id instead of rating.id. Returns { details: null } if no rating exists for the ticket.

Permission Note

This endpoint accepts either menu-csat or company-request-view permission. This means any admin who can view tickets can also see their CSAT data, without needing explicit CSAT module access.

POST /csat/comments

Adds an admin follow-up comment to a rating.

Request

{
  "ratingId": 1234,
  "comments": "We have addressed this issue and improved our process."
}

Response (200)

{
  "success": true
}

PUT /csat/comments

Updates an existing admin follow-up comment. Uses the same payload as POST.

Request

{
  "ratingId": 1234,
  "comments": "Updated: Follow-up complete, customer contacted."
}

Response (200)

{
  "success": true
}

GET /csat/agents/list

Returns a list of active administrators for use as filter options in the CSAT table.

Response (200)

{
  "list": [
    { "id": 1, "value": 1, "label": "Agent One", "text": "Agent One" },
    { "id": 2, "value": 2, "label": "Agent Two", "text": "Agent Two" }
  ]
}

Common Error Responses

All errors follow the Boom format:

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Descriptive error message"
}

Status	When
400	Validation failed (Joi schema)
401	Missing or invalid JWT
403	Insufficient permissions
409	Business logic error (query failure, invalid data)
422	Malformed request parameters