Skip to main content
PUT
/
api
/
v1
/
icsr
/
{icsr_id}
/
eventos
Manage Adverse Events
curl --request PUT \
  --url https://api.example.com/api/v1/icsr/{icsr_id}/eventos \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventos": [
    {
      "texto": "<string>",
      "tipo_notificacion": "<string>",
      "fecha_inicio": "<string>",
      "fecha_fin": "<string>",
      "gravedad": "<string>",
      "causalidad": "<string>",
      "desenlace": "<string>",
      "solo_ram_grave": "<string>",
      "texto_correo": "<string>",
      "doc_fuente_url": "<string>",
      "meddra_llt_code": "<string>",
      "meddra_llt_term": "<string>",
      "meddra_pt_code": "<string>",
      "meddra_pt_term": "<string>",
      "meddra_pt_manual": "<string>",
      "is_from_narrative": true
    }
  ],
  "gravedad": "<string>",
  "causalidad": "<string>",
  "desenlace": "<string>",
  "solo_ram_grave": "<string>",
  "texto_correo": "<string>",
  "doc_fuente_url": "<string>",
  "meddra_llt_code": "<string>",
  "meddra_llt_term": "<string>",
  "meddra_pt_code": "<string>",
  "meddra_pt_term": "<string>",
  "meddra_pt_manual": "<string>"
}
'
{
  "id": 123,
  "icsr_id": 123,
  "texto": "<string>",
  "tipo_notificacion": "<string>",
  "fecha_inicio": "<string>",
  "fecha_fin": "<string>",
  "gravedad": "<string>",
  "causalidad": "<string>",
  "desenlace": "<string>",
  "solo_ram_grave": "<string>",
  "texto_correo": "<string>",
  "doc_fuente_url": "<string>",
  "meddra_llt_code": "<string>",
  "meddra_llt_term": "<string>",
  "meddra_pt_code": "<string>",
  "meddra_pt_term": "<string>",
  "meddra_pt_manual": "<string>",
  "is_from_narrative": true
}

​
Endpoints

​
List Events for a Case

GET /api/v1/icsr/{icsr_id}/eventos
Returns all adverse events associated with a specific ICSR case. Authentication: Requires permission icsr:read

​
Replace All Events

PUT /api/v1/icsr/{icsr_id}/eventos
Replaces all adverse events for a case. This is the primary endpoint for updating events. Authentication: Requires permission icsr:update

​
Update Single Event

PUT /api/v1/icsr/{icsr_id}/eventos/{evento_id}
Updates a single adverse event (e.g., to change severity, causality, or outcome). Authentication: Requires permission icsr:update

​
Update MedDRA Coding Only

PUT /api/v1/icsr/{icsr_id}/meddra
Alias endpoint specifically for updating MedDRA coding. Behaves identically to the main eventos endpoint. Authentication: Requires permission icsr:update

​
Bulk Event Retrieval

GET /api/v1/icsr/eventos?ids=1&ids=2&ids=3
GET /api/v1/icsr/_bulk/eventos?ids=1,2,3
Retrieve events for multiple ICSR cases in a single request. Authentication: Requires permission icsr:read

​
Path Parameters

​
icsr_id
integer
required
The unique identifier of the ICSR case
​
evento_id
integer
required
The unique identifier of the specific adverse event (for single event updates)

​
Request Body (Replace All Events)

​
eventos
array
required
Array of event objects. Sending an empty array will delete all events.

​
Request Body (Update Single Event)

​
gravedad
string
Update event severity
​
causalidad
string
Update causality assessment
​
desenlace
string
Update event outcome
​
solo_ram_grave
string
Update serious-only-due-to-AE flag
​
texto_correo
string
Update extended text
​
doc_fuente_url
string
Update source document URL
​
meddra_llt_code
string
Update LLT code
​
meddra_llt_term
string
Update LLT term
​
meddra_pt_code
string
Update PT code
​
meddra_pt_term
string
Update PT term
​
meddra_pt_manual
string
Update manual PT term
Only include fields you want to update. Fields not included will retain their current values.

