JuanTax API

Overview

Welcome to JuanTax’s API!

Check out our Quick Guide if you already want to get started on making API requests.

We organized this site into the below major areas to help you get started using the JuanTax API.

Getting Started

JuanTax is a cloud-based tax platform which allows self-employed professionals and businesses prepare and file taxes compliant with the BIR tax regulations through the web and app.

You can use our API to generate and file your tax returns. Through the API, you can seamlessly manage your organizations and reports. The JuanTax API is built using REST principles which ensures predictable URLs that makes writing applications easy.

What is an API and How Does it Work

An application programming interface (API) is a software intermediary that allows communication between applications through a documented interface. It allows applications to exchange data or information and functionality quickly and securely. An API is like a messenger that delivers a user’s request to an external system and sends the system’s response back to the user.

An API is a set of rules that define how applications can talk to each other. It acts as a middleman between applications that want to connect with each other for a specified task.

A common example is the third-party login where applications allow users to sign in using their Facebook, Google, LinkedIn, or other accounts instead of creating an account directly. It doesn’t actually give the app access to your social media accounts. Instead, it uses the API to check if the user is already logged in to the third-party website. When the user confirms they want to log in using their social media account, the API provides the application with identification information so it knows who’s logging in.

Forms supported by JuanTax API

The API supports the following forms:

OAuth2.0

Overview

OAuth is an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications. It is a way to get access to protected data from an application. It’s safer and more secure than asking users to log in with passwords.

To simplify, OAuth 2.0 provides a way for applications to get limited access to user’s data in other applications without revealing their credentials.

For more information about OAuth 2.0, see oauth.net and RFC 6749.

OAuth 2.0 Concepts

OAuth 2.0 Flow

Client Credentials Flow is used when applications request an access token to access their own resources, not on behalf of a user. Client applications will be provided a client ID and client secret to obtain an access token.

Access tokens are used to make secure calls to an API and gain access. Access tokens have a limited lifetime of usually 5-30 minutes. This can be renewed with a refresh token. Refresh tokens are used to obtain new access tokens once the initial access token has expired.

How it Works

Client AppJuanTax Authorization ServerJuanTax APIAuthenticate with Client ID + Client SecretValidate Client ID + Client SecretAccess TokenRequest Data with Access TokenResponseClient AppJuanTax Authorization ServerJuanTax API

Endpoints and Formats

All API calls must be executed over HTTPS and must be made to: https://api.juan.tax.

Environments available within JuanTax API:

All responses are returned in JSON format.

Authentication

JuanTax REST API uses the OAuth2.0 protocol to authorize and authenticate client applications or API requests. It provides secure access on your application without exposing usernames and passwords.

Quick Guide

The following steps will walk you through the basics to get started using the JuanTax API.

  1. Create your account.
  2. Get your Authentication Keys.
  3. Get an access token from JuanTax Authorization Server.
  4. Send the access token to an API.
  5. Use a refresh token to get a new access token, if necessary.

Create your account

Before you start and be able to use JuanTax integrations, you need to create an account first. If you already have an account, you must still complete the request access form.

Get your Authentication Keys

https://api.juan.tax/oauth2/authorize/
client_id: O3KZFjKf1XSTKkZeiDS_Hrk0xJx-bjnYpV55ROJ4mPs
client_secret: *************************
> Note: Securely store the keys and do not share to anyone.

Get an Access Token

Request URL:

https://api.juan.tax/oauth2/token/

Request Body:

Field Type Example Value
client_id string O3KZFjKf1XSTKkZeiDS_Hrk0xJx-bjnYpV55ROJ4mPs
client_secret string 022880f02f1de2f11d907f13d967d155f81ba9eea535327fae7cc46641954640

Response Body:

Field Type Example Value
access_token string iJPM0taRmZKazFYU1RLa1plaURTX0hyazB4Sn
token_type string bearer

Example Server Response:

Code Description
200 The request was successful.

Send Access Token

Example:

requests.post(SANDBOX_URL + '/oauth2/token', auth=HTTPBasicAuth(CLIENT_ID, CLIENT_SECRET))
curl -X 'POST' 'https://api.juan.tax/oauth2/token' -H 'accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=CLIENT_ID&client_secret=CLIENT_SECRET'

Refresh Token

https://api.juan.tax/oauth2/token/

Request Body

Field Type Example Value
client_id string O3KZFjKf1XSTKkZeiDS_Hrk0xJx-bjnYpV55ROJ4mPs
client_secret string 022880f02f1de2f11d907f13d967d155f81ba9eea535327fae7cc46641954640
refresh_token string

Example Server Response

Code Description
200 The request was successful.

API Reference

Organization

Organization is the Business registered in Bureau of Internal Revenue (BIR). Business owners (whether individual or company) are required to register their businesses in order to make it legal. This allows a business owner to release receipts and invoices to their customers. You can learn more on how to register your business with the BIR here.

POST

Creates an organization with a unique Organization ID which will be referenced in other methods.

Request Body

Field Type Description
type string Classification of the Organization (Values: individual or non-individual); See Organization Classification.
registered_name string Registered Name of the Organization if type is Non-Individual
Trade Name of the Organization if type is Individual. This is optional for Individual type.
first_name string First Name of the Organization if type is Individual.
middle_name string Optional. Middle Name of the Organization if type is Individual.
last_name string Surname of the Organization if type is Individual.
address string Address of the organization.
city string City where the organization is based out of.
zip_code string Zip Code of the Region where the organization is based out of.
region string Name of the Region where the organization is based out of.
phone string Contact Number of the organization.
email string Email Address of the Organization.
tin string Tax Identification Number of the Organization. This is the first 9 digits of your TIN. If your TIN is 123-456-789-100, your actual TIN is 123-456-789.
branch_code string This is the last 3 digits after your TIN. If your TIN is 123-456-789-100, your Branch Code is 100.
rdo string Revenue District Office - a sector under BIR that keeps the records of taxpayers under its jurisdiction. See list of RDO Codes.
financial_year_end date Optional. Period end of a fiscal/calendar year (Ex: December). If no value was entered, default year end would be December.
line_of_business string Products or services offered by a business. See Line of Business.

