Create Incident

Purpose

Creates a new incident in Sodtrack and associates it with a booking, a lead, or a work order.

The target entity is identified by entityType (booking, lead, or work_order) and by entity (using entityId or entityReference). The incident requires a description and an incident reason (by ID; reference is not yet supported). You can optionally set the reporter, creator, and accountable users, an external reference, and dynamic forms data.

Incidents are used to track issues, complaints, or follow-ups. Only booking, lead and work_order are supported for creation.

Field Definitions

📋 Request body

📝 Dynamic forms

🔗 Entity identifier

📌 Incident reason identifier

👤 User information (reporter, creator, accountable)

Example Request (booking by reference)

{
  "entityType": "booking",
  "entity": {
    "type": "entityReference",
    "value": "BOOK-REF-001"
  },
  "description": "Técnico no llevó el equipo correcto.",
  "incidentReason": {
    "type": "reasonId",
    "value": "2"
  },
  "reporterUser": {
    "type": "userEmail",
    "value": "soporte@example.com"
  },
  "creatorUser": {
    "type": "userReference",
    "value": "USER-EXT-001"
  },
  "reference": "INC-EXT-2025-001"
}

Example Request (lead by reference)

{
  "entityType": "lead",
  "entity": {
    "type": "entityReference",
    "value": "LEAD-EXT-342"
  },
  "description": "Queja por demora en agendamiento.",
  "incidentReason": {
    "type": "reasonId",
    "value": "2"
  },
  "reporterUser": {
    "type": "userEmail",
    "value": "soporte@example.com"
  },
  "creatorUser": {
    "type": "userEmail",
    "value": "soporte@example.com"
  },
  "reference": "INC-LEAD-001",
  "dynamicForms": [
    {
      "formReference": "incident_creation_form",
      "values": [
        {
          "fieldReference": "incident_creation_form_field_1",
          "value": "Yes"
        }
      ]
    }
  ]
}

Example Request (work order by reference)

{
  "entityType": "work_order",
  "entity": {
    "type": "entityReference",
    "value": "WO-EXT-778"
  },
  "description": "Repuesto incorrecto enviado en la orden de trabajo.",
  "incidentReason": {
    "type": "reasonId",
    "value": "3"
  },
  "reporterUser": {
    "type": "userEmail",
    "value": "soporte@example.com"
  },
  "reference": "INC-WO-001"
}

Example Request (minimal)

{
  "entityType": "booking",
  "entity": {
    "type": "entityId",
    "value": "12345"
  },
  "description": "Incidente reportado por integración.",
  "incidentReason": {
    "type": "reasonId",
    "value": "1"
  }
}

Response Example

{
  "id": 100,
  "entityType": "booking",
  "entityId": 12345,
  "bookingId": 12345,
  "incidentStatus": {
    "id": 1,
    "name": "Open",
    "description": "Incident is open",
    "isFinalStatus": false,
    "isInitialStatus": true,
    "bookingStatusUpdate": ""
  },
  "reference": "INC-EXT-001"
}

When entityType is "work_order", the response carries the work order id in entityId and omits bookingId:

{
  "id": 101,
  "entityType": "work_order",
  "entityId": 778,
  "incidentStatus": {
    "id": 1,
    "name": "Open",
    "description": "Incident is open",
    "isFinalStatus": false,
    "isInitialStatus": true,
    "bookingStatusUpdate": ""
  },
  "reference": "INC-WO-001"
}

Response Fields

*Error Responses *

Business Rules & Constraints

Entity identification

• entityType and entity are required. Supported values for creation are booking, lead, and work_order. The enum may also include project; it is not supported for this endpoint and returns ENTITY_TYPE_NOT_SUPPORTED.
• entity.value must be non-empty (after trim). Otherwise the request fails with ENTITY_IDENTIFIER_REQUIRED.

Booking resolution

When entityType is booking:

• entity.type = entityId: value is the booking ID. The booking must exist; otherwise the API returns BOOKING_NOT_FOUND_FOR_ID.
• entity.type = entityReference: value is the booking reference. No match returns BOOKING_NOT_FOUND_FOR_REFERENCE; multiple matches return MULTIPLE_BOOKINGS_FOUND_FOR_REFERENCE.

Lead resolution

When entityType is lead:

• entity.type = entityId: value is the lead ID. The lead must exist; otherwise the API returns LEAD_NOT_FOUND_FOR_ID.
• entity.type = entityReference: value is the lead reference. The lead must exist; otherwise the API returns LEAD_NOT_FOUND_FOR_REFERENCE.

Work order resolution

When entityType is work_order:

• entity.type = entityId: value is the work order ID and must be numeric; a non-numeric value returns INVALID_WORK_ORDER_ID. The work order must exist; otherwise the API returns WORK_ORDER_NOT_FOUND_FOR_ID.
• entity.type = entityReference: value is the work order external reference. No match returns WORK_ORDER_NOT_FOUND_FOR_REFERENCE.

User resolution

• reporterUser and creatorUser are optional and can be sent as null. When either is provided with a non-null value, it must resolve to an existing user by the given identifier (userId, userEmail, or userReference). If the user cannot be resolved, the request fails with INVALID_REPORTER_USER or INVALID_CREATOR_USER respectively.
• accountableUser is optional. When provided, it is resolved if possible; if it cannot be resolved, the incident may be created without an accountable user (behavior may depend on configuration).
• Invalid user identifier type returns INVALID_USER_TYPE.

Incident reason

• incidentReason is required. Only type = reasonId is supported; reasonReference is not yet supported and returns INCIDENT_REASON_REFERENCE_NOT_SUPPORTED.
• value must be a valid numeric reason ID that exists in Sodtrack. Invalid number returns INVALID_INCIDENT_REASON_ID; non-existent reason returns INCIDENT_REASON_NOT_FOUND.

Data and format

• Dynamic form data (when provided) is validated and stored for the incident according to the incident creation flow configuration.
• All timestamps in responses follow ISO 8601 format (UTC) where applicable.