# Company Management

## **Get Companies**

<mark style="color:green;">**`GET`**</mark> `api/companies`

### **Description:**

Returns a list of companies created by the authenticated company.

### **Request Headers:**

| Header Name     | Description                       | Type   | Required |
| --------------- | --------------------------------- | ------ | -------- |
| `Authorization` | Bearer token for API access       | string | Yes      |
| `Content-Type`  | Must be set to `application/json` | string | Yes      |

### **Response:**

{% tabs %}
{% tab title="200" %}
200 OK:

```json
{
    "data": [
        {
            "id": 1,
            "name": "Company A",
            "address": "1234 Street",
            "phone": "123456789",
            "registration_id": "REG123456",
            "created_by": 1,
            "status": "approved",
            "is_active": true
        },
        {
            "id": 2,
            "name": "Company B",
            "address": "5678 Street",
            "phone": "987654321",
            "registration_id": "REG654321",
            "created_by": 1,
            "status": "pending review",
            "is_active": false
        }
    ],
    "current_page": 1,
    "last_page": 1,
    "total": 2
}
```

{% endtab %}

{% tab title="403" %}
**403 Forbidden:**

```json
{
    "error": "API access is disabled for this company."
}
```

{% endtab %}

{% tab title="500" %}
**Internal Server Error**

```json
{
    "error": "An error occurred while fetching the list of companies. Please try again later."
}
```

{% endtab %}
{% endtabs %}

***

## **Create a New Company**

<mark style="color:green;">**POST**</mark> `/api/companies`

### **Description:**

Creates a new company under the authenticated company.

### **Request Headers:**

| Header Name   | Value Type   | Description                                    |
| ------------- | ------------ | ---------------------------------------------- |
| Authorization | Bearer Token | The token used for authenticating the request. |
| Content-Type  | string       | Must be set to `application/json`.             |

### **Request Body:**

| Parameter          | Description                                                 | Type   | Required | Example                  |
| ------------------ | ----------------------------------------------------------- | ------ | -------- | ------------------------ |
| name               | The name of the company.                                    | string | Yes      | "New Company"            |
| address            | The company's address.                                      | string | No       | "1234 Main St."          |
| phone              | The company's phone number.                                 | string | No       | "1234567890"             |
| registration\_id   | The company's registration ID.                              | string | No       | "REG123456"              |
| first\_name        | First name of the super admin.                              | string | Yes      | "John"                   |
| last\_name         | Last name of the super admin.                               | string | Yes      | "Doe"                    |
| personal\_email    | Super admin's personal email (must be unique).              | string | Yes      | "<john.doe@example.com>" |
| title              | The title of the super admin.                               | string | Yes      | "CEO"                    |
| domain\_name       | Unique domain name for the company.                         | string | Yes      | "newcompany.com"         |
| email\_template    | Email template to be used.                                  | string | Yes      | "default\_template"      |
| payment\_frequency | The payment frequency (one of: weekly, bi-weekly, monthly). | string | Yes      | "monthly"                |

### **Response:**

{% tabs %}
{% tab title="201" %}

```json
{
    "success": "Company created successfully.",
    "company": {
        "id": 3,
        "name": "New Company",
        "code": "NC01",
        "address": "7890 Street",
        "phone": "111222333",
        "registration_id": null,
        "email_template": "default",
        "payment_frequency": "monthly",
        "created_by": 1,
        "status": "pending review",
        "domain": "newcompany.com",
        "is_active": false
    }
}
```

{% endtab %}

{% tab title="403" %}
**Forbidden**

```json
{
    "error": "Access to this API is disabled for your company."
}
```

{% endtab %}

{% tab title="422" %}
**Unprocessable Content**

```json
{
    "error": "Validation failed.",
    "messages": {
        "name": [
            "The company name is required."
        ],
        "first_name": [
            "The first name of the super admin is required."
        ],
        "last_name": [
            "The last name of the super admin is required."
        ],
        "personal_email": [
            "The super admin's personal email is required."
        ],
        "title": [
            "The title field is required."
        ],
        "domain_name": [
            "The domain name is required and must be unique."
        ],
        "email_template": [
            "An email template is required."
        ],
        "payment_frequency": [
            "The payment frequency is required."
        ]
    }
}
```

{% endtab %}

{% tab title="500" %}
&#x20;**Internal Server Error:**

```json
{
    "error": "An error occurred while creating the company. Please try again later."
}
```

{% endtab %}
{% endtabs %}

***

## **Get Company Details**

<mark style="color:green;">**GET**</mark> `/api/companies/{id}`

### **Description:**

Retrieves details of a specific company created by the authenticated company.

### **Request Headers:**

| Header Name   | Value Type   | Description                                    |
| ------------- | ------------ | ---------------------------------------------- |
| Authorization | Bearer Token | The token used for authenticating the request. |

### **Request Parameters:**

| Parameter | Value Type | Description                        |
| --------- | ---------- | ---------------------------------- |
| id        | Integer    | The ID of the company to retrieve. |

### **Response:**

{% tabs %}
{% tab title="200" %}

```json
{
    "id": 3,
    "name": "New Company",
    "code": "NC01",
    "address": "7890 Street",
    "phone": "111222333",
    "registration_id": "REG123456",
    "email_template": "default",
    "payment_frequency": "monthly",
    "created_by": 1,
    "status": "pending review",
    "domain": "newcompany.com",
    "is_active": false
}
```

