> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Falasefemi2/companyflow/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with CompanyFlow API in minutes

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.

<Note>
  Make sure you have CompanyFlow running locally or have access to a deployed instance. See the [Installation guide](/installation) if you need to set up the server first.
</Note>

## Step 1: Verify the Server is Running

First, check that the CompanyFlow server is healthy and accessible:

```bash theme={null}
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:

```bash theme={null}
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "your_password"
  }'
```

### Login Response

On successful authentication, you'll receive a response containing:

```json theme={null}
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "role": "admin",
    "employee": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "John",
      "last_name": "Doe",
      "email": "user@company.com",
      "company_id": "660e8400-e29b-41d4-a716-446655440000"
    },
    "company": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corporation",
      "slug": "acme-corp"
    }
  }
}
```

<Warning>
  Store the JWT token securely. Never commit tokens to version control or expose them in client-side code.
</Warning>

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

```bash theme={null}
curl -X GET http://localhost:8080/companies/660e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "email": "contact@acmecorp.com",
    "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:

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "success": true,
  "data": { /* response data */ },
  "message": "optional success message"
}
```

### Error Response

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="shield" href="/concepts/authentication">
    Learn more about JWT authentication and security
  </Card>

  <Card title="API Reference" icon="book" href="/api/auth/login">
    Explore all available endpoints and their schemas
  </Card>

  <Card title="Employee Management" icon="users" href="/api/employees/create">
    Manage employee records and bulk uploads
  </Card>

  <Card title="Leave Management" icon="calendar" href="/api/leaves/create">
    Handle leave requests and approvals
  </Card>
</CardGroup>

<Tip>
  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.
</Tip>