Response Body

Field Type Description
organization_id string Unique identifier of the Organization
code number Returns the status codes like 200, 400, etc.
description string Name of the status code
detail string Detailed status message

Request URL:

https://api.juan.tax.com/organizations/

Example Request Body:

{
  "type": "non-individual",
  "registered_name": "Test 2551Q",
  "address": "ABC St",
  "city": "Makati",
  "zip_code": "1234",
  "region": "NCR",
  "phone": "165846302",
  "email": "a@test.com",
  "tin": "231-456-526",
  "branch_code": "781",
  "rdo": "050",
  "financial_year_end": "December",
  "line_of_business": "Preparation of coffee, cacao and cocoa beans"
}

Example Response Body:

{
  "organization_id": "fa9hgt20-73aa-4c4c-a88c-065jj468a635"
}

Example Server Response:

Code Description
200 The request was successful.

GET

1. Get Organization

Returns information about an organization.

Request Body

Field Type Description
organization_id string Unique identifier of the Organization

Response Body

Field Type Description
code number Returns the status codes like 200, 400, etc.
description string Name of the status code.
detail string Detailed status message.
type string Classification of the Organization (Values: individual or non-individual); See Organization Classification.
registered_name string Registered Name of the Organization if type is Non-Individual
Trade Name of the Organization if type is Individual. This is optional for Individual type.
first_name string First Name of the Organization if type is Individual.
middle_name string Middle Name of the Organization if type is Individual.
last_name string Surname of the Organization if type is Individual.
address string Address of the organization.
city string City where the organization is based out of.
zip_code string Zip Code of the Region where the organization is based out of.
region string Name of the Region where the organization is based out of.
phone string Contact Number of the organization.
email string Email Address of the Organization.
tin string Tax Identification Number of the Organization. This is the first 9 digits of your TIN. If your TIN is 123-456-789-100, your actual TIN is 123-456-789.
branch_code string This is the last 3 digits after your TIN. If your TIN is 123-456-789-100, your Branch Code is 100.
rdo string Revenue District Office - a sector under BIR that keeps the records of taxpayers under its jurisdiction. See list of RDO Codes.
financial_year_end date Period end of a fiscal/calendar year (Ex: December).
line_of_business string Products or services offered by a business. See Line of Business.

Request URL:

https://api.juan.tax.com/organizations/fa9hgt20-73aa-4c4c-a88c-065jj468a635/

Example Response Body:

{
  "type": "non-individual",
  "registered_name": "Test 2551Q",
  "address": "ABC St",
  "city": "Makati",
  "zip_code": "1234",
  "region": "NCR",
  "phone": "165846302",
  "email": "a@test.com",
  "tin": "231-456-526",
  "branch_code": "781",
  "rdo": "050",
  "financial_year_end": "December",
  "line_of_business": "Preparation of coffee, cacao and cocoa beans"
}

Example Server Response:

Code Description
200 The request was successful.

2. Get List Organizations

Returns list of organizations created on an account.

Request Body

Click Execute button.

Response Body

Field Type Description
code number Returns the status codes like 200, 400, etc.
description string Name of the status code.
detail string Detailed status message.
type string Classification of the Organization (Values: individual or non-individual); See Organization Classification.
registered_name string Registered Name of the Organization if type is Non-Individual
Trade Name of the Organization if type is Individual. This is optional for Individual type.
first_name string First Name of the Organization if type is Individual.
middle_name string Middle Name of the Organization if type is Individual.
last_name string Surname of the Organization if type is Individual.
address string Address of the organization.
city string City where the organization is based out of.
zip_code string Zip Code of the Region where the organization is based out of.
region string Name of the Region where the organization is based out of.
phone string Contact Number of the organization.
email string Email Address of the Organization.
tin string Tax Identification Number of the Organization. This is the first 9 digits of your TIN. If your TIN is 123-456-789-100, your actual TIN is 123-456-789.
branch_code string This is the last 3 digits after your TIN. If your TIN is 123-456-789-100, your Branch Code is 100.
rdo string Revenue District Office - a sector under BIR that keeps the records of taxpayers under its jurisdiction. See list of RDO Codes.
financial_year_end date Period end of a fiscal/calendar year (Ex: December).
line_of_business string Products or services offered by a business. See Line of Business.
organization_id string Unique identifier of the Organization

Request URL:

https://api.juan.tax.com/organizations/

Example Response Body:

[
  {
    "type": "individual",
    "registered_name": "Test Individual",
    "first_name": "Marj",
    "middle_name": "string",
    "last_name": "Test",
    "address": "ABC ST",
    "city": "Makati",
    "zip_code": "1234",
    "region": "NCR",
    "phone": "123-456-789",
    "email": "marj@test.com",
    "tin": "128-787-110",
    "branch_code": "000",
    "rdo": "050",
    "financial_year_end": "December 31",
    "line_of_business": "Preparation of coffee, cacao and cocoa beans",
    "organization_id": "eb6a214c-5c9a-53b6-91c1-7d732448b418"
  },
  {
    "type": "individual",
    "registered_name": "string",
    "first_name": "Marj",
    "middle_name": "string",
    "last_name": "Test1",
    "address": "ABC ST",
    "city": "Makati",
    "zip_code": "1234",
    "region": "NCR",
    "phone": "123-456-789",
    "email": "marj@test.com",
    "tin": "111-333-222",
    "branch_code": "555",
    "rdo": "050",
    "financial_year_end": "December 31",
    "line_of_business": "string",
    "organization_id": "2ca1321c-8ae9-5024-9a69-deaa6b028042"
  },
  {
    "type": "individual",
    "registered_name": "string",
    "first_name": "Marj",
    "middle_name": "string",
    "last_name": "Test2",
    "address": "ABC St.",
    "city": "Makati",
    "zip_code": "1234",
    "region": "NCR",
    "phone": "123-456-789",
    "email": "marj@test.com",
    "tin": "123-321-555",
    "branch_code": "000",
    "rdo": "050",
    "financial_year_end": "December 31",
    "line_of_business": "Testing",
    "organization_id": "d2fdc221-977f-4a2f-8ae1-01f94ad6d63b"
  }
]

Example Server Response:

Code Description
200 The request was successful.

PUT

Updates data of an organization.

Request Body

Field Type Description
organization_id string Required. Unique identifier of the Organization
registered_name string Registered Name of the Organization if type is Non-Individual
Trade Name of the Organization if type is Individual. This is optional for Individual type.
first_name string First Name of the Organization if type is Individual.
middle_name string Middle Name of the Organization if type is Individual.
last_name string Surname of the Organization if type is Individual.
address string Address of the organization.
city string City where the organization is based out of.
zip_code string Zip Code of the Region where the organization is based out of.
region string Name of the Region where the organization is based out of.
phone string Contact Number of the organization.
email string Email Address of the Organization.
tin string Tax Identification Number of the Organization. This is the first 9 digits of your TIN. If your TIN is 123-456-789-100, your actual TIN is 123-456-789.
branch_code string This is the last 3 digits after your TIN. If your TIN is 123-456-789-100, your Branch Code is 100.
rdo string Revenue District Office - a sector under BIR that keeps the records of taxpayers under its jurisdiction. See list of RDO Codes.

Response Body

Field Type Description
code number Returns the status codes like 200, 400, etc.
description string Name of the status code.
detail string Detailed status message.
type string Classification of the Organization (Values: individual or non-individual); See Organization Classification.
registered_name string Registered Name of the Organization if type is Non-Individual
Trade Name of the Organization if type is Individual. This is optional for Individual type.
first_name string First Name of the Organization if type is Individual.
middle_name string Middle Name of the Organization if type is Individual.
last_name string Surname of the Organization if type is Individual.
address string Address of the organization.
city string City where the organization is based out of.
zip_code string Zip Code of the Region where the organization is based out of.
region string Name of the Region where the organization is based out of.
phone string Contact Number of the organization.
email string Email Address of the Organization.
tin string Tax Identification Number of the Organization. This is the first 9 digits of your TIN. If your TIN is 123-456-789-100, your actual TIN is 123-456-789.
branch_code string This is the last 3 digits after your TIN. If your TIN is 123-456-789-100, your Branch Code is 100.
rdo string Revenue District Office - a sector under BIR that keeps the records of taxpayers under its jurisdiction. See list of RDO Codes.
financial_year_end date Period end of a fiscal/calendar year (Ex: December).
line_of_business string Products or services offered by a business. See Line of Business.

Request URL:

https://api.juan.tax.com/organizations/fa9hgt20-73aa-4c4c-a88c-065jj468a635/

Example Request Body:

{
  "phone": "111222333",
  "email": "test@test.com"
}

Example Response Body:

{
  "type": "non-individual",
  "registered_name": "Test 2551Q",
  "address": "ABC St",
  "city": "Makati",
  "zip_code": "1234",
  "region": "NCR",
  "phone": "111222333",
  "email": "test@test.com",
  "tin": "231-456-526",
  "branch_code": "781",
  "rdo": "050",
  "financial_year_end": "December",
  "line_of_business": "Preparation of coffee, cacao and cocoa beans"
}

Example Server Response:

Code Description
200 The request was successful.

Reports

GET

Returns list of reports generated on an organization.

Request Body

Field Type Description
organization_id string Unique identifier of the Organization

Response Body

Field Type Description
code number Returns the status codes like 200, 400, etc.
description string Name of the status code.
detail string Detailed status message.
report_id string Unique identifier of the Report.
type string Type of the report. (Values: 1601C, 2551Q)
month string Month of the report generated.
organization_id string Unique identifier of the Organization
organization_name string Registered Name of the Organization if type is Non-Individual; Trade name or Full Name of the Organization if type is Individual.
year string Year of the report generated.
is_filed boolean To check if the report is filed.
is_amended boolean To check if the report is amended.
status string Will be set to 1 if report is ACTIVE.

Request URL:

https://api.juan.tax.com/reports/8b806bba-2022-4f1d-aa70-852f85d20d45/

Example Response Body:

[
  {
    "report_id": "3201a577-0d53-491d-b179-74023cc9b4fb",
    "type": "1601C",
    "month": "January",
    "organization_id": "8b806bba-2022-4f1d-aa70-852f85d20d45",
    "organization_name": "Test Organization",
    "year": "2019",
    "is_filed": false,
    "is_amended": false,
    "status": 1
  }
]

Example Server Response:

Code Description
200 The request was successful.

Form 1601-C

Form 1601-C or Monthly Remittance Return of Income Taxes Withheld on Compensation is filed by a Withholding Agent who deducts and withhold taxes on compensation paid to employees.

