Skip to main content
This guide will walk you through making your first API calls to CompanyFlow. You’ll learn how to authenticate and interact with the API endpoints.
Make sure you have CompanyFlow running locally or have access to a deployed instance. See the Installation guide if you need to set up the server first.

​
Step 1: Verify the Server is Running

First, check that the CompanyFlow server is healthy and accessible: 
curl http://localhost:8080/health
You should receive an ok response. The server runs on port 8080 by default, or the port specified in your PORT environment variable.

​
Step 2: Explore the API Documentation

CompanyFlow provides interactive Swagger documentation. Open your browser and navigate to: 
http://localhost:8080/swagger/index.html
This interactive interface allows you to explore all available endpoints, view request/response schemas, and even test API calls directly from your browser.

​
Step 3: Authenticate

All protected endpoints in CompanyFlow require JWT authentication. To get started, you’ll need to log in with valid employee credentials.

​
Login Request

The login endpoint is located at /auth/login and accepts the following payload: 
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

​
Login Response

On successful authentication, you’ll receive a response containing: 
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "role": "admin",
    "employee": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "company_id": "660e8400-e29b-41d4-a716-446655440000"
    },
    "company": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corporation",
      "slug": "acme-corp"
    }
  }
}
Store the JWT token securely. Never commit tokens to version control or expose them in client-side code.
The response includes:
  • token: JWT token for authenticating subsequent requests
  • role: The employee’s role in the system
  • employee: Basic employee profile information
  • company: The company (tenant) the employee belongs to

​
Step 4: Make an Authenticated Request

Now that you have a JWT token, you can make authenticated requests to protected endpoints. Include the token in the Authorization header with the Bearer prefix.

​
Example: Get Company Information

curl -X GET http://localhost:8080/companies/660e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Example Response

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "email": "[email protected]",
    "phone": "+1-555-0123",
    "address": "123 Business St, City, State 12345",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Step 5: List Companies with Pagination

CompanyFlow supports pagination for list endpoints. Here’s how to retrieve a paginated list of companies: 
curl -X GET "http://localhost:8080/companies?page=1&page_size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Query Parameters

  • page: Page number (default: 1)
  • page_size: Number of items per page (default: 10)
  • status: Filter by company status (optional)
  • search: Search by company name or slug (optional)

​
Paginated Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "name": "Acme Corporation",
        "slug": "acme-corp",
        "status": "active"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total_items": 1,
      "total_pages": 1
    }
  }
}

​
Common API Response Structure

All CompanyFlow API responses follow a consistent structure:

​
Success Response

{
  "success": true,
  "data": { /* response data */ },
  "message": "optional success message"
}

​
Error Response

{
  "success": false,
  "error": "Error message describing what went wrong"
}

​
HTTP Status Codes

CompanyFlow uses standard HTTP status codes:
  • 200 OK: Request succeeded
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request body or parameters
  • 401 Unauthorized: Missing or invalid authentication token
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server error occurred

​
Next Steps

Authentication Guide

Learn more about JWT authentication and security

API Reference

Explore all available endpoints and their schemas

Employee Management

Manage employee records and bulk uploads

Leave Management

Handle leave requests and approvals
Use the interactive Swagger UI at http://localhost:8080/swagger/index.html to test endpoints without writing code. It includes authentication support and request validation.

Build docs developers (and LLMs) love

Get started for freeTalk to us