Endpoints — API de Nomyt

Base URL: https://api.nomyt.co/v1

Todos los endpoints requieren autenticacion mediante token Bearer. Consulta la para obtener tu token.

Vacantes

Listar vacantes

http

GET /vacancies

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 25, max: 100)
`status`	string	`draft`, `published`, `paused`, `in_process`, `closed`, `archived`
`department`	string	Filtrar por departamento
`modality`	string	`on_site`, `remote`, `hybrid`
`contract_type`	string	`full_time`, `part_time`, `project`, `internship`, `temporary`
`location_country`	string	Codigo de pais ISO 3166 (ej. `PA`, `CO`, `MX`)
`search`	string	Busqueda por titulo o descripcion
`created_from`	date	Fecha de creacion desde (ISO 8601)
`created_to`	date	Fecha de creacion hasta (ISO 8601)

Scope requerido: vacancies:read

Ejemplo:

bash

curl -X GET "https://api.nomyt.co/v1/vacancies?status=published&location_country=PA&per_page=10" \
  -H "Authorization: Bearer {token}"

Respuesta:

json

{
  "data": [
    {
      "id": "vac_abc123",
      "title": "Desarrollador Full Stack",
      "slug": "desarrollador-full-stack-abc123",
      "department": "Tecnologia",
      "location": {
        "country": "Panama",
        "city": "Ciudad de Panama"
      },
      "modality": "hybrid",
      "contract_type": "full_time",
      "level": "senior",
      "salary_range": {
        "min": 2500,
        "max": 4000,
        "currency": "USD",
        "period": "monthly",
        "visible": true
      },
      "status": "published",
      "applications_count": 42,
      "views_count": 850,
      "published_at": "2026-03-01T10:00:00Z",
      "closes_at": "2026-04-01T23:59:59Z",
      "created_at": "2026-03-01T09:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 8,
    "total_pages": 1
  }
}

Obtener vacante

http

GET /vacancies/{vacancy_id}

Scope requerido: vacancies:read

Respuesta:

json

{
  "data": {
    "id": "vac_abc123",
    "title": "Desarrollador Full Stack",
    "slug": "desarrollador-full-stack-abc123",
    "department": "Tecnologia",
    "description": "Buscamos un desarrollador Full Stack con experiencia...",
    "responsibilities": [
      "Desarrollar y mantener aplicaciones web",
      "Participar en revisiones de codigo",
      "Colaborar con el equipo de diseno UX"
    ],
    "requirements": {
      "mandatory": [
        "3+ anos de experiencia en desarrollo web",
        "Dominio de React y Node.js"
      ],
      "desirable": [
        "Experiencia con AWS o GCP",
        "Conocimiento de Docker y Kubernetes"
      ]
    },
    "benefits": [
      "Horario flexible",
      "Seguro medico",
      "Capacitacion continua"
    ],
    "skills": ["React", "Node.js", "TypeScript", "PostgreSQL"],
    "location": {
      "country": "Panama",
      "city": "Ciudad de Panama"
    },
    "modality": "hybrid",
    "contract_type": "full_time",
    "level": "senior",
    "min_experience_years": 3,
    "salary_range": {
      "min": 2500,
      "max": 4000,
      "currency": "USD",
      "period": "monthly",
      "visible": true
    },
    "openings": 1,
    "visibility": "public",
    "status": "published",
    "applications_count": 42,
    "views_count": 850,
    "published_at": "2026-03-01T10:00:00Z",
    "closes_at": "2026-04-01T23:59:59Z",
    "created_at": "2026-03-01T09:30:00Z",
    "updated_at": "2026-03-05T14:20:00Z"
  }
}

Crear vacante

http

POST /vacancies

Scope requerido: vacancies:write

json

{
  "title": "Disenador UX/UI",
  "department": "Diseno",
  "description": "Buscamos un disenador UX/UI con experiencia en productos digitales.",
  "location": {
    "country": "PA",
    "city": "Ciudad de Panama"
  },
  "modality": "hybrid",
  "contract_type": "full_time",
  "level": "mid",
  "min_experience_years": 2,
  "salary_range": {
    "min": 1800,
    "max": 2800,
    "currency": "USD",
    "period": "monthly",
    "visible": true
  },
  "requirements": {
    "mandatory": [
      "2+ anos de experiencia en diseno UX/UI",
      "Dominio de Figma"
    ],
    "desirable": [
      "Experiencia con design systems",
      "Conocimiento basico de HTML/CSS"
    ]
  },
  "skills": ["Figma", "UX Research", "Design Systems", "Prototyping"],
  "benefits": ["Horario flexible", "Seguro medico"],
  "visibility": "public",
  "status": "draft"
}

Respuesta (201 Created):

json

{
  "data": {
    "id": "vac_def456",
    "title": "Disenador UX/UI",
    "slug": "disenador-ux-ui-def456",
    "status": "draft",
    "created_at": "2026-03-11T10:00:00Z"
  }
}

Actualizar vacante

http

PATCH /vacancies/{vacancy_id}

Scope requerido: vacancies:write

json

{
  "salary_range": {
    "min": 2000,
    "max": 3000,
    "currency": "USD",
    "period": "monthly",
    "visible": true
  },
  "status": "published"
}

Cambiar estado de vacante

http

POST /vacancies/{vacancy_id}/status

json

{
  "status": "paused",
  "reason": "Evaluando candidatos actuales antes de recibir nuevas aplicaciones."
}

Eliminar vacante

http

DELETE /vacancies/{vacancy_id}

Scope requerido: vacancies:write

Atencion

Solo se pueden eliminar vacantes en estado draft. Las vacantes publicadas deben cerrarse y archivarse primero. Las vacantes con candidatos asociados no pueden eliminarse; usa el estado archived en su lugar.

Candidatos

Listar candidatos de una vacante

http

GET /vacancies/{vacancy_id}/candidates

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 25, max: 100)
`stage`	string	`new`, `reviewing`, `shortlisted`, `interview`, `offer`, `hired`, `rejected`
`skills`	string	Lista de habilidades separadas por coma
`min_experience`	integer	Anos minimos de experiencia
`location`	string	Pais o ciudad del candidato
`sort_by`	string	`applied_at`, `name`, `experience`, `match_score`
`sort_order`	string	`asc`, `desc`

