API de edad y género de Botim

Comprueba el registro en Botim por número de teléfono y devuelve edad y género estimados por IA junto con el estado de registro de cada número enviado. Facilita la segmentación basada en perfiles. La tarea utiliza el flujo de trabajo estándar de procesamiento por lotes asíncrono.

Parámetros del producto

Parámetro	Valor
Tipo de tarea	botim_gender
Tipo de entrada	Teléfono en formato E.164
Mínimo de entradas válidas	500

estimated_amount se calcula con la tarifa de la cuenta y es el importe de referencia para la tarea.

Formato de entrada

Sube un archivo .txt o .csv con un teléfono por línea. Se recomienda el formato E.164.

+14155552671
+442071838750

Crear una tarea

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./numbers.txt"' \
--form 'task_type="botim_gender"'

La API devuelve un ID de tarea. Guárdalo para consultar el estado.

Respuesta de carga

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 500,
  "estimated_amount": {
    "amount": "0.350000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Consultar el estado

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Consulta hasta que status sea exported. pending y processing no indican finalización.

Respuesta en proceso

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 500,
  "success": 250,
  "failure": 0
}

Respuesta exportada

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 500,
  "success": 500,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "0.350000",
    "currency": "USD"
  }
}

Campos de resultado

Campo	Descripción	Ejemplo
number / Number	Teléfono de entrada. CSV usa number; XLSX usa Number.	+14155552671
activated	Indica si se detectó una cuenta para el número.	yes / no
gender	Género detectado para una cuenta Botim registrada.	Male / Female / Unknown
age	Edad o rango de edad detectado para una cuenta Botim registrada.	25-34

Las filas sin cuenta devuelven activated=no; los campos de perfil quedan vacíos si no hay datos.

Procesamiento del archivo

Descarga el paquete desde result_url solo después de la exportación y conserva los nombres de columna.

Campos de respuesta

Campo	Descripción
created_at	Hora de creación.
updated_at	Última actualización.
task_id	Identificador único.
status	pending, processing, exported o failed.
total	Total de entradas válidas.
success	Valores procesados correctamente.
failure	Valores con error.
result_url	URL de descarga tras exportar.
actual_amount	Importe final, si está disponible.
estimated_amount	Importe estimado al crear la tarea.

Códigos de estado

Estado	Descripción
200	Solicitud correcta.
202	Tarea creada y cargo estimado aplicado.
400	Archivo no válido, tipo no compatible o entradas insuficientes.
401	API Key ausente o no válida.
402	Saldo insuficiente.
403	Producto no disponible para su cuenta (descontinuado o solo para clientes en lista blanca); contacte con soporte.
404	Tarea no encontrada.
413	Archivo demasiado grande.
500	Error interno; inténtalo más tarde.
503	Producto temporalmente no disponible (pausado por mantenimiento); no se realiza ningún cargo, inténtelo más tarde.

Notas operativas

• La tarea es asíncrona; consulta con el ID devuelto.
• Solo los teléfonos válidos y normalizados cuentan para el mínimo.
• Las tareas fallidas se reembolsan automáticamente según la facturación.