You can learn more about Form 1601-C here.

POST

Creates a Monthly Remittance Return of Income Taxes Withheld on Compensation with a unique ID which will be referenced in its Organization.

Request Body

Field Type Description
is_amended boolean Optional. To check if the report is amended. Default value is False.
amended_count number Optional. Total number of times the report has been amended.
withholding_agent string Category of Withholding Agent (Values: private, government).
tax_relief boolean Optional. To check if Tax Relief will be availed. Default value is False.
tax_relief_options string Optional. Selected Tax Treaty (Values: Special Law, International Tax Treaty, Both).
schedule_1 object[] Optional. Shows details of Schedule 1 - Adjustment of Taxes Withheld on Compensation from Previous Months. For any amendments, please include correct number of schedule 1 rows. e.g., If you have 3 rows of schedule 1 and you need to update any of the lines, note that you still need to include all rows.
      previous_month string Month and Year that has Adjustments (Ex: 01/2021).
      date_paid string Date of payment (Ex: 01/20/2021).
      drawee_bank string Drawee Bank/Bank Code/Agency.
      number string
      tax_paid number Total Tax Paid (Excluding Penalties for the Month).
      tax_due number Should be Tax Due for the Month.
total_compensation number Optional. Item 14 - Total Amount of Compensation.
statutory_minimum_wage number Optional. Item 15 - Total Amount of Statutory Minimum Wage for Minimum Wage Earners (MWEs).
holiday_overtime_night_hazard_pay number Optional. Item 16 - Total amount of Holiday Pay, Overtime Pay, Night Shift Differential, and Hazard Pay for MWEs only.
thirteen_month_pay number Optional. Item 17 - Total Amount of 13th Month Pay and Other Benefits.
de_minimis_benefits number Optional. Item 18 - Total Amount of De Minimis Benefits.
sss_gsis_phic_hdmf number Optional. Item 19 - Total Amount of SSS, GSIS, PHIC, HDMF Mandatory Contributions & Unions Dues (employee’s shares only).
other_nontaxable_compensation number Optional. Item 20 - Total Amount of Other Non-Taxable Compensation.
other_nontaxable_compensation_description string Optional. Description of Other Non-Taxable Compensation.
taxable_compensation_no_withholding number Optional. Item 23 - Taxable compensation not subject to withholding tax (for employees, other than MWEs receiving 250,000 & below for the year).
total_taxes_withheld number Optional. Item 25 - Total Taxes Withheld.
other_remittances number Optional. Item 29 - Other Remittances Made.
other_remittances_description string Optional. Description of Other Remittances Made.
tax_remitted_previous_return number Optional. Item 28 - Tax Remitted in Return Previously Filed, if this is an amended return.
penalties object[] Optional. Shows details of Penalties for late filing of Tax Returns.
      surcharge number NIRC SEC. 248. - Civil Penalties.
      interest number NIRC SEC. 249. Interest.
      compromise number NIRC SEC. 255. Failure to File Return, Supply Correct and Accurate Information, Pay Tax Withhold and Remit Tax and Refund Excess Taxes Withheld on Compensation.
organization_id string Unique identifier of the Organization.
month string Tax month of form 1601-C to be filed (Values: January, February, March,…).
year string Tax year of form 1601-C to be filed (Values: 2019, 2020, 2021).

Response Body

Field Type Description
code number Returns the status codes (200, 400, etc.).
description string Name of the status code.
detail string Detailed status message.
report_id string Unique identifier of the Report.
report object[] Shows details of the Report.
      is_amended boolean To check if the report is amended.
      amended_count number Total number of times the report has been amended.
      withholding_agent string Category of Withholding Agent (Values: private, government).
      tax_relief boolean To check if Tax Relief will be availed.
      tax_relief_options string Selected Tax Treaty (Values: Special Law, International Tax Treaty, Both).
      schedule_1 object[] Shows details of Schedule 1 - Adjustment of Taxes Withheld on Compensation from Previous Months.
            previous_month string Month and Year that has Adjustments (Ex: 01/2021).
            date_paid string Date of payment (Ex: 01/20/2021).
            drawee_bank string Drawee Bank/Bank Code/Agency.
            number string Reference number of the payment made.
            tax_paid number Total Tax Paid (Excluding Penalties for the Month).
            tax_due number Should be Tax Due for the Month.
      total_compensation number Item 14 - Total Amount of Compensation.
      statutory_minimum_wage number Item 15 - Total Amount of Statutory Minimum Wage for Minimum Wage Earners (MWEs).
      holiday_overtime_night_hazard_pay number Item 16 - Total amount of Holiday Pay, Overtime Pay, Night Shift Differential, and Hazard Pay for MWEs only.
      thirteen_month_pay number Item 17 - Total Amount of 13th Month Pay and Other Benefits.
      de_minimis_benefits number Item 18 - Total Amount of De Minimis Benefits.
      sss_gsis_phic_hdmf number Item 19 - Total Amount of SSS, GSIS, PHIC, HDMF Mandatory Contributions & Unions Dues (employee’s shares only).
      other_nontaxable_compensation number Item 20 - Total Amount of Other Non-Taxable Compensation.
      other_nontaxable_compensation_description string Description of Other Non-Taxable Compensation.
      taxable_compensation_no_withholding number Item 23 - Taxable compensation not subject to withholding tax (for employees, other than MWEs receiving 250,000 & below for the year).
      total_taxes_withheld number Item 25 - Total Taxes Withheld.
      other_remittances number Item 29 - Other Remittances Made.
      other_remittances_description string Description of Other Remittances Made.
      tax_remitted_previous_return number Item 28 - Tax Remitted in Return Previously Filed, if this is an amended return.
      penalties object[] Shows details of Penalties for late filing of Tax Returns.
            surcharge number NIRC SEC. 248. - Civil Penalties.
            interest number NIRC SEC. 249. Interest.
            compromise number NIRC SEC. 255. Failure to File Return, Supply Correct and Accurate Information, Pay Tax Withhold and Remit Tax and Refund Excess Taxes Withheld on Compensation.
      organization_id string Unique identifier of the Organization.
      month string Tax month of form 1601-C to be filed (Values: January, February, March,…).
      year string Tax year of form 1601-C to be filed (Values: 2019, 2020, 2021).

