BizCARE MyInvois
API Reference

Companies API

Complete API reference for managing company information and settings

Companies API

This section covers all company-related endpoints for managing company information, settings, and validation in the E-Invoice system.

Authentication

All endpoints require authentication via API key:

X-API-Key: your-api-key-here

Base URL

/api

Get Company Information

Retrieve the current company's information and settings.

Endpoint

GET /api/companies

Headers

X-API-Key: your-api-key-here

Response Example

{
  "data": {
    "id": 2,
    "user_id": 4,
    "client_id": "80e766cd-fed8-46df-bdf0-d72b97391b70",
    "client_secret": "2690aec0-4b91-42da-acdf-51c4424ffa04",
    "scope": "InvoicingAPI",
    "access_token": "eyJhbGci...",
    "token_expires_in": 3600,
    "token_expires_at": "2025-09-17T04:58:26.320+00:00",
    "name": "Gaincue Retail",
    "tin_code": "IG12345678901",
    "registration_number": "991021081111",
    "registration_type": "NRIC",
    "sst_registration_number": null,
    "tourism_tax_registration_number": null,
    "business_activity_description": "sell pc parts test",
    "msic_code": "46510",
    "country": "Malaysia",
    "state": "Pulau Pinang",
    "city": "Bukit Mertajam",
    "zip_code": "14000",
    "address": "Company address full dummy 1",
    "phone": "+60 12345678",
    "email": "gaincueRetail@gmail.com",
    "bank_account": null,
    "exporter_certified_number": null,
    "setting": {
      "INVOICE_PREFIX": "25-",
      "DEBIT_NOTE_PREFIX": "DN-",
      "CREDIT_NOTE_PREFIX": "CN-",
      "PREFIX_DIGIT_COUNT": 5,
      "REFUND_NOTE_PREFIX": "RN-",
      "AUTO_SUBMIT_INVOICE": false,
      "CONSOLIDATE_INVOICE_PREFIX": "CINV-",
      "SELF_BILLED_INVOICE_PREFIX": "SBINV-",
      "CONSOLIDATE_SELF_BILLED_INVOICE_PREFIX": "CSBINV-"
    },
    "created_at": "2025-08-19T03:03:35.345+00:00",
    "updated_at": "2025-09-23T04:10:17.488+00:00",
    "default_tax_types_and_rates": [
      {
        "tax_rate": 10,
        "tax_type": "01",
        "factor_type": "percentage"
      },
      {
        "tax_rate": 5,
        "tax_type": "02",
        "factor_type": "percentage"
      }
    ],
    "is_company_ready": true,
    "as_buyer": {
      "contactNumber": "+60 12345678",
      "name": "Gaincue Retail",
      "partyType": "LOCAL_INDIVIDUAL",
      "registrationType": "NRIC",
      "registrationNumber": "991021081111",
      "sstRegistrationNumber": "NA",
      "tin": "IG12345678901",
      "address": {
        "addressLine0": "Company address full dummy 1",
        "cityName": "Bukit Mertajam",
        "country": "MYS",
        "state": "07",
        "postalZone": "14000"
      },
      "email": "gaincueRetail@gmail.com"
    },
    "as_supplier": {
      "contactNumber": "+60 12345678",
      "name": "Gaincue Retail",
      "partyType": "LOCAL_INDIVIDUAL",
      "registrationType": "NRIC",
      "registrationNumber": "991021081111",
      "sstRegistrationNumber": "NA",
      "tin": "IG12345678901",
      "address": {
        "addressLine0": "Company address full dummy 1",
        "cityName": "Bukit Mertajam",
        "country": "MYS",
        "state": "07",
        "postalZone": "14000"
      },
      "email": "gaincueRetail@gmail.com",
      "businessActivityDescription": "sell pc parts test",
      "msic": "46510",
      "tourismTaxRegistrationNumber": "NA"
    }
  }
}

Update Company Settings

Update company settings including invoice prefixes and configurations.

Endpoint

PUT /api/companies

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
settingobjectYesCompany settings object

Setting Object

FieldTypeRequiredDescription
INVOICE_PREFIXstringYesPrefix for invoice numbers
DEBIT_NOTE_PREFIXstringYesPrefix for debit note numbers
CREDIT_NOTE_PREFIXstringYesPrefix for credit note numbers
PREFIX_DIGIT_COUNTnumberYesNumber of digits in the prefix
REFUND_NOTE_PREFIXstringYesPrefix for refund note numbers
AUTO_SUBMIT_INVOICEbooleanYesWhether to automatically submit invoices
CONSOLIDATE_INVOICE_PREFIXstringYesPrefix for consolidated invoices
SELF_BILLED_INVOICE_PREFIXstringYesPrefix for self-billed invoices
CONSOLIDATE_SELF_BILLED_INVOICE_PREFIXstringYesPrefix for consolidated self-billed invoices

Request Example

{
  "setting": {
    "INVOICE_PREFIX": "25-",
    "DEBIT_NOTE_PREFIX": "DN-",
    "CREDIT_NOTE_PREFIX": "CN-",
    "PREFIX_DIGIT_COUNT": 5,
    "REFUND_NOTE_PREFIX": "RN-",
    "AUTO_SUBMIT_INVOICE": false,
    "CONSOLIDATE_INVOICE_PREFIX": "CINV-",
    "SELF_BILLED_INVOICE_PREFIX": "SBINV-",
    "CONSOLIDATE_SELF_BILLED_INVOICE_PREFIX": "CSBINV-"
  }
}

