API Documentation

Developer Documentation

Complete API reference and integration guide for Onboarding Manager. Build powerful onboarding workflows with our RESTful API and webhook integrations.

Getting Started

Welcome to the Onboarding Manager API. This guide will help you get started with integrating our corporate onboarding platform into your systems.

Quick Start

  1. Obtain an API token from your account administrator
  2. Make your first request to test connectivity
  3. Explore the API reference below
  4. Set up webhooks for real-time notifications

Base URL

https://your-instance.onboardingmanager.co/api

Authentication

All API requests require authentication using a Bearer token in the Authorization header. Contact your administrator to obtain an API token.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://your-instance.onboardingmanager.co/api/prospects

Note: Keep your API tokens secure. Never commit them to version control or share them publicly.

API Reference

The Onboarding Manager API is organized around REST principles. Our API returns JSON responses and uses standard HTTP response codes.

Prospects

Prospects represent companies or individuals going through the onboarding process. Each prospect is identified by their NIT (Colombian tax ID).

GET /api/prospects

Retrieve a list of all prospects.

Example Response

{
  "data": [
    {
      "id": 900123456,
      "nombre_comercial": "Acme Corporation",
      "razon_social": "Acme Corp S.A.S.",
      "nit": "900123456",
      "status": "active",
      "inserted_at": "2024-01-15T10:30:00Z"
    }
  ]
}
GET /api/prospects/:id

Retrieve a specific prospect by NIT.

Parameters

Parameter Type Description
id integer The prospect's NIT (Colombian tax ID)

Example Response

{
  "data": {
    "id": 900123456,
    "nombre_comercial": "Acme Corporation",
    "razon_social": "Acme Corp S.A.S.",
    "nit": "900123456",
    "email": "contact@acme.com",
    "telefono": "+57 1 234 5678",
    "ciudad": "Bogotá",
    "status": "active",
    "inserted_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
POST /api/prospects

Create a new prospect.

Request Body

{
  "nit": 900123456,
  "nombre_comercial": "Acme Corporation",
  "razon_social": "Acme Corp S.A.S.",
  "email": "contact@acme.com",
  "telefono": "+57 1 234 5678",
  "ciudad": "Bogotá"
}

Response

{
  "data": {
    "id": 900123456,
    "nombre_comercial": "Acme Corporation",
    "status": "pending",
    "inserted_at": "2024-01-15T10:30:00Z"
  }
}

Onboardings

Onboardings represent active onboarding sessions linked to prospects. They track the progress through verification and compliance workflows.

GET /api/onboardings

Retrieve a list of all onboardings.

Example Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "prospect_id": 900123456,
      "verification_id": "ver_abc123",
      "status": "in_progress",
      "inserted_at": "2024-01-15T10:30:00Z"
    }
  ]
}
GET /api/onboardings/:id

Retrieve a specific onboarding by UUID.

Example Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "prospect_id": 900123456,
    "verification_id": "ver_abc123",
    "status": "in_progress",
    "trebol_session_id": "sess_xyz789",
    "inserted_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:45:00Z"
  }
}

Onboarding Status Values

Onboardings progress through different status values during their lifecycle. Understanding these statuses helps you track the onboarding journey.

Status Description
initiated Onboarding session has been created and the prospect has been invited
ContractEmailSent Truora identity validation email has been sent
SarlaftCaseCreated ClickUp case created for compliance review
sarlaftApprovedProspect Compliance screening approved by SARLAFT team
sarlaftRejectedProspect Compliance screening rejected by SARLAFT team
Document statuses Various statuses synced from Trebol document verification (e.g., documents uploaded, signed, etc.)

Status Flow

Typical flow: initiated → ContractEmailSent → SarlaftCaseCreated → sarlaftApprovedProspect

The process can transition to sarlaftRejectedProspect if compliance checks fail. Document statuses from Trebol are also reflected dynamically.

Events

Events provide a complete audit trail of all actions in the system. Each event includes full payload data and timestamps.

GET /api/events

Retrieve a list of all events.

Example Response

{
  "data": [
    {
      "id": "evt_123456",
      "event_type": "ProspectCreated",
      "payload": {
        "prospect_id": 900123456,
        "nombre_comercial": "Acme Corporation"
      },
      "inserted_at": "2024-01-15T10:30:00Z"
    }
  ]
}
GET /api/events/:id

Retrieve a specific event by ID.

GET /api/events?prospect_id=:prospect_id

Retrieve all events for a specific prospect.

Query Parameters

Parameter Type Description
prospect_id integer The prospect's NIT to filter events

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://your-instance.onboardingmanager.co/api/events?prospect_id=900123456

Example Response

{
  "data": [
    {
      "id": "evt_001",
      "event_type": "ProspectCreated",
      "payload": {
        "prospect_id": 900123456,
        "nombre_comercial": "Acme Corporation"
      },
      "inserted_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "evt_002",
      "event_type": "OnboardingCreated",
      "payload": {
        "onboarding_id": "onb_abc123",
        "prospect_id": 900123456
      },
      "inserted_at": "2024-01-15T11:00:00Z"
    }
  ]
}

Tip: Use this endpoint to track the complete lifecycle of a prospect's onboarding journey, from creation to completion.

Webhooks

Webhooks allow external partners to send real-time notifications to Onboarding Manager. All webhook requests are validated using HMAC signatures and processed asynchronously.

Webhook Endpoint

POST /webhooks/partners/:partner

Receive webhook notifications from integrated partners.

Supported Partners

  • trebol - Digital onboarding and signature management
  • truora - Identity verification and background checks
  • taktile - Compliance screening and risk calculation
  • clickup - Case and task management
  • salesforce - CRM integration
  • zoho - CRM lead ingestion

Authentication

Webhook requests must include an HMAC signature in the request headers. The signature is computed using SHA-256 HMAC with your partner-specific secret key.

Example Webhook Payload

{
  "event_type": "verification_completed",
  "prospect_id": 900123456,
  "verification_id": "ver_abc123",
  "status": "approved",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "verification_method": "document",
    "confidence_score": 0.98
  }
}

Processing: All webhooks are processed asynchronously using Oban job queues with automatic retry logic. You'll receive a 202 Accepted response immediately.

Error Handling

The API uses standard HTTP status codes to indicate success or failure. All error responses include a JSON body with details.

HTTP Status Codes

Status Code Meaning
200 Success
201 Created
202 Accepted (async processing)
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API token
404 Not Found
422 Unprocessable Entity - Validation errors
500 Internal Server Error

Error Response Format

{
  "error": {
    "message": "Prospect not found",
    "code": "not_found",
    "details": {}
  }
}

Need Help?

Contact your administrator for API tokens, technical support, or questions about integrating with Onboarding Manager.