Company Management

This documentation provides details for the API endpoints that allow managing companies in the system.

Get Companies

GET 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:

200

200 OK:

{
    "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
}

403

403 Forbidden:

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

500

Internal Server Error

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

---

Create a New Company

POST /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	"[e-mail]"
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:

201

{
    "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
    }
}

403

Forbidden

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

422

Unprocessable Content

{
    "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."
        ]
    }
}

500

Internal Server Error:

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

---

Get Company Details

GET /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:

200

{
    "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
}

403

Forbidden:

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

404

Not Found:

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

500

Internal Server Error:

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

---

Update a Company

PUT /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:

200

OK:

{
    "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
    }
}

403

Forbidden

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

404

Not Found:

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

422

Unprocessable Entity

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

500

Internal Server Error

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

---

Deactivate a Company

PATCH /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:

200

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

403

Forbidden

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

404

Not Found

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

Untitled

Internal Server Error

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

---

Activate a Company

PATCH /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:

200

OK

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

403

Forbidden:

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

404

Not Found:

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

500

Internal Server Error:

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