Create an Alert

Creates a new alert for an entity resolved by polymorphic identifier (entityId or entityReference) plus entityType.

POST/api/integration/alert

Request

cURL

curl -X POST "https://dev.integration.cl.sodtrack-shared.sodtrack.com/api/integration/alert" \
  -H "Authorization: Bearer $SODTRACK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "origin: <your-origin>" \
  -d '{
  "entityType": "lead",
  "entity": {
    "type": "entityId",
    "value": "503"
  },
  "name": "New - Lead Not Viewed",
  "createdComment": "New leads must be contacted within 4 business hours. Please visit your lead record and log a call with your customer to resolve this alert."
}'

Base URL: https://dev.integration.cl.sodtrack-shared.sodtrack.com · other environments

Headers

Name	Type	Description
`origin`	string	—

Request body

application/json

{
  "entityType": "lead",
  "entity": {
    "type": "entityId",
    "value": "503"
  },
  "name": "New - Lead Not Viewed",
  "createdComment": "New leads must be contacted within 4 business hours. Please visit your lead record and log a call with your customer to resolve this alert."
}

Responses

Create an Alert

{
  "id": 10,
  "uuid": "d73c51c5-3fbe-4d8e-8f24-2ecce2f8e8e1",
  "entityType": "booking",
  "entityId": 1,
  "name": "Technician unavailable",
  "status": "active",
  "creationUserType": "integration_api",
  "createdByUserId": null,
  "creationType": "manual",
  "resolveType": "manual",
  "metricKey": "capacity",
  "metricValue": "0",
  "createdComment": "Created from external monitoring",
  "reference": "EXT-ALERT-100",
  "resolvedComment": null,
  "resolvedByUserId": null,
  "resolvedDate": null,
  "createdDate": "2026-02-24T10:00:00.000Z",
  "updatedDate": "2026-02-24T10:00:00.000Z"
}

Error responses for this endpoint follow the shared error reference.

General Description

Creates a new alert for an entity resolved by polymorphic identifier (entityId or entityReference) plus entityType.

Field Definitions

Request Body: ExternalIntegrationCreateAlertRequestDTO

Field	Type	Required	Description
`entityType`	enum	Yes	Entity type where alert is created can be one of `booking`, `lead`, `project` or `budget`
`entity`	`ExternalIntegrationEntityIdentifierRequestDTO`	Yes	Entity identifier object.
`name`	string	Yes	Alert name.
`resolveType`	enum	No	Resolve behavior. Supported in this flow: `manual`, `sticky`.
`metricKey`	string	No	Optional metric key.
`metricValue`	string	No	Optional metric value.
`createdComment`	string	No	Optional creation comment.
`reference`	string	No	Optional external alert reference (must be unique).

`ExternalIntegrationEntityIdentifierRequestDTO`

Field	Type	Required	Description
`type`	enum	Yes	Identifier type: `entityId` or `entityReference`.
`value`	string	Yes	Entity ID value (when `entityId`) or reference value (when `entityReference`).

Success Response

Returns AlertDTO.

Field	Type	Description
`id`	number	Alert ID.
`uuid`	string	Alert UUID.
`entityType`	enum	Alert entity type.
`entityId`	number	Resolved entity ID.
`name`	string	Alert name.
`status`	enum	`active` or `resolved`.
`creationUserType`	enum	`integration_api` for this flow.
`createdByUserId`	number	null
`creationType`	enum	Creation mode.
`resolveType`	enum	Resolve type of alert.
`metricKey`	string	null
`metricValue`	string	null
`createdComment`	string	null
`reference`	string	null
`resolvedComment`	string	null
`resolvedByUserId`	number	null
`resolvedDate`	Date	null
`createdDate`	Date	Created timestamp.
`updatedDate`	Date	Updated timestamp.

Example Request

json

{
  "entityType": "booking",
  "entity": {
    "type": "entityReference",
    "value": "BKG-EXT-100"
  },
  "name": "Technician unavailable",
  "resolveType": "manual",
  "metricKey": "capacity",
  "metricValue": "0",
  "createdComment": "Created from external monitoring",
  "reference": "EXT-ALERT-100"
}

Example Response

http

HTTP/1.1 201 Created

json

{
  "id": 10,
  "uuid": "d73c51c5-3fbe-4d8e-8f24-2ecce2f8e8e1",
  "entityType": "booking",
  "entityId": 12345,
  "name": "Technician unavailable",
  "status": "active",
  "creationUserType": "integration_api",
  "createdByUserId": null,
  "creationType": "manual",
  "resolveType": "manual",
  "metricKey": "capacity",
  "metricValue": "0",
  "createdComment": "Created from external monitoring",
  "reference": "EXT-ALERT-100",
  "resolvedComment": null,
  "resolvedByUserId": null,
  "resolvedDate": null,
  "createdDate": "2026-02-24T10:00:00.000Z",
  "updatedDate": "2026-02-24T10:00:00.000Z"
}

Example Error Responses

json

{
  "statusCode": 400,
  "message": "INVALID_ENTITY_IDENTIFIER_TYPE",
  "error": "Bad Request"
}

json

{
  "statusCode": 400,
  "message": "BUDGET_REFERENCE_NOT_SUPPORTED",
  "error": "Bad Request"
}

json

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

Business Rules & Constraints

entity.type must be exactly entityId or entityReference; otherwise returns INVALID_ENTITY_IDENTIFIER_TYPE.
Entity resolution requires exactly one identifier value that maps to exactly one instance of the entity.
- If entity cannot be resolved: ENTITY_NOT_FOUND.
- If reference maps to multiple entities: MULTIPLE_ENTITIES_FOUND.
For entityType = budget, reference-based resolution is not supported yet BUDGET_REFERENCE_NOT_SUPPORTED.
reference, when provided, must be unique; duplicate returns ALERT_REFERENCE_ALREADY_EXISTS.