Response

Success (200)

Returns the updated company object with the same structure as the GET endpoint.

Validation Error (422)

{
  "errors": [
    {
      "message": "The CONSOLIDATE_SELF_BILLED_INVOICE_PREFIX field must be defined",
      "rule": "required",
      "field": "setting.CONSOLIDATE_SELF_BILLED_INVOICE_PREFIX"
    }
  ]
}

Validate TIN

Validate a Tax Identification Number (TIN) against the MyInvois system.

Endpoint

POST /api/validation/tin

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
registration_typestringYesType of registration: NRIC, BRN, PASSPORT
registration_numberstringYesRegistration number
tinstringYesTax Identification Number to validate

Request Example

{
  "registration_type": "NRIC",
  "registration_number": "991021081111",
  "tin": "IG12345678901"
}

Response

Success (200)

{
  "data": {
    "is_valid": true,
    "message": "TIN validation successful"
  }
}

Invalid TIN (200)

{
  "data": {
    "is_valid": false,
    "message": "TIN validation failed"
  }
}

Validate Company Name

Validate a company name for uniqueness and compliance.

Endpoint

POST /api/validation/company-name

Headers

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringYesCompany name to validate

Request Example

{
  "name": "My Company Sdn Bhd"
}

Response

Success (200)

{
  "data": {
    "is_valid": true,
    "message": "Company name is available"
  }
}

Company Data Structure

Main Company Object

FieldTypeDescription
idnumberUnique company identifier
user_idnumberAssociated user ID
client_idstringMyInvois client ID
client_secretstringMyInvois client secret
scopestringAPI scope permissions
access_tokenstringCurrent access token
token_expires_innumberToken expiration time in seconds
token_expires_atstringToken expiration timestamp
namestringCompany name
tin_codestringTax Identification Number
registration_numberstringCompany registration number
registration_typestringType of registration
sst_registration_numberstring|nullSST registration number
tourism_tax_registration_numberstring|nullTourism tax registration
business_activity_descriptionstringDescription of business activities
msic_codestringMalaysian Standard Industrial Classification code
countrystringCountry name
statestringState/province
citystringCity name
zip_codestringPostal code
addressstringFull address
phonestringContact phone number
emailstringContact email
bank_accountstring|nullBank account details
exporter_certified_numberstring|nullExporter certification number
settingobjectCompany settings
created_atstringCreation timestamp
updated_atstringLast update timestamp
default_tax_types_and_ratesarrayDefault tax configurations
is_company_readybooleanWhether company setup is complete
as_buyerobjectCompany information formatted for buyer role
as_supplierobjectCompany information formatted for supplier role

Default Tax Types and Rates

Each item in the default_tax_types_and_rates array contains:

FieldTypeDescription
tax_ratenumberTax rate value
tax_typestringTax type code
factor_typestringType of factor (usually "percentage")

Company as Buyer/Supplier

The as_buyer and as_supplier objects format the company information for use in invoices:

FieldTypeDescription
contactNumberstringContact phone number
namestringCompany name
partyTypestringParty type classification
registrationTypestringRegistration type
registrationNumberstringRegistration number
sstRegistrationNumberstringSST registration number
tinstringTax Identification Number
addressobjectAddress information
address.addressLine0stringAddress line
address.cityNamestringCity name
address.countrystringCountry code (e.g., "MYS")
address.statestringState code
address.postalZonestringPostal code
emailstringContact email

Additional fields for as_supplier:

FieldTypeDescription
businessActivityDescriptionstringBusiness activity description
msicstringMSIC code
tourismTaxRegistrationNumberstringTourism tax registration

Common Error Codes

Status CodeDescription
200OK - Request successful
400Bad Request - Invalid request data
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Company not found
422Unprocessable Entity - Validation errors

Error Response Format

{
  "errors": [
    {
      "message": "Error description",
      "rule": "validation_rule_name",
      "field": "field.path"
    }
  ]
}

Important Notes

  1. Registration Types:

    • NRIC: National Registration Identity Card (for Malaysian individuals)
    • BRN: Business Registration Number (for businesses)
    • PASSPORT: Passport number (for foreign individuals)

  2. Party Types:

    • LOCAL_INDIVIDUAL: Local Malaysian individual
    • LOCAL_EXEMPTED_ENTITY: Local exempted entity
    • LOCAL_BUSINESS_AGENT_DEALER_DISTRIBUTOR: Local business/agent/dealer/distributor
    • FOREIGNER_BUSINESS: Foreign business entity
    • FOREIGNER_INDIVIDUAL: Foreign individual

  3. State Codes: Use Malaysian state codes (e.g., "07" for Perak, "14" for Penang)

  4. Country Code: Use "MYS" for Malaysia (ISO 3166-1 alpha-3)

  5. MSIC Codes: Use Malaysian Standard Industrial Classification codes to categorize business activities

  6. Token Management: The API automatically manages MyInvois access tokens. The token_expires_at field indicates when the current token expires.

  7. Company Readiness: The is_company_ready field indicates whether the company has completed all required setup steps for e-invoicing.

Data Models

Comprehensive overview of all data models in the E-Invoice API system

Invoices API

Complete API reference for managing invoices in the E-Invoice system