Audit log API: query and manage the ServiciosYa audit trail

The ServiciosYa audit API surfaces two separate audit systems under a unified set of endpoints. The legacy system stores records in dbo.InsertAuditLog and is queried via the dbo.GetAuditLogs stored procedure; it tracks coarse entity-level changes as free-text old/new value strings. The PRO system writes structured events to dbo.AuditEvents with per-field change tracking in dbo.AuditChanges, rich metadata (module, action, severity, result, correlation ID, IP address), and visibility controls that allow SUPER_ADMIN to hide sensitive events from ADMIN_GENERAL users. When the PRO table is absent from the database, the PRO endpoints return empty results rather than errors, allowing zero-downtime migration. All audit endpoints are scoped to the caller’s CompanyID claim so that ADMIN_GENERAL users can only see records belonging to their own company. SUPER_ADMIN users can query across all companies.

Authentication

Endpoint	Required role
`POST /api/audit/logs`	`SUPER_ADMIN` or `ADMIN_GENERAL`
`POST /api/v1/audit/events/search`	`SUPER_ADMIN` or `ADMIN_GENERAL`
`GET /api/v1/audit/events/{id}`	`SUPER_ADMIN` or `ADMIN_GENERAL`
`POST /api/v1/audit/{id}/hide`	`SUPER_ADMIN` only
`POST /api/v1/audit/{id}/unhide`	`SUPER_ADMIN` only

POST /api/audit/logs — Query legacy audit log

Queries the legacy dbo.GetAuditLogs stored procedure and returns a paginated list of AuditLogDto records. Results are always filtered to the caller’s CompanyID, which is read from the JWT claims and cannot be overridden by the request body. Authentication: SUPER_ADMIN, ADMIN_GENERAL
Method: POST
Path: /api/audit/logs
Content-Type: application/json

Request body

userID

integer

Filter by the internal user ID that performed the action.

actionType

string

Filter by the action type string stored in the legacy log (e.g. "CREATE", "UPDATE").

entityName

string

Filter by the entity type name (e.g. "Service", "ServiceRequest").

entityID

integer (int64)

Filter by the specific entity primary key.

dateFrom

string (ISO 8601)

Inclusive start of the date range filter (local server time).

dateTo

string (ISO 8601)

Inclusive end of the date range filter.

searchValue

string

Free-text search applied across available text fields by the stored procedure.

pageNumber

integer

default:"1"

1-based page number. Values below 1 are treated as 1.

pageSize

integer

default:"50"

Records per page. Values below 1 or above 200 are clamped to 50.

Response — 200 OK

{
  "success": true,
  "data": {
    "totalRows": 340,
    "pageNumber": 1,
    "pageSize": 50,
    "data": [
      {
        "auditID": 1001,
        "userID": 42,
        "username": "jdoe@example.com",
        "companyName": "Empresa Demo",
        "actionType": "UPDATE",
        "entityName": "Service",
        "entityID": 77,
        "oldValues": "{\"name\":\"Old Name\"}",
        "newValues": "{\"name\":\"New Name\"}",
        "iPAddress": "192.168.1.10",
        "createdAt": "2026-04-30T09:15:00Z"
      }
    ]
  }
}

success

boolean

Always true for a successful response.

data.totalRows

integer

Total number of rows matching the filters (before pagination).

data.pageNumber

integer

The effective page number used for this response.

data.pageSize

integer

The effective page size used for this response.

data.data

array

Array of legacy audit log records.

data.data[].auditID

integer (int64)

Unique identifier of the legacy audit record.

data.data[].userID

integer

ID of the user who performed the action.

data.data[].username

string | null

Username looked up from dbo.[User], enriched server-side.

data.data[].companyName

string | null

Company name looked up from dbo.Company, enriched server-side.

data.data[].actionType

string

The action type string stored in the legacy log.

data.data[].entityName

string

The entity type that was affected.

data.data[].entityID

integer (int64)

Primary key of the affected entity.

data.data[].oldValues

string

JSON-serialised snapshot of the entity’s fields before the action.

data.data[].newValues

string

JSON-serialised snapshot of the entity’s fields after the action.

data.data[].iPAddress

string

IP address of the request that triggered the audit event.

data.data[].createdAt

string (ISO 8601)

Timestamp when the audit record was written.

Legacy audit records do not support hide/unhide, per-field change detail, severity levels, or correlation IDs. Those features are only available in the PRO audit system via /api/v1/audit/events.

POST /api/v1/audit/events/search — Search PRO audit events