Scope requerido: candidates:read

Respuesta:

json

{
  "data": [
    {
      "id": "cand_xyz789",
      "name": "Maria Garcia",
      "email": "maria@ejemplo.com",
      "phone": "+507 6789-1234",
      "location": {
        "country": "Panama",
        "city": "Ciudad de Panama"
      },
      "experience_years": 5,
      "skills": ["React", "Node.js", "TypeScript"],
      "stage": "shortlisted",
      "match_score": 85,
      "applied_at": "2026-03-05T14:30:00Z",
      "profile_url": "https://nomyt.co/p/maria-garcia"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 42,
    "total_pages": 2
  }
}

Obtener perfil de candidato

http

GET /candidates/{candidate_id}

Scope requerido: candidates:read

Respuesta:

json

{
  "data": {
    "id": "cand_xyz789",
    "name": "Maria Garcia",
    "email": "maria@ejemplo.com",
    "phone": "+507 6789-1234",
    "location": {
      "country": "Panama",
      "city": "Ciudad de Panama"
    },
    "availability": "immediate",
    "preferred_modality": "hybrid",
    "salary_expectation": {
      "min": 2500,
      "currency": "USD",
      "period": "monthly"
    },
    "summary": "Ingeniera de software con 5 anos de experiencia...",
    "experience": [
      {
        "company": "Tech Solutions Panama",
        "title": "Desarrolladora Senior",
        "period": "2023-01 - present",
        "description": "Lider tecnica de equipo de 4 desarrolladores."
      }
    ],
    "education": [
      {
        "institution": "Universidad Tecnologica de Panama",
        "degree": "Ingenieria en Sistemas Computacionales",
        "year": 2020
      }
    ],
    "skills": {
      "technical": ["React", "Node.js", "TypeScript", "PostgreSQL"],
      "soft": ["Liderazgo", "Comunicacion"]
    },
    "languages": [
      { "language": "Espanol", "level": "Native" },
      { "language": "Ingles", "level": "Advanced (C1)" }
    ],
    "documents": {
      "cv_url": "https://api.nomyt.co/v1/candidates/cand_xyz789/cv",
      "portfolio_url": "https://mariagarcia.dev",
      "linkedin_url": "https://linkedin.com/in/mariagarcia"
    },
    "tags": ["talento_top", "bilingue"],
    "applications": [
      {
        "vacancy_id": "vac_abc123",
        "vacancy_title": "Desarrollador Full Stack",
        "stage": "shortlisted",
        "applied_at": "2026-03-05T14:30:00Z"
      }
    ],
    "created_at": "2026-03-05T14:30:00Z"
  }
}

Actualizar etapa de candidato

http

POST /vacancies/{vacancy_id}/candidates/{candidate_id}/stage

Scope requerido: candidates:write

json

{
  "stage": "interview",
  "notes": "Perfil excelente. Agendar entrevista tecnica.",
  "notify_candidate": true
}

Respuesta:

json

{
  "data": {
    "candidate_id": "cand_xyz789",
    "vacancy_id": "vac_abc123",
    "previous_stage": "shortlisted",
    "new_stage": "interview",
    "changed_at": "2026-03-11T10:00:00Z",
    "changed_by": "Ana Rodriguez",
    "notification_sent": true
  }
}

Agregar nota a candidato

http

POST /candidates/{candidate_id}/notes

Scope requerido: candidates:write

json

{
  "content": "Excelente candidata. Considerar para Tech Lead cuando se abra la posicion.",
  "visibility": "team"
}

Buscar en base de datos de candidatos

http

GET /candidates/search

Parametros de consulta:

Parametro	Tipo	Descripcion
`q`	string	Busqueda por texto libre (nombre, habilidades, experiencia)
`skills`	string	Habilidades separadas por coma
`location`	string	Pais o ciudad
`min_experience`	integer	Anos minimos de experiencia
`availability`	string	`immediate`, `2_weeks`, `1_month`, `negotiable`
`tags`	string	Etiquetas separadas por coma

Scope requerido: candidates:read

bash

curl -X GET "https://api.nomyt.co/v1/candidates/search?skills=React,Node.js&location=PA&min_experience=3" \
  -H "Authorization: Bearer {token}"

Importar candidatos

http

POST /candidates/import

Scope requerido: candidates:write

bash

curl -X POST https://api.nomyt.co/v1/candidates/import \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@candidatos.csv" \
  -F "source=manual_import" \
  -F "tags=importacion_marzo"

Respuesta:

json

{
  "data": {
    "import_id": "imp_001",
    "status": "processing",
    "total_rows": 150,
    "processed": 0,
    "created": 0,
    "duplicates": 0,
    "errors": 0,
    "started_at": "2026-03-11T10:00:00Z"
  }
}

Procesamiento asincrono

La importacion de candidatos se procesa de forma asincrona. Usa el endpoint GET /candidates/import/{import_id} para consultar el estado y los resultados de la importacion.

Entrevistas

Agendar entrevista

http

POST /interviews

Scope requerido: interviews:manage

json

{
  "vacancy_id": "vac_abc123",
  "candidate_id": "cand_xyz789",
  "type": "video_nomyt",
  "scheduled_at": "2026-03-20T10:00:00-05:00",
  "duration_minutes": 45,
  "timezone": "America/Panama",
  "interviewers": [
    {
      "name": "Ana Rodriguez",
      "email": "ana@miempresa.com",
      "role": "technical_lead",
      "required": true
    },
    {
      "name": "Carlos Mendez",
      "email": "carlos@miempresa.com",
      "role": "hr_manager",
      "required": false
    }
  ],
  "candidate_preparation": "La entrevista durara 45 minutos. Incluye una seccion tecnica.",
  "internal_notes": "Evaluar experiencia con React y liderazgo de equipo."
}

Respuesta (201 Created):

json

{
  "data": {
    "id": "int_ghi789",
    "vacancy_id": "vac_abc123",
    "candidate_id": "cand_xyz789",
    "type": "video_nomyt",
    "status": "scheduled",
    "scheduled_at": "2026-03-20T10:00:00-05:00",
    "duration_minutes": 45,
    "video_room_url": "https://nomyt.co/room/int_ghi789",
    "interviewers": [
      {
        "name": "Ana Rodriguez",
        "email": "ana@miempresa.com",
        "status": "pending"
      }
    ],
    "candidate_notified": true,
    "created_at": "2026-03-11T10:00:00Z"
  }
}

Listar entrevistas

http

GET /interviews

Parametros de consulta:

Parametro	Tipo	Descripcion
`page`	integer	Numero de pagina (default: 1)
`per_page`	integer	Resultados por pagina (default: 25, max: 100)
`status`	string	`scheduled`, `confirmed`, `in_progress`, `completed`, `cancelled`
`type`	string	`video_nomyt`, `on_site`, `phone`, `external_video`
`vacancy_id`	string	Filtrar por vacante
`interviewer_email`	string	Filtrar por entrevistador
`from`	date	Fecha desde (ISO 8601)
`to`	date	Fecha hasta (ISO 8601)

Scope requerido: interviews:manage

Obtener entrevista

http

GET /interviews/{interview_id}

Scope requerido: interviews:manage

Reagendar entrevista

http

PATCH /interviews/{interview_id}

Scope requerido: interviews:manage

json

{
  "scheduled_at": "2026-03-22T14:00:00-05:00",
  "duration_minutes": 60,
  "reason": "Conflicto de agenda del entrevistador."
}

Cancelar entrevista

http

POST /interviews/{interview_id}/cancel

Scope requerido: interviews:manage

json

{
  "reason": "candidate_requested",
  "notify_participants": true,
  "notes": "El candidato solicito cancelar por motivos personales."
}

Atencion

Al cancelar una entrevista, se notifica automaticamente a todos los participantes si notify_participants es true. La etapa del candidato en la vacante no cambia automaticamente; debes actualizarla manualmente si es necesario.

Registrar evaluacion

http

POST /interviews/{interview_id}/evaluation

Scope requerido: interviews:manage

json

{
  "interviewer_email": "ana@miempresa.com",
  "overall_score": 4,
  "criteria": [
    {
      "name": "Habilidades tecnicas",
      "weight": 30,
      "score": 5,
      "comment": "Excelente dominio de React y Node.js."
    },
    {
      "name": "Experiencia relevante",
      "weight": 25,
      "score": 4,
      "comment": "5 anos de experiencia solida."
    },
    {
      "name": "Comunicacion",
      "weight": 15,
      "score": 4,
      "comment": "Clara y articulada."
    },
    {
      "name": "Resolucion de problemas",
      "weight": 15,
      "score": 4,
      "comment": "Enfoque estructurado."
    },
    {
      "name": "Fit cultural",
      "weight": 15,
      "score": 3,
      "comment": "Prefiere trabajo remoto, evaluar flexibilidad."
    }
  ],
  "recommendation": "advance",
  "notes": "Candidata fuerte. Recomendar segunda entrevista con CTO."
}

Respuesta (201 Created):

json

{
  "data": {
    "id": "eval_001",
    "interview_id": "int_ghi789",
    "interviewer": "Ana Rodriguez",
    "overall_score": 4,
    "weighted_score": 4.15,
    "recommendation": "advance",
    "created_at": "2026-03-20T11:00:00Z"
  }
}

Obtener evaluaciones de una entrevista

http

GET /interviews/{interview_id}/evaluations

Scope requerido: interviews:manage

Analiticas

Resumen general

http

GET /analytics/summary

Parametros de consulta:

Parametro	Tipo	Descripcion
`from`	date	Fecha de inicio (ISO 8601)
`to`	date	Fecha de fin (ISO 8601)
`granularity`	string	`day`, `week`, `month`

Scope requerido: vacancies:read

Respuesta:

json

{
  "data": {
    "period": {
      "from": "2026-03-01",
      "to": "2026-03-11"
    },
    "vacancies": {
      "active": 12,
      "total_published": 18,
      "total_views": 15400,
      "total_applications": 342
    },
    "candidates": {
      "new_applications": 342,
      "in_process": 85,
      "hired": 5,
      "average_time_to_hire_days": 18
    },
    "interviews": {
      "scheduled": 45,
      "completed": 38,
      "attendance_rate": 84.4,
      "average_score": 3.7
    },
    "conversion_funnel": {
      "views_to_applications": 2.22,
      "applications_to_shortlisted": 35.1,
      "shortlisted_to_interview": 62.5,
      "interview_to_offer": 28.9,
      "offer_to_hired": 71.4
    }
  }
}

Analiticas por vacante

http

GET /analytics/vacancies/{vacancy_id}

Scope requerido: vacancies:read

Respuesta:

json

{
  "data": {
    "vacancy_id": "vac_abc123",
    "title": "Desarrollador Full Stack",
    "metrics": {
      "views": 850,
      "applications": 42,
      "conversion_rate": 4.94,
      "time_to_first_application": "1h 30m",
      "candidates_by_stage": {
        "new": 8,
        "reviewing": 12,
        "shortlisted": 10,
        "interview": 7,
        "offer": 3,
        "hired": 2
      },
      "sources": {
        "portal_search": 22,
        "direct_link": 10,
        "social_media": 6,
        "referral": 4
      },
      "top_skills": [
        { "skill": "React", "count": 38 },
        { "skill": "Node.js", "count": 35 },
        { "skill": "TypeScript", "count": 28 }
      ]
    }
  }
}

Analiticas de reclutamiento

http

GET /analytics/recruitment

Parametros de consulta:

Parametro	Tipo	Descripcion
`from`	date	Fecha de inicio
`to`	date	Fecha de fin
`department`	string	Filtrar por departamento

Scope requerido: vacancies:read candidates:read

Respuesta:

json

{
  "data": {
    "period": {
      "from": "2026-01-01",
      "to": "2026-03-11"
    },
    "kpis": {
      "time_to_hire_avg_days": 22,
      "cost_per_hire_avg_usd": 150,
      "offer_acceptance_rate": 78.5,
      "quality_of_hire_score": 4.1,
      "candidate_satisfaction": 4.3
    },
    "trends": {
      "applications_by_month": [
        { "month": "2026-01", "count": 280 },
        { "month": "2026-02", "count": 315 },
        { "month": "2026-03", "count": 342 }
      ],
      "hires_by_month": [
        { "month": "2026-01", "count": 3 },
        { "month": "2026-02", "count": 4 },
        { "month": "2026-03", "count": 5 }
      ]
    }
  }
}

Codigos de respuesta

Codigo	Descripcion
`200`	Solicitud exitosa
`201`	Recurso creado exitosamente
`204`	Recurso eliminado exitosamente
`400`	Solicitud mal formada o parametros invalidos
`401`	No autenticado — token ausente o expirado
`403`	Sin permisos suficientes — scope inadecuado
`404`	Recurso no encontrado
`409`	Conflicto (ej. slug de vacante duplicado)
`422`	Error de validacion (ej. campos requeridos faltantes)
`429`	Limite de tasa excedido
`500`	Error interno del servidor

Estructura de error estandar

Todos los errores siguen la misma estructura:

json

{
  "error": "validation_error",
  "message": "El campo 'title' es requerido para crear una vacante.",
  "details": [
    {
      "field": "title",
      "code": "required",
      "message": "Este campo es obligatorio."
    }
  ]
}

Webhooks

Configura webhooks para recibir eventos en tiempo real cuando cambian los estados de vacantes, candidatos o entrevistas. Ve a Ajustes > Webhooks o usa PUT /webhooks para configurarlos programaticamente.

Eventos disponibles: vacancy.published, vacancy.closed, candidate.applied, candidate.stage_changed, interview.scheduled, interview.completed, interview.evaluation_submitted.

Endpoints — API de Nomyt ​

Vacantes ​

Listar vacantes ​

Obtener vacante ​

Crear vacante ​

Actualizar vacante ​

Cambiar estado de vacante ​

Eliminar vacante ​

Candidatos ​

Listar candidatos de una vacante ​

Obtener perfil de candidato ​

Actualizar etapa de candidato ​

Agregar nota a candidato ​

Buscar en base de datos de candidatos ​

Importar candidatos ​

Entrevistas ​

Agendar entrevista ​

Listar entrevistas ​

Obtener entrevista ​

Reagendar entrevista ​

Cancelar entrevista ​

Registrar evaluacion ​

Obtener evaluaciones de una entrevista ​

Analiticas ​

Resumen general ​

Analiticas por vacante ​

Analiticas de reclutamiento ​

Codigos de respuesta ​

Estructura de error estandar ​

Endpoints — API de Nomyt

Vacantes

Listar vacantes

Obtener vacante

Crear vacante

Actualizar vacante

Cambiar estado de vacante

Eliminar vacante

Candidatos

Listar candidatos de una vacante

Obtener perfil de candidato

Actualizar etapa de candidato

Agregar nota a candidato

Buscar en base de datos de candidatos

Importar candidatos

Entrevistas

Agendar entrevista

Listar entrevistas

Obtener entrevista

Reagendar entrevista

Cancelar entrevista

Registrar evaluacion

Obtener evaluaciones de una entrevista

Analiticas

Resumen general

Analiticas por vacante

Analiticas de reclutamiento

Codigos de respuesta

Estructura de error estandar