​
Response

Returns an array of event objects:
​
id
integer
Unique event identifier
​
icsr_id
integer
Parent ICSR case ID
​
texto
string
Event description
​
tipo_notificacion
string
Notification type
​
fecha_inicio
string
Event start date
​
fecha_fin
string
Event end date
​
gravedad
string
Event severity
​
causalidad
string
Causality assessment
​
desenlace
string
Event outcome
​
solo_ram_grave
string
Serious-only-due-to-AE indicator
​
texto_correo
string
Extended text from correspondence
​
doc_fuente_url
string
Source document URL
​
meddra_llt_code
string
MedDRA LLT code
​
meddra_llt_term
string
MedDRA LLT term
​
meddra_pt_code
string
MedDRA PT code
​
meddra_pt_term
string
MedDRA PT term
​
meddra_pt_manual
string
Manual PT term
​
is_from_narrative
boolean
Whether extracted from narrative

​
Bulk Retrieval Response

When using the bulk endpoints (GET /api/v1/icsr/eventos?ids=...), the response is an object keyed by ICSR ID: 
{
  "1234": [
    {
      "id": 5001,
      "icsr_id": 1234,
      "texto": "Rash eritematoso",
      "gravedad": "No grave",
      "causalidad": "Probable"
    }
  ],
  "1235": [
    {
      "id": 5002,
      "icsr_id": 1235,
      "texto": "Náuseas",
      "gravedad": "No grave",
      "causalidad": "Posible"
    },
    {
      "id": 5003,
      "icsr_id": 1235,
      "texto": "Vómitos",
      "gravedad": "No grave",
      "causalidad": "Posible"
    }
  ]
}

​
Example Requests

​
List Events

GET /api/v1/icsr/1234/eventos
Response: 
[
  {
    "id": 5001,
    "icsr_id": 1234,
    "texto": "Rash eritematoso generalizado",
    "tipo_notificacion": "Inicial",
    "fecha_inicio": "2024-01-15",
    "fecha_fin": "2024-01-18",
    "gravedad": "No grave",
    "causalidad": "Probable",
    "desenlace": "Recuperado",
    "solo_ram_grave": null,
    "meddra_pt_code": "10037844",
    "meddra_pt_term": "Rash",
    "meddra_llt_code": "10037868",
    "meddra_llt_term": "Rash eritematoso",
    "is_from_narrative": true
  }
]

​
Add Multiple Events

PUT /api/v1/icsr/1234/eventos

{
  "eventos": [
    {
      "texto": "Rash eritematoso generalizado",
      "tipo_notificacion": "Inicial",
      "fecha_inicio": "2024-01-15",
      "fecha_fin": "2024-01-18",
      "gravedad": "No grave",
      "causalidad": "Probable",
      "desenlace": "Recuperado",
      "meddra_pt_code": "10037844",
      "meddra_pt_term": "Rash",
      "meddra_llt_code": "10037868",
      "meddra_llt_term": "Rash eritematoso",
      "is_from_narrative": true
    },
    {
      "texto": "Prurito intenso",
      "tipo_notificacion": "Inicial",
      "fecha_inicio": "2024-01-15",
      "fecha_fin": "2024-01-17",
      "gravedad": "No grave",
      "causalidad": "Probable",
      "desenlace": "Recuperado",
      "meddra_pt_code": "10037087",
      "meddra_pt_term": "Prurito",
      "is_from_narrative": true
    }
  ]
}

​
Update Event Severity and Causality

PUT /api/v1/icsr/1234/eventos/5001

{
  "gravedad": "Grave",
  "causalidad": "Definitiva",
  "solo_ram_grave": "Si"
}

​
Update MedDRA Coding

PUT /api/v1/icsr/1234/meddra