Searches the dbo.AuditEvents table with a rich set of filters and returns paginated results. ADMIN_GENERAL callers automatically receive only events belonging to their company and only events where IsVisibleForAdmins = 1 (i.e. not hidden by a SUPER_ADMIN). SUPER_ADMIN callers can query across all companies and see all events regardless of visibility. Authentication: SUPER_ADMIN, ADMIN_GENERAL
Method: POST
Path: /api/v1/audit/events/search
Content-Type: application/json

Request body

dateFromUtc

string (ISO 8601)

Filter events at or after this UTC timestamp.

dateToUtc

string (ISO 8601)

Filter events at or before this UTC timestamp.

userId

integer

Filter by the user who performed the action.

companyId

integer

Filter by company ID. SUPER_ADMIN only — ignored for ADMIN_GENERAL (their company is always enforced).

username

string

Partial match against UserEmail (SQL LIKE '%value%').

companyName

string

Partial match against the company name from dbo.Company.

module

string

Exact match on the module name (e.g. "AUTH", "PAYMENTS"). See the Actions reference table below.

action

string

Exact match on the action name (e.g. "LOGIN", "CREATE_SERVICE").

result

string

Exact match on the result field (e.g. "Success", "Failure").

severity

string

Exact match on the severity field (e.g. "Info", "Warning", "Error", "Critical").

isVisibleForAdmins

boolean

SUPER_ADMIN only. Filter by visibility flag. Pass false to retrieve hidden events.

correlationId

string (UUID)

Filter by the HTTP request correlation ID to find all events from a single request.

pageNumber

integer

default:"1"

1-based page number.

pageSize

integer

default:"50"

Records per page. Maximum allowed value is 200.

Response — 200 OK

{
  "totalRows": 1204,
  "pageNumber": 1,
  "pageSize": 50,
  "data": [
    {
      "id": 9871,
      "timestampUtc": "2026-05-01T11:47:03Z",
      "userId": 42,
      "userEmail": "jdoe@example.com",
      "role": "ADMIN_GENERAL",
      "companyId": 7,
      "companyName": "Empresa Demo",
      "action": "VALIDATE_PAYMENT",
      "module": "PAYMENTS",
      "entityName": "Payment",
      "entityId": "4402",
      "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ipAddress": "192.168.1.10",
      "userAgent": "Mozilla/5.0 ...",
      "result": "Success",
      "severity": "Info",
      "message": "Pago validado correctamente.",
      "isVisibleForAdmins": true,
      "hiddenByUserId": null,
      "hiddenAtUtc": null
    }
  ]
}

totalRows

integer

Total matching records before pagination.

pageNumber

integer

Effective page number.

pageSize

integer

Effective page size.

data

array

Page of AuditEventDto records. See the AuditEvent fields reference below.

Example

curl -s https://api.serviciosya.com/api/v1/audit/events/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "module": "AUTH",
    "severity": "Warning",
    "dateFromUtc": "2026-05-01T00:00:00Z",
    "dateToUtc":   "2026-05-01T23:59:59Z",
    "pageNumber": 1,
    "pageSize": 25
  }' | jq '.totalRows'

GET /api/v1/audit/events/ — Get single audit event

Retrieves the full detail of a single PRO audit event, including all field-level changes recorded in dbo.AuditChanges. Access is restricted to the caller’s company for ADMIN_GENERAL. Returns 404 if the event does not exist, belongs to a different company, or is hidden from the caller’s role. Authentication: SUPER_ADMIN, ADMIN_GENERAL
Method: GET
Path: /api/v1/audit/events/{id}

Path parameters

integer (int64)

required

The unique ID of the audit event to retrieve.

Response — 200 OK

{
  "id": 9871,
  "timestampUtc": "2026-05-01T11:47:03Z",
  "userId": 42,
  "userEmail": "jdoe@example.com",
  "role": "ADMIN_GENERAL",
  "companyId": 7,
  "companyName": "Empresa Demo",
  "action": "UPDATE_SERVICE",
  "module": "SERVICES",
  "entityName": "Service",
  "entityId": "77",
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ipAddress": "192.168.1.10",
  "userAgent": "Mozilla/5.0 ...",
  "result": "Success",
  "severity": "Info",
  "message": "Servicio actualizado.",
  "isVisibleForAdmins": true,
  "hiddenByUserId": null,
  "hiddenAtUtc": null,
  "changes": [
    {
      "id": 501,
      "auditEventId": 9871,
      "fieldName": "Name",
      "oldValue": "Old Service Name",
      "newValue": "New Service Name"
    }
  ]
}

