Skip to main content

​
Endpoint

POST /api/medicos

​
Authentication

This endpoint requires authentication with an admin role. Include a valid JWT token in the Authorization header.
Authorization: Bearer <token>

​
Description

Creates a new doctor record by associating an existing person with a specialty. The person must exist in the system and cannot already be registered as a doctor or user.

​
Request Body

​
persona_id
integer
required
ID of the person to register as a doctor. The person must exist and not already be a doctor or user.
​
especialidad_id
integer
required
ID of the medical specialty to assign to the doctor
​
email
string
required
Professional email address for the doctor. Must be unique.
​
colegiatura
string
Professional license or medical registration number

​
Response

Returns the newly created doctor object.

​
Response Fields

​
id
integer
Unique identifier for the newly created doctor
​
persona_id
integer
ID of the associated person
​
especialidad_id
integer
ID of the assigned specialty
​
email
string
Doctor’s professional email address
​
colegiatura
string
Professional license number (null if not provided)
​
activo
boolean
Active status (defaults to true for new doctors)

​
Example Request

curl -X POST "https://api.example.com/api/medicos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_id": 5,
    "especialidad_id": 2,
    "email": "[email protected]",
    "colegiatura": "MED-12345"
  }'

​
Example Response

{
  "id": 3,
  "persona_id": 5,
  "especialidad_id": 2,
  "email": "[email protected]",
  "colegiatura": "MED-12345",
  "activo": true
}

​
Error Responses

​
400 Bad Request
Missing required fields
{
  "message": "persona_id, especialidad_id y email son obligatorios"
}
Person has a user role
{
  "message": "La persona tiene un rol de usuario y no puede ser médico"
}
Invalid specialty ID
{
  "message": "Especialidad no válida"
}
​
401 Unauthorized
Missing or invalid authentication token
{
  "message": "Token no proporcionado"
}
​
403 Forbidden
User does not have admin role
{
  "message": "Acceso denegado"
}
​
404 Not Found
Person does not exist
{
  "message": "Persona no existe"
}
​
409 Conflict
Person is already registered as a doctor
{
  "message": "La persona ya está registrada como médico"
}
Email or person is duplicated
{
  "message": "Email o persona duplicada"
}
​
500 Internal Server Error
Server error while creating doctor
{
  "message": "Error al crear médico"
}

​
Business Rules

Important validation rules:
  • The person must exist in the personas table
  • The person cannot already have a user account (usuario role)
  • The person cannot already be registered as a doctor
  • The email must be unique across all doctors
  • The specialty must exist in the especialidades table

Build docs developers (and LLMs) love

Get started for freeTalk to us