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
}

PUT

api

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.

Show Event Object Schema

texto

string

required

Event description/text (minimum 1 character)

tipo_notificacion

string

Notification type (e.g., “Inicial”, “Seguimiento”)

fecha_inicio

string

Event start date (ISO format: YYYY-MM-DD)

fecha_fin

string

Event end date (ISO format: YYYY-MM-DD)

gravedad

string

Event severity. Common values:

“Grave”
“No grave”
“Potencialmente grave”

causalidad

string

Causality assessment. Common values:

“Definitiva” - Certain/definite relationship
“Probable” - Probable relationship
“Posible” - Possible relationship
“Improbable” - Unlikely relationship
“Condicional” - Conditional
“No clasificable” - Unassessable

desenlace

string

Event outcome. Common values:

“Recuperado” - Recovered
“En recuperación” - Recovering
“Recuperado con secuelas” - Recovered with sequelae
“No recuperado” - Not recovered
“Muerte” - Death
“Desconocido” - Unknown

solo_ram_grave

string

Whether serious only due to adverse reaction. Values: “Si”, “No”, or null

texto_correo

string

Extended text from email or correspondence

doc_fuente_url

string

URL to source document or attachment

meddra_llt_code

string

MedDRA Lowest Level Term (LLT) code (e.g., “10037868”)

meddra_llt_term

string

MedDRA LLT term text (e.g., “Rash eritematoso”)

meddra_pt_code

string

MedDRA Preferred Term (PT) code (e.g., “10037844”)

meddra_pt_term

string

MedDRA PT term text (e.g., “Rash”)

meddra_pt_manual

string

Manually entered PT term if auto-coding is not used

is_from_narrative

boolean

default:"true"

Whether the event was extracted from the narrative description (vs. manually added)

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:

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

Delete existing events: All current events for the case are deleted
Validate new events: Each event in the array is validated
Insert new events: Valid events are inserted in order
Commit transaction: All changes are committed atomically
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"
}

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

Use Cases

Narrative Extraction Workflow

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

Manual Event Entry

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

Event Severity by Event (Not Case-Level)

VIGIA supports individual severity assessment per event:

Each event has its own gravedad field
Update individual events via PUT /icsr/{id}/eventos/{evento_id}
Case-level gravedad field on ICSR model represents overall severity

Causality Assessment Evolution

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

Best Practices

When Replacing Events

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

MedDRA Coding

Use standard codes when available: Prefer coded terms over free text
Include both LLT and PT: Provide complete hierarchy
Store code and term: Always pair code with the term text
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

Update ICSR Case

ICSR Followup Communications

​Endpoints

​List Events for a Case

​Replace All Events

​Update Single Event

​Update MedDRA Coding Only

​Bulk Event Retrieval

​Path Parameters

​Request Body (Replace All Events)

​Request Body (Update Single Event)

​Response

​Bulk Retrieval Response

​Example Requests

​List Events

​Add Multiple Events

​Update Event Severity and Causality

​Update MedDRA Coding

​Clear All Events

​Behavior

​Replace All Events Workflow

​Field Normalization

​MedDRA Coding

​Event Ordering

​Validation

​Error Responses

​400 Bad Request

​404 Not Found

​Use Cases

​Narrative Extraction Workflow

​Manual Event Entry

​Event Severity by Event (Not Case-Level)

​Causality Assessment Evolution

​Best Practices

​When Replacing Events

​MedDRA Coding

​Performance

​Related Endpoints

Endpoints

List Events for a Case

Replace All Events

Update Single Event

Update MedDRA Coding Only

Bulk Event Retrieval

Path Parameters

Request Body (Replace All Events)

Request Body (Update Single Event)

Response

Bulk Retrieval Response

Example Requests

List Events

Add Multiple Events

Update Event Severity and Causality

Update MedDRA Coding

Clear All Events

Behavior

Replace All Events Workflow

Field Normalization

MedDRA Coding

Event Ordering

Validation

Error Responses

400 Bad Request

404 Not Found

Use Cases

Narrative Extraction Workflow

Manual Event Entry

Event Severity by Event (Not Case-Level)

Causality Assessment Evolution

Best Practices

When Replacing Events

MedDRA Coding

Performance

Related Endpoints