Response — 404 Not Found

Returned when the event does not exist, is outside the caller’s company scope, or (for ADMIN_GENERAL) has been hidden by a SUPER_ADMIN.

Example

curl -s https://api.serviciosya.com/api/v1/audit/events/9871 \
  -H "Authorization: Bearer <token>" | jq '.changes'

POST /api/v1/audit//hide — Hide an audit event

Marks an audit event as hidden by setting IsVisibleForAdmins = false, recording the acting user’s ID in HiddenByUserId and the timestamp in HiddenAtUtc. Hidden events remain fully visible to SUPER_ADMIN but are excluded from all results returned to ADMIN_GENERAL. The hide action itself is written to the audit log as a HIDE_AUDIT_EVENT event with Severity = "Warning". Authentication: SUPER_ADMIN only
Method: POST
Path: /api/v1/audit/{id}/hide

Path parameters

integer (int64)

required

The unique ID of the audit event to hide.

Response — 200 OK

{ "message": "Evento ocultado." }

Response — 404 Not Found

Returned when the event does not exist or the update affected zero rows.

POST /api/v1/audit//unhide — Restore a hidden event

Reverses a previous hide by setting IsVisibleForAdmins = true and clearing HiddenByUserId and HiddenAtUtc. The action is written to the audit log as an UNHIDE_AUDIT_EVENT event with Severity = "Info". After a successful unhide, ADMIN_GENERAL users will once again see the event in search results. Authentication: SUPER_ADMIN only
Method: POST
Path: /api/v1/audit/{id}/unhide

Path parameters

integer (int64)

required

The unique ID of the audit event to restore.

Response — 200 OK

{ "message": "Evento restaurado." }

Response — 404 Not Found

Returned when the event does not exist or the update affected zero rows.

AuditEvent fields reference

The following fields appear in both the search results (AuditEventDto) and the detail response (AuditEventDetailDto).

integer (int64)

Unique identifier of the audit event in dbo.AuditEvents.

timestampUtc

string (ISO 8601)

UTC timestamp when the event was written.

userId

integer | null

ID of the user who triggered the event. null for system-generated events.

userEmail

string | null

Email address of the acting user at the time of the event.

role

string | null

JWT role claim of the acting user (e.g. "ADMIN_GENERAL", "SUPER_ADMIN").

companyId

integer | null

Company the acting user belonged to.

companyName

string | null

Human-readable company name, joined from dbo.Company.

action

string

The action that was performed (e.g. "LOGIN", "CREATE_SERVICE"). See the actions table below.

module

string

Functional module that generated the event (e.g. "AUTH", "SERVICES").

entityName

string | null

The entity type affected (e.g. "Service", "Payment").

entityId

string | null

String representation of the entity’s primary key.

correlationId

string (UUID)

HTTP request correlation ID, shared by all audit events generated within the same request.

ipAddress

string | null

Client IP address of the originating request.

userAgent

string | null

User-Agent header from the originating request.

result

string

Outcome of the action. Typical values: "Success", "Failure".

severity

string

Severity level: "Info", "Warning", "Error", or "Critical".

message

string | null

Free-text description of the event, written by the application layer.

isVisibleForAdmins

boolean

true if the event is visible to ADMIN_GENERAL users. SUPER_ADMIN always sees all events regardless of this flag.

hiddenByUserId

integer | null

ID of the SUPER_ADMIN who hid this event, or null if not hidden.

hiddenAtUtc

string (ISO 8601) | null

UTC timestamp when the event was hidden, or null if not hidden.

changes

array

(Detail endpoint only.) List of AuditChangeDto records describing per-field mutations.

changes[].id

integer (int64)

Unique ID of the change record in dbo.AuditChanges.

changes[].auditEventId

integer (int64)

Foreign key back to dbo.AuditEvents.Id.

changes[].fieldName

string

Name of the model property that changed.

changes[].oldValue

string | null

String representation of the value before the change.

changes[].newValue

string | null

String representation of the value after the change.

Audit actions by module

The following table documents every action string that ServiciosYa writes to dbo.AuditEvents.