{
  "eventos": [
    {
      "texto": "Rash eritematoso generalizado",
      "meddra_llt_code": "10037868",
      "meddra_llt_term": "Rash eritematoso",
      "meddra_pt_code": "10037844",
      "meddra_pt_term": "Rash",
      "is_from_narrative": true
    }
  ]
}

​
Clear All Events

PUT /api/v1/icsr/1234/eventos

{
  "eventos": []
}

​
Behavior

​
Replace All Events Workflow

  1. Delete existing events: All current events for the case are deleted
  2. Validate new events: Each event in the array is validated
  3. Insert new events: Valid events are inserted in order
  4. Commit transaction: All changes are committed atomically
  5. Return updated list: The complete list of events is returned with assigned IDs

​
Field Normalization

String fields are automatically trimmed:
  • Empty strings after trimming become null
  • Whitespace-only values become null
  • This applies to all text fields including MedDRA terms

​
MedDRA Coding

MedDRA codes follow a hierarchical structure:
  • LLT (Lowest Level Term): Most specific term (e.g., “Rash eritematoso”)
  • PT (Preferred Term): Standardized grouping term (e.g., “Rash”)
Both auto-coded and manually entered terms are supported:
  • Use meddra_llt_code and meddra_pt_code for coded terms
  • Use meddra_pt_manual for free-text terms when coding is not available

​
Event Ordering

Events are ordered by their id in ascending order (insertion order). To reorder events, you must replace the entire array.

​
Validation

The API validates:
  • ICSR case exists
  • User has update permissions
  • texto field is required and non-empty
  • Date formats are valid ISO-8601
  • Field lengths don’t exceed database limits (max 255 chars for most fields)
  • MedDRA codes are strings (no format validation)

​
Error Responses

​
400 Bad Request

{
  "detail": [
    {
      "loc": ["body", "eventos", 0, "texto"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
404 Not Found

{
  "detail": "ICSR no encontrado"
}
or 
{
  "detail": "Evento no encontrado para este ICSR"
}

​
Use Cases

​
Narrative Extraction Workflow

  1. Parse the case narrative (e.g., using NLP)
  2. Extract individual adverse events
  3. Send all events via PUT /icsr/{id}/eventos
  4. Mark each event with is_from_narrative: true

​
Manual Event Entry

  1. User enters event details in a form
  2. Include severity, causality, outcome from dropdowns
  3. Add MedDRA coding if available
  4. Send as a single-event array
  5. Mark with is_from_narrative: false

​
Event Severity by Event (Not Case-Level)

VIGIA supports individual severity assessment per event:
  1. Each event has its own gravedad field
  2. Update individual events via PUT /icsr/{id}/eventos/{evento_id}
  3. Case-level gravedad field on ICSR model represents overall severity

​
Causality Assessment Evolution

  1. Initial submission: causalidad: "Posible"
  2. After investigation: Update to "Probable"
  3. After expert review: Update to "Definitiva"
  4. Use single-event update endpoint to modify just causality

​
Best Practices

​
When Replacing Events

  1. Always GET first: Retrieve current events before making changes
  2. Preserve existing events: Include all events you want to keep
  3. Add new events: Append to the array
  4. Remove unwanted events: Exclude from the array
  5. Send complete array: Never send a partial list unless intentionally deleting events

​
MedDRA Coding

  1. Use standard codes when available: Prefer coded terms over free text
  2. Include both LLT and PT: Provide complete hierarchy
  3. Store code and term: Always pair code with the term text
  4. Manual fallback: Use meddra_pt_manual when coding is unavailable

​
Performance

  • Batch event updates in a single request rather than multiple individual updates
  • For MedDRA-only updates, use the /meddra endpoint (same behavior, semantic clarity)
  • Bulk retrieval is more efficient than individual GET requests for multiple cases
  • Create Case - Create ICSR (events are usually added after case creation)
  • Update Case - Update case-level severity and outcome
  • List Cases - List cases with their events

Build docs developers (and LLMs) love

Get started for freeTalk to us