Skip to main content
Method and path: POST {BASE_URL}/consultations Creates a new telemedicine consultation, either scheduled (with date/time) or immediate (no date; patient and provider can join shortly).

​
Request body (JSON)

FieldTypeRequiredDescription
providerobjectYesProvider details.
provider.namestringYesFull name (10–50 characters).
provider.documentTypestringYesCC, TI, CE, RC or PAS.
provider.documentNumberstringYesDocument number (8–20 characters).
provider.professionalTypestringYese.g. MedicoGeneral, MedicoEspecialista, Psicologo.
provider.medicalSpecialtyCodestringConditionalRequired only if professionalType is MedicoEspecialista. Do not send for MedicoGeneral, Psicologo, etc. See Medical specialties.
provider.phonestringYesPhone in international format (e.g. +573001234567).
provider.emailstringYesValid email.
provider.professionalLicensestringNoLicense number (optional).
patientobjectYesPatient details.
patient.documentTypestringYesCC, TI, CE, RC or PAS.
patient.documentNumberstringYes8–20 characters.
patient.namestringYesFull name.
patient.phonestringYesInternational format.
patient.emailstringYesValid email.
consultationTypestringYesConsultation type (e.g. ConsultaGeneral, ConsultaUrgencias). See Consultation types for the full catalog.
durationMinutesnumberYesDuration in minutes. Allowed: 10, 15, 20, 25, 30, 35, 40, 45, 50, 60. See Consultation durations.
scheduledAtstringNoDate and time in yyyy-MM-dd HH:mm format. If not sent, an immediate consultation is created. If sent, must be in the future with at least 15 minutes notice (organization timezone).

​
Catalog reference

For the fields consultationType, medicalSpecialtyCode, and durationMinutes, see the official tables:

Consultation types

Allowed values for consultationType (Resolución 2654 de 2019).

Medical specialties

Codes for medicalSpecialtyCode by professional type.

Consultation durations

Allowed values for durationMinutes (10 to 60 minutes).

​
Example – Scheduled consultation (specialist)

{
  "provider": {
    "name": "Dr. Juan Pérez",
    "documentType": "CC",
    "documentNumber": "1234567890",
    "professionalType": "MedicoEspecialista",
    "medicalSpecialtyCode": "CA003",
    "phone": "+573001234567",
    "email": "[email protected]",
    "professionalLicense": "12345"
  },
  "patient": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "name": "María García López",
    "phone": "+573009876543",
    "email": "[email protected]"
  },
  "consultationType": "ConsultaGeneral",
  "scheduledAt": "2024-12-15 14:30",
  "durationMinutes": 30
}

​
Example – Immediate consultation (general practitioner)

Without scheduledAt or medicalSpecialtyCode: 
{
  "provider": {
    "name": "Dr. Ana Martínez",
    "documentType": "CC",
    "documentNumber": "9876543210",
    "professionalType": "MedicoGeneral",
    "phone": "+573009876543",
    "email": "[email protected]"
  },
  "patient": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "name": "María García López",
    "phone": "+573009876543",
    "email": "[email protected]"
  },
  "consultationType": "ConsultaUrgencias",
  "durationMinutes": 20
}

​
Success response (200)

{
  "success": true,
  "data": {
    "consultationId": "550e8400-e29b-41d4-a716-446655440001",
    "accessPin": "123456",
    "participantAccess": {
      "patientUrl": "https://meet.kairoconnect.com/join/abc123def456?type=patient",
      "providerUrl": "https://meet.kairoconnect.com/join/abc123def456?type=provider"
    },
    "expiredAt": "2024-12-15 15:00",
    "provider": { "name": "Dr. Ana Martínez", "professionalType": "Médico General" },
    "patient": {
      "documentType": "CC",
      "documentNumber": "1234567890",
      "name": "María García López"
    },
    "scheduledAt": "2024-12-15 14:30",
    "durationMinutes": 30,
    "status": "Pending",
    "createdAt": "2024-12-15 10:30"
  },
  "metadata": {
    "requestId": "a1b2c3d4e5",
    "timestamp": "2024-12-15T10:30:00Z",
    "version": "v1"
  }
}
For Medico Especialista, data.provider will also include specialtyId, specialtyCode and specialtyName. For Medico General those fields are not sent.

​
Typical errors

  • 400 – Validation: format, duration not allowed, specialty required/not allowed.
  • 409 – Schedule conflict: provider or patient not available at that time.

​
See also