Module	Action	Severity (typical)	Description
`AUTH`	`LOGIN`	Info	Successful user authentication.
`AUTH`	`REGISTER_CUSTOMER`	Info	New customer portal account created.
`AUTH`	`REGISTER_INTERNAL`	Info	New internal/staff account created.
`AUTH`	`CHANGE_PASSWORD`	Warning	User password changed.
`AUTH`	`DELETE_PORTAL_USER`	Warning	Portal user account deleted.
`SERVICES`	`CREATE_SERVICE`	Info	New service catalogue entry created.
`SERVICES`	`UPDATE_SERVICE`	Info	Existing service updated.
`SERVICES`	`TOGGLE_SERVICE`	Info	Service enabled or disabled.
`SERVICES`	`DELETE_SERVICE`	Warning	Service catalogue entry deleted.
`SERVICE_REQUESTS`	`CREATE_SERVICE_REQUEST`	Info	New service request submitted.
`SERVICE_REQUESTS`	`UPDATE_REQUEST_STATUS`	Info	Service request status changed.
`SERVICE_REQUESTS`	`UPLOAD_ATTACHMENT`	Info	Attachment uploaded to a service request.
`SERVICE_REQUESTS`	`UPLOAD_INVOICE`	Info	Invoice uploaded to a service request.
`SERVICE_REQUESTS`	`UPLOAD_DELIVERY_ATTACHMENT`	Info	Delivery attachment uploaded.
`SERVICE_REQUESTS`	`RESOLVE_CANCELLATION_REMINDER`	Info	Cancellation reminder resolved.
`SERVICE_REQUESTS`	`DELETE_SERVICE_REQUEST`	Warning	Service request deleted.
`PAYMENTS`	`VALIDATE_PAYMENT`	Info	Payment proof validated and accepted.
`PAYMENTS`	`REJECT_PAYMENT`	Warning	Payment proof rejected.
`PAYMENTS`	`CONFIRM_REFUND`	Warning	Refund confirmed for a payment.
`UPLOADS`	`UPLOAD_PAYMENT_PROOF`	Info	Payment proof file uploaded.
`AUDIT`	`HIDE_AUDIT_EVENT`	Warning	A `SUPER_ADMIN` hid an audit event.
`AUDIT`	`UNHIDE_AUDIT_EVENT`	Info	A `SUPER_ADMIN` restored a hidden audit event.

Audit write behaviour

Audit events are written via IAuditEventService.TryWriteAsync. This method is fire-and-forget by design: it catches and swallows all exceptions so that an audit write failure never causes a user-facing operation to fail or return an error. If the dbo.AuditEvents table does not exist, writes silently no-op. Check application logs for [AuditEventService]-prefixed warning messages if events appear to be missing.

Authentication

Services

Service Requests

System

Audit log API: query and manage the ServiciosYa audit trail

Authentication

POST /api/audit/logs — Query legacy audit log

Request body

Response — 200 OK

POST /api/v1/audit/events/search — Search PRO audit events

Request body

Response — 200 OK

Example

GET /api/v1/audit/events/ — Get single audit event

Path parameters

Response — 200 OK

Response — 404 Not Found

Example

POST /api/v1/audit//hide — Hide an audit event

Path parameters

Response — 200 OK

Response — 404 Not Found

POST /api/v1/audit//unhide — Restore a hidden event

Path parameters

Response — 200 OK

Response — 404 Not Found

AuditEvent fields reference

Audit actions by module

Audit write behaviour

Build docs developers (and LLMs) love

Authentication

Services

Service Requests

System

Documentation Index

​Authentication

​POST /api/audit/logs — Query legacy audit log

​Request body

​Response — 200 OK

​POST /api/v1/audit/events/search — Search PRO audit events

​Request body

​Response — 200 OK

​Example

​GET /api/v1/audit/events/ — Get single audit event

​Path parameters

​Response — 200 OK

​Response — 404 Not Found

​Example

​POST /api/v1/audit//hide — Hide an audit event

​Path parameters

​Response — 200 OK

​Response — 404 Not Found

​POST /api/v1/audit//unhide — Restore a hidden event

​Path parameters

​Response — 200 OK

​Response — 404 Not Found

​AuditEvent fields reference

​Audit actions by module

​Audit write behaviour

Build docs developers (and LLMs) love

Authentication

POST /api/audit/logs — Query legacy audit log

Request body

Response — 200 OK

POST /api/v1/audit/events/search — Search PRO audit events

Request body

Response — 200 OK

Example

GET /api/v1/audit/events/ — Get single audit event

Path parameters

Response — 200 OK

Response — 404 Not Found

Example

POST /api/v1/audit//hide — Hide an audit event

Path parameters

Response — 200 OK

Response — 404 Not Found

POST /api/v1/audit//unhide — Restore a hidden event

Path parameters

Response — 200 OK

Response — 404 Not Found

AuditEvent fields reference

Audit actions by module

Audit write behaviour