Request URL:

https://api.juan.tax.com/reports/1601C/

Example Request Body:

{
  "withholding_agent": "private",
  "total_compensation": 10000,
  "statutory_minimum_wage": 500,
  "holiday_overtime_night_hazard_pay": 100,
  "thirteen_month_pay": 5000,
  "organization_id": "d2fdc221-877e-4a2f-8ae1-01f94bd7d63b",
  "month": "January",
  "year": "2019"
}

Example Response Body:

{
  "report_id": "02b67eb5-eb31-4e77-a519-4ef2394f2915",
  "report": {
    "is_amended": null,
    "amended_count": null,
    "withholding_agent": "private",
    "tax_relief": null,
    "tax_relief_options": null,
    "schedule_1": null,
    "total_compensation": 10000,
    "statutory_minimum_wage": 500,
    "holiday_overtime_night_hazard_pay": 100,
    "thirteen_month_pay": 5000,
    "de_minimis_benefits": null,
    "sss_gsis_phic_hdmf": null,
    "other_nontaxable_compensation": null,
    "other_nontaxable_compensation_description": null,
    "taxable_compensation_no_withholding": null,
    "total_taxes_withheld": null,
    "other_remittances": null,
    "other_remittances_description": null,
    "tax_remitted_previous_return": null,
    "penalties": null,
    "organization_id": "d2fdc221-877e-4a2f-8ae1-01f94bd7d63b",
    "month": "January",
    "year": "2019"
  }
}

Example Server Response:

Code Description
200 The request was successful.

PUT

Updates data of 1601-C report.

Request Body

Field Type Description
report_id string Unique identifier of the Report.
is_amended boolean To check if the report is amended.
amended_count number Total number of times the report has been amended.
withholding_agent string Category of Withholding Agent (Values: private, government).
tax_relief boolean To check if Tax Relief will be availed.
tax_relief_options string Selected Tax Treaty (Values: Special Law, International Tax Treaty, Both).
schedule_1 object[] Optional. Shows details of Schedule 1 - Adjustment of Taxes Withheld on Compensation from Previous Months. For any amendments, please include correct number of schedule 1 rows. e.g., If you have 3 rows of schedule 1 and you need to update any of the lines, note that you still need to include all rows.
      previous_month string Month and Year that has Adjustments (Ex: 01/2021).
      date_paid string Date of payment (Ex: 01/20/2021).
      drawee_bank string Drawee Bank/Bank Code/Agency.
      number string
      tax_paid number Total Tax Paid (Excluding Penalties for the Month).
      tax_due number Should be Tax Due for the Month.
total_compensation number Optional. Item 14 - Total Amount of Compensation.
statutory_minimum_wage number Optional. Item 15 - Total Amount of Statutory Minimum Wage for Minimum Wage Earners (MWEs).
holiday_overtime_night_hazard_pay number Optional. Item 16 - Total amount of Holiday Pay, Overtime Pay, Night Shift Differential, and Hazard Pay for MWEs only.
thirteen_month_pay number Optional. Item 17 - Total Amount of 13th Month Pay and Other Benefits.
de_minimis_benefits number Optional. Item 18 - Total Amount of De Minimis Benefits.
sss_gsis_phic_hdmf number Optional. Item 19 - Total Amount of SSS, GSIS, PHIC, HDMF Mandatory Contributions & Unions Dues (employee’s shares only).
other_nontaxable_compensation number Optional. Item 20 - Total Amount of Other Non-Taxable Compensation.
other_nontaxable_compensation_description string Optional. Description of Other Non-Taxable Compensation.
taxable_compensation_no_withholding number Optional. Item 23 - Taxable compensation not subject to withholding tax (for employees, other than MWEs receiving 250,000 & below for the year).
total_taxes_withheld number Optional. Item 25 - Total Taxes Withheld.
other_remittances number Optional. Item 29 - Other Remittances Made.
other_remittances_description string Optional. Description of Other Remittances Made.
tax_remitted_previous_return number Optional. Item 28 - Tax Remitted in Return Previously Filed, if this is an amended return.
penalties object[] Optional. Shows details of Penalties for late filing of Tax Returns.
      surcharge number NIRC SEC. 248. - Civil Penalties.
      interest number NIRC SEC. 249. Interest.
      compromise number NIRC SEC. 255. Failure to File Return, Supply Correct and Accurate Information, Pay Tax Withhold and Remit Tax and Refund Excess Taxes Withheld on Compensation.

Response Body

Field Type Description
code number Returns the status codes (200, 400, etc.).
description string Name of the status code.
detail string Detailed status message.
report_id string Unique identifier of the Report.

Request URL:

https://api.juan.tax.com/reports/1601C/99ac9328-23a4-44bd-a931-fcebfccd7a57/

Example Request Body:

{
  "is_amended": false,
  "amended_count": 0,
  "withholding_agent": "private",
  "tax_relief": false,
  "tax_relief_options": "",
  "schedule_1": [
    {
      "previous_month": "03/2019",
      "date_paid": "01/21/2019",
      "drawee_bank": "Bank",
      "number": "1234",
      "tax_paid": 100,
      "tax_due": 200
    },
    {
      "previous_month": "04/2019",
      "date_paid": "02/10/2019",
      "drawee_bank": "Bank",
      "number": "12345",
      "tax_paid": 200,
      "tax_due": 300
    },
    {
      "previous_month": "05/2019",
      "date_paid": "02/10/2019",
      "drawee_bank": "Bank",
      "number": "12345",
      "tax_paid": 200,
      "tax_due": 300
    }
  ],
  "total_compensation": 10000,
  "statutory_minimum_wage": 500,
  "holiday_overtime_night_hazard_pay": 100,
  "thirteen_month_pay": 5000,
  "organization_id": "d2fdc221-877e-4a2f-8ae1-01f94bd7d63b",
  "month": "January",
  "year": "2019"
}

Example Response Body:

{
  "report_id": "99ac9328-23a4-44bd-a931-fcebfccd7a57",
  "time": "2021-11-17T15:32:56.564595"
}

Example Server Response:

Code Description
200 The request was successful.

Form 2551Q

BIR Form 2551Q, or also known as Quarterly Percentage Tax Return are taxes imposed on individuals/businesses who sell/lease goods or services which are exempted from Value Added Tax (VAT) with annual sales not exceeding 3,000,000 PHP.

Currently, the updated version of this form comes with additional ATCs (Alphanumeric Tax Code) such as PT010, PT040, and many others.

You can learn more about Form 2551Q here.

POST

Creates a Quarterly Percentage Tax Return with a unique ID which will be referenced in its Organization.

Request Body

Field Type Description
income_tax_type string Income Tax Rate the taxpayer is availing (Values: Graduated, 8% Income Tax).
creditable_percentage_tax_withheld number Optional. Creditable Percentage Tax Withheld per BIR Form No. 2307.
tax_paid_previously_filed number Optional. Tax Paid in Return Previously Filed, if this is an Amended Return.
other_tax_credit_payment object[] Optional. Shows details of Other Tax Credit Payments.
      description string Specified by the taxpayer. Description or label of the Tax Credit Payment.
      amount number Amount of Other Tax Credit paid.
schedule_1 object[] Optional. Shows details of Schedule 1 - Computation of Tax. For any amendments, please include correct number of schedule 1 rows. e.g., If you have 3 rows of schedule 1 and you need to update any of the lines, note that you still need to include all rows.
      atc_code string Alphanumeric Tax Code - Organization’s Tax Code based on its industry (Values: PT 010 (CREATE), PT 040, PT 041, …).
      taxable_amount number Total gross amount including VAT.
overpayment string Optional. If there is an overpayment, options are Refund and Tax Credit.
penalties object[] Optional. Shows details of Penalties for late filing of Tax Returns.
      surcharge number NIRC SEC. 248. - Civil Penalties.
      interest number NIRC SEC. 249. Interest.
      compromise number NIRC SEC. 255. Failure to File Return, Supply Correct and Accurate Information, Pay Tax Withhold and Remit Tax and Refund Excess Taxes Withheld on Compensation.
organization_id string Unique identifier of the Organization.
quarter string Tax quarter of form 2551Q to be filed (Values: 1,2,3,4).
year string Tax year of form 2551Q to be filed (Values: 2019, 2020, 2021).

Response Body

Field Type Description
code number Returns the status codes (200, 400, etc.).
description string Name of the status code.
detail string Detailed status message.
report_id string Unique identifier of the Report.
report object[] Shows details of the Report.
      organization_id string Unique identifier of the Organization.
      quarter string Tax quarter of form 2551Q to be filed (Values: 1,2,3,4).
      year string Tax year of form 2551Q to be filed (Values: 2019, 2020, 2021).
      income_tax_type string Income Tax Rate the taxpayer is availing (Values: Graduated, 8% Income Tax).
      creditable_percentage_tax_withheld number Creditable Percentage Tax Withheld per BIR Form No. 2307.
      tax_paid_previously_filed number Tax Paid in Return Previously Filed, if this is an Amended Return.
      other_tax_credit_payment object[] Shows details of Other Tax Credit Payments.
            description string Specified by the taxpayer. Description or label of the Tax Credit Payment.
            amount number Amount of Other Tax Credit paid.
      schedule_1 object[] Shows details of Schedule 1 - Computation of Tax.
            atc_code string Alphanumeric Tax Code - Organization’s Tax Code based on its industry (Values: PT 010 (CREATE), PT 040, PT 041, …).
            taxable_amount number Total gross amount including VAT.
      overpayment string If there is an overpayment, options are Refund and Tax Credit.
      penalties object[] Shows details of Penalties for late filing of Tax Returns.
            surcharge number NIRC SEC. 248. - Civil Penalties.
            interest number NIRC SEC. 249. Interest.
            compromise number NIRC SEC. 255. Failure to File Return, Supply Correct and Accurate Information, Pay Tax Withhold and Remit Tax and Refund Excess Taxes Withheld on Compensation.

Request URL:

https://api.juan.tax.com/reports/2551Q/

Example Request Body:

{
  "organization_id": "fa9hgt20-73aa-4c4c-a88c-065jj468a635",
  "quarter": "1",
  "year": "2020",
  "income_tax_type": "Graduated",
  "schedule_1": [
    {
      "atc_code": "PT 010",
      "taxable_amount": 10000
    }
  ]
}

Example Response Body:

{
  "report_id": "73bb4295-f3ab-46e6-92b1-ce42c7e72729",
  "report": {
    "organization_id": "fa9hgt20-73aa-4c4c-a88c-065jj468a635",
    "quarter": "1",
    "year": "2020",
    "income_tax_type": "Graduated",
    "schedule_1": [
      {
        "atc_code": "PT 010",
        "taxable_amount": 10000
      }
    ]
  }
}

Example Server Response:

Code Description
200 The request was successful.

GET

Returns information about a 2551Q report.

Request Body

Field Type Description
report_id string Unique identifier of the Report

Response Body

Field Type Description
code number Returns the status codes (200, 400, etc.).
description string Name of the status code.
detail string Detailed status message.
oid string Unique identifier of the Report.
type string Type of the Report. In this case, 2551Q.
organization_id string Unique identifier of the Organization.
status string Will be set to 1 if report is ACTIVE.
month string Shows the first month of the Tax quarter of form 2551Q to be filed.
year string Tax year of form 2551Q to be filed (Values: 2019, 2020, 2021).
is_amended string To check if the report is amended.
amended_count number Total number of times the report has been amended.
is_filed string To check if the report is filed.
is_paid string To check if the report is paid.
report_date string Report Date generated for 2551Q form.
due_date string Due Date of the 2551Q form generated.
schedule_1 object[] Shows details of Schedule 1 - Computation of Tax.
      atc_code string Alphanumeric Tax Code - Organization’s Tax Code based on its industry (Values: PT 010 (CREATE), PT 040, PT 041, …)
      taxable_rate number Tax Rate of the ATC.
      taxable_amount number Total gross amount including VAT.
      tax_due number Total amount to be payed.
uuid string Unique Identifier
api boolean To check if the Organization is connected via the JuanTax API.

Request URL:

    https://api.juan.tax.com/reports/2551Q/73bb4295-f3ab-46e6-92b1-ce42c7e72729/

Example Response Body:

Example Server Response:

Code Description
200 The request was successful.

PUT

Updates data of 2551Q report.

Request Body

Field Type Description
report_id string Unique identifier of the Report.
income_tax_type string Income Tax Rate the taxpayer is availing (Values: Graduated, 8% Income Tax).
creditable_percentage_tax_withheld number Optional. Creditable Percentage Tax Withheld per BIR Form No. 2307.
tax_paid_previously_filed number Optional. Tax Paid in Return Previously Filed, if this is an Amended Return.
other_tax_credit_payment object[] Optional. Shows details of Other Tax Credit Payments.
      description string Specified by the taxpayer. Description or label of the Tax Credit Payment.
      amount number Amount of Other Tax Credit paid.
schedule_1 object[] Optional. Shows details of Schedule 1 - Computation of Tax. For any amendments, please include correct number of schedule 1 rows. e.g., If you have 3 rows of schedule 1 and you need to update any of the lines, note that you still need to include all rows.
      atc_code string Alphanumeric Tax Code - Organization’s Tax Code based on its industry (Values: PT 010 (CREATE), PT 040, PT 041, …).
      taxable_amount number Total gross amount including VAT.
overpayment string Optional. If there is an overpayment, options are Refund and Tax Credit.
penalties object[] Optional. Shows details of Penalties for late filing of Tax Returns.
      surcharge number NIRC SEC. 248. - Civil Penalties.
      interest number NIRC SEC. 249. Interest.
      compromise number NIRC SEC. 255. Failure to File Return, Supply Correct and Accurate Information, Pay Tax Withhold and Remit Tax and Refund Excess Taxes Withheld on Compensation.

Response Body

Field Type Description
code number Returns the status codes (200, 400, etc.).
description string Name of the status code.
detail string Detailed status message.
report_id string Unique identifier of the Report.
report object[] Shows details of the Report.
      organization_id string Unique identifier of the Organization.
      quarter string Tax quarter of form 2551Q to be filed (Values: 1,2,3,4).
      year string Tax year of form 2551Q to be filed (Values: 2019, 2020, 2021).
      income_tax_type string Income Tax Rate the taxpayer is availing (Values: Graduated, 8% Income Tax).
      creditable_percentage_tax_withheld number Creditable Percentage Tax Withheld per BIR Form No. 2307.
      tax_paid_previously_filed number Tax Paid in Return Previously Filed, if this is an Amended Return.
      other_tax_credit_payment object[] Shows details of Other Tax Credit Payments.
            description string Specified by the taxpayer. Description or label of the Tax Credit Payment.
            amount number Amount of Other Tax Credit paid.
      schedule_1 object[] Shows details of Schedule 1 - Computation of Tax.
            atc_code string Alphanumeric Tax Code - Organization’s Tax Code based on its industry (Values: PT 010 (CREATE), PT 040, PT 041, …).
            taxable_amount number Total gross amount including VAT.
      overpayment string If there is an overpayment, options are Refund and Tax Credit.
      penalties object[] Shows details of Penalties for late filing of Tax Returns.
            surcharge number NIRC SEC. 248. - Civil Penalties.
            interest number NIRC SEC. 249. Interest.
            compromise number NIRC SEC. 255. Failure to File Return, Supply Correct and Accurate Information, Pay Tax Withhold and Remit Tax and Refund Excess Taxes Withheld on Compensation.

Request URL:

https://api.juan.tax.com/reports/2551Q/

Example Request Body:

{
  "organization_id": "fa9hgt20-73aa-4c4c-a88c-065jj468a635",
  "quarter": "1",
  "year": "2020",
  "income_tax_type": "Graduated",
  "schedule_1": [
    {
      "atc_code": "PT 010",
      "taxable_amount": 10000
    }
  ]
}

Example Response Body:

Example Server Response:

Code Description
200 The request was successful.

Frequently Asked Questions (FAQs)

What Format are the Requests and Responses in?

How can I test an API?

What is the rate limit of the API?

Can we pay tax dues through API?

Can you help us with the coding?

Who can I contact for help?

Other References

This section provides reference to the list of types and codes that are valid within JuanTax API.

Organization Classification

A taxpayer is a person or organization subject to pay a tax. Taxpayers are classified into two major categories:

Classification Description
Individual Sole Proprietors, Self-employed/Freelancers, Professionals, Mixed Income Earners
Non-Individual Corporations, Partnerships

Organization Types

This lists the Tax type your Organization complies with.

Type Description
Percentage Tax A business tax imposed on persons or entities who sell or lease goods, properties or services in the course of trade or business whose gross annual sales or receipts do not exceed the amount required to register as VAT-registered taxpayers.
Tax Exempt Applies if income, revenue as well as assets of your business is being used exclusively for educational, religious and charitable purposes only. Best examples of these includes: churches, mosque, convents and other non-profit organizations which are exempted from paying taxes.
Value Added Tax A business tax imposed and collected from the seller in the course of trade or business on every sale of properties (real or personal) lease of goods or properties (real or personal) or vendors of services. It is an indirect tax, thus, it can be passed on to the buyer.

RDO Codes

The BIR uses the below RDO Codes to track the amount of tax collection within a particular region and record and process tax returns, tax payments, and withholding taxes.

RDO Code District Office
001 Laoag City, Ilocos Norte
002 Vigan, Ilocos Sur
003 San Fernando, La Union
004 Calasiao, Central Pangasinan
005 Alaminos City, West Pangasinan
006 Urdaneta City, East Pangasinan
007 Bangued, Abra
008 Baguio City
009 La Trinidad, Benguet
010 Bontoc, Mt. Province
011 Tabuk City, Kalinga
012 Lagawe, Ifugao
013 Tuguegarao, Cagayan
014 Bayombong, Nueva Vizcaya
015 Naguilan, Isabela
016 Cabarroguis, Quirino
17A Tarlac, Tarlac City
17B Paniqui, Tarlac
018 Olongapo City
019 Subic Bay Freeport Zone
020 Balanga, Bataan
21A North Pampanga
21B South Pampanga
21C Clark Freeport Zone
022 Baler, Aurora
23A North Nueva Ecija
23B South Nueva Ecija
024 Valenzuela City
25A West Bulacan
25B East Bulacan
026 Malabon-Navotas
027 Caloocan City
028 Novaliches
029 Tondo-San Nicolas
030 Binondo
031 Sta. Cruz
032 Quiapo-Sampaloc-Sta. Mesa-San Miguel
033 Intramuros-Ermita-Malate
034 Paco-Pandacan-Sta. Ana-San Andres
035 Romblon
036 Puerto Princesa
037 San Jose, Occidental Mindoro
038 North Quezon City
039 South Quezon City
040 Cubao
041 Mandaluyong City
042 San Juan
043 Pasig
044 Taguig-Pateros
045 Marikina
046 Cainta/Taytay
047 East Makati
048 West Makati
049 North Makati
050 South Makati
051 Pasay City
052 Paranaque
53A Las Pinas City
53B Muntinlupa City
54A Trece Martirez City, East Cavite
54B Kawit, West Cavite
055 San Pablo City
056 Calamba, Laguna
057 Binan, Laguna
058 Batangas City
059 Lipa City
060 Lucena City
061 Gumaca, Quezon
062 Boac, Marinduque
063 Calapan, Oriental Mindoro
064 Talisay, Camarines Norte
065 Naga City
066 Iriga City
067 Legazpi City, Albay
068 Sorsogon, Sorsogon
069 Virac, Catanduanes
070 Masbate, Masbate
071 Kalibo, Aklan
072 Roxas City
073 San Jose, Antique
074 Iloilo City
075 Zarraga, Iloilo City
076 Victorias City, Negros Occidental
077 Bacolod City
078 Binalbagan, Negros Occidental
079 Dumaguete City
080 Mandaue City
081 Cebu City North
082 Cebu City South
083 Talisay, Cebu
084 Tagbilaran City
085 Catarman, Northern Samar
086 Borongan, Eastern Samar
087 Calbayog City, Samar
088 Tacloban City
089 Ormoc City
090 Maasin, Southern Leyte
091 Dipolog City
092 Pagadian City, Zamboanga del Sur
93A Zamboanga City, Zamboanga del Sur
93B Zamboanga Sibugay
094 Isabela, Basilan
095 Jolo, Sulu
096 Bongao, Tawi-Tawi
097 Gingoog City
098 Cagayan de Oro City
099 Malaybalay, Bukidnon
100 Ozamis City
101 Iligan City
102 Marawi City
103 Butuan City
104 Bayugan, Agusan del Sur
105 Surigao City
106 Tandag, Surigao del Sur
107 Cotabato City
108 Kidapawan, North Cotabato
109 Tacurong, Sultan Kudarat
110 General Santos City
111 Koronadal, South Cotabato
112 Tagum, Davao del Norte
113A West Davao City
113B East Davao City
114 Mati, Davao Oriental
115 Digos, Davao del Sur
116 Regular LT Audit Division 1
121 Excise LT Audit Division 1
122 Large Taxpayers Division - Makati
123 Large Taxpayers Division - Cebu
124 Excise LT Audit Division II
125 Regular LT Audit Division 11
126 Regular LT Audit Division III
127 LTDO, Davao
132 East Davao City

Line of Business

This is the list provided by the BIR but you can also indicate your own line of business.