Genera una clave de API para desarrolladores
En la app ve a Settings → API y crea una Developer API key. Define sus alcances (scopes) y su nivel de acceso (solo lectura o lectura-escritura) al mínimo que necesite la integración. El secreto se muestra una sola vez: cópialo de inmediato en un gestor de secretos; la app solo guarda una forma redactada.
Revoca y regenera en la misma página si alguna vez se filtra una clave.
Verifica la identidad con whoami
La URL base es
https://api.app.firstsales.io. La autenticación es un token Bearer. Empieza siempre confirmando que la clave resuelve a la organización y el espacio de trabajo que esperas:GET /api/v1/whoami:curl https://api.app.firstsales.io/api/v1/whoami \ -H "Authorization: Bearer $FIRSTSALES_API_KEY"Encuentra los IDs de tu organización y espacio de trabajo
Cada recurso está delimitado a una organización y un espacio de trabajo, así que la mayoría de las rutas se ven como
/api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Lístalos:# Organizations you can access curl https://api.app.firstsales.io/api/v1/organizations \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" # Workspaces inside an org curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces \ -H "Authorization: Bearer $FIRSTSALES_API_KEY"Crea un contacto (de forma idempotente)
Haz un POST de un contacto dentro de un espacio de trabajo. Envía un encabezado Idempotency-Key para que una solicitud reintentada nunca cree un duplicado: seguro de repetir tras un fallo de red.
curl -X POST \ https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: jane-acme-2026-01" \ -d '{ "email": "[email protected]", "first_name": "Jane", "company_name": "Acme" }'Lee las analíticas de una campaña
Extrae métricas de embudo y de interacción de una campaña para sincronizar los resultados en tu propio reporting: sin hacer scraping del dashboard:
curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns/CAMPAIGN_ID/analytics \ -H "Authorization: Bearer $FIRSTSALES_API_KEY"Lee las respuestas desde la bandeja de entrada
Lista los hilos de la bandeja de entrada para extraer envíos, aperturas, respuestas y rebotes hacia tus sistemas. Los cuerpos de los hilos se redactan en la vista de lista; obtén un solo hilo para el detalle. Así es como enrutas respuestas positivas hacia un CRM mientras los conectores nativos siguen en camino.
curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/inbox/threads \ -H "Authorization: Bearer $FIRSTSALES_API_KEY"Mantente dentro de la superficie pública
La API solo expone la superficie pública
/api/v1. No llames a rutas privadas de la app, callbacks de proveedores, píxeles de seguimiento, manejadores de baja de suscripción, o rutas cron internas: no forman parte del contrato y se romperán. Si una llamada devuelveunsupported_operation, detente y trátalo como "no disponible vía la API", no como algo que rodear.Aplican los códigos de estado estándar:
401clave inválida/revocada,422validación (el body indica el campo),429límite de tasa (reduce la frecuencia y reintenta).
Consejos de experto
whoami antes de escribir
Confirma que la clave resuelve a la organización/espacio de trabajo que pretendes antes de cualquier llamada que modifique datos. Una clave con alcance al espacio de trabajo equivocado es la forma más común de escribir datos en el lugar incorrecto.
Envía siempre un Idempotency-Key en las creaciones
Los reintentos de red ocurren. Un Idempotency-Key hace que un POST repetido sea una operación nula en vez de un contacto duplicado o un cobro doble.
Guarda la clave una vez, nunca la imprimas
El secreto se muestra una sola vez y se guarda redactado. Ponlo directo en un gestor de secretos; nunca lo registres en logs, lo subas a un commit, ni lo envíes dentro de un bundle de cliente.
Trata unsupported_operation como una parada dura
Si la API devuelve unsupported_operation, lo que quieres hacer no está en el contrato público. No recurras a rutas privadas de la app para forzarlo: reporta la limitación.
Preguntas frecuentes
¿Dónde consigo una clave de API?
Settings → API. Crea una Developer API key con los alcances y el nivel de acceso que necesitas; se muestra una sola vez, así que cópiala de inmediato. Revoca y regenera en la misma página si queda expuesta.
¿Cuál es la URL base y la autenticación?
URL base https://api.app.firstsales.io; autentica con Authorization: Bearer $FIRSTSALES_API_KEY y envía JSON. Empieza con GET /api/v1/whoami para confirmar el contexto.
¿Por qué las rutas son tan largas?
Los recursos están delimitados a una organización y un espacio de trabajo, así que las rutas son /api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Obtén los IDs desde /api/v1/organizations y su subrecurso /workspaces (o desde whoami).
¿Cómo evito escrituras duplicadas?
Envía un encabezado Idempotency-Key en las solicitudes de creación. Una solicitud reintentada con la misma clave devuelve el resultado original en vez de crear un segundo registro: segura de repetir tras un timeout.
¿Puedo leer métricas de campaña y respuestas?
Sí: GET …/campaigns/{id}/analytics para embudo/interacción, y GET …/inbox/threads para actividad de conversación. Los cuerpos de los hilos se redactan en la lista; obtén un solo hilo para el detalle completo.
¿Hay una integración de Zapier o CRM en su lugar?
No hay conector de Zapier, y los conectores nativos de CRM (Salesforce, HubSpot, Pipedrive) todavía están en camino. Hasta que se lancen, la API REST (o el CLI) es la forma soportada de integrar y sincronizar.
¿Qué significa unsupported_operation?
La acción solicitada no forma parte del contrato público /api/v1. Detente y repórtalo: no llames a rutas privadas de la app, callbacks, píxeles ni endpoints internos para rodearlo; no están soportados y se romperán.