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

500

---

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	"[email protected]"
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

422

500

---

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

404

500

---

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

404

422

500

---

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

404

Untitled

---

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

404

500