{% endtab %}

{% tab title="403" %}
**Forbidden:**

```json
{
    "error": "API access is disabled for this company."
}
```

{% endtab %}

{% tab title="404" %}
**Not Found:**

```json
{
    "error": "Company not found or does not belong to the current company."
}
```

{% endtab %}

{% tab title="500" %}
**Internal Server Error:**

```json
{
    "error": "An error occurred while retrieving the company details. Please try again later."
}
```

{% endtab %}
{% endtabs %}

***

## **Update a Company**

<mark style="color:blue;">**PUT**</mark> `/api/companies/{id}`

### **Description:**

Updates the details of a specific company created by the authenticated company.

### **Request Headers:**

| Header Name   | Value Type   | Description                                    |
| ------------- | ------------ | ---------------------------------------------- |
| Authorization | Bearer Token | The token used for authenticating the request. |
| Content-Type  | string       | Must be set to `application/json`.             |

### **Request Parameters:**

| Parameter | Value Type | Description                      |
| --------- | ---------- | -------------------------------- |
| id        | Integer    | The ID of the company to update. |

### **Request Body:**

| Parameter          | Description                                                 | Type   | Required | Example                |
| ------------------ | ----------------------------------------------------------- | ------ | -------- | ---------------------- |
| name               | The name of the company.                                    | string | No       | "Updated Company Name" |
| address            | The company's address.                                      | string | No       | "Updated Address"      |
| phone              | The company's phone number.                                 | string | No       | "1234567890"           |
| registration\_id   | The company's registration ID (must be unique).             | string | No       | "REG123456"            |
| email\_template    | Email template to be used.                                  | string | No       | "new\_template"        |
| code               | The company code.                                           | string | No       | "UCN01"                |
| domain             | The company's domain name.                                  | string | No       | "updatedcompany.com"   |
| payment\_frequency | The payment frequency (one of: weekly, bi-weekly, monthly). | string | No       | "weekly"               |

### **Response:**

{% tabs %}
{% tab title="200" %}
**OK:**

```json
{
    "message": "Company updated successfully.",
    "company": {
        "id": 3,
        "name": "Updated Company Name",
        "address": "Updated Address",
        "phone": "111222333",
        "registration_id": "REG123456",
        "email_template": "new_template",
        "payment_frequency": "weekly",
        "code": "UCN01",
        "domain": "updatedcompany.com",
        "is_active": true
    }
}
```

{% endtab %}

{% tab title="403" %}
**Forbidden**

```json
{
    "error": "API access is disabled for this company."
}
```

{% endtab %}

{% tab title="404" %}
**Not Found:**

```json
{
    "error": "Company not found or does not belong to the current company."
}
```

{% endtab %}

{% tab title="422" %}
**Unprocessable Entity**

```json
{
    "error": "Validation failed.",
    "messages": {
        "registration_id": ["The registration ID is already in use by another company."]
    }
}
```

{% endtab %}

{% tab title="500" %}
**Internal Server Error**

```json
{
    "error": "An error occurred while updating the company details. Please try again later."
}
```

{% endtab %}
{% endtabs %}

***

## **Deactivate a Company**

<mark style="color:purple;">**PATCH**</mark> `/api/companies/{id}/deactivate`

### **Description:**

Deactivates a company, making it inactive and revoking API access.

### **Request Headers:**

| Header Name   | Value Type   | Description                                    |
| ------------- | ------------ | ---------------------------------------------- |
| Authorization | Bearer Token | The token used for authenticating the request. |

### **Request Parameters:**

| Parameter | Value Type | Description                          |
| --------- | ---------- | ------------------------------------ |
| id        | Integer    | The ID of the company to deactivate. |

### **Response:**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "Company deactivated successfully."
}
```

{% endtab %}

{% tab title="403" %}
**Forbidden**

```json
{
    "error": "API access is disabled for this company."
}
```

{% endtab %}

{% tab title="404" %}
**Not Found**

```json
{
    "error": "Company not found or does not belong to the current company."
}
```

{% endtab %}

{% tab title="Untitled" %}
**Internal Server Error**

```json
{
    "error": "An error occurred while deactivating the company. Please try again later."
}
```

{% endtab %}
{% endtabs %}

***

## **Activate a Company**

<mark style="color:purple;">**PATCH**</mark> `/api/companies/{id}/activate`

### **Description:**

Activates a company, making it active and restoring API access.

### **Request Headers:**

| Header Name   | Value Type   | Description                                    |
| ------------- | ------------ | ---------------------------------------------- |
| Authorization | Bearer Token | The token used for authenticating the request. |

### **Request Parameters:**

| Parameter | Value Type | Description                        |
| --------- | ---------- | ---------------------------------- |
| id        | Integer    | The ID of the company to activate. |

### **Response:**

{% tabs %}
{% tab title="200" %}
**OK**

```json
{
    "message": "Company activated successfully."
}
```

{% endtab %}

{% tab title="403" %}
&#x20;**Forbidden:**

```json
{
    "error": "API access is disabled for this company."
}
```

{% endtab %}

{% tab title="404" %}
**Not Found:**

```json
{
    "error": "Company not found or does not belong to the current company."
}
```

{% endtab %}

{% tab title="500" %}
**Internal Server Error:**

```json
{
    "error": "An error occurred while activating the company. Please try again later."
}
```

{% endtab %}
{% endtabs %}