# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gangmates.com/api-documentation/api-reference/company-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.