API Reference

API Documentation

This document will help you get started with CloudTax API.

Overview

CloudTax is a NETFILE-certified, white-labelled platform-as-a-service (PaaS) solution, designed to simplify personal tax filing (T1) for Canadians. Our platform is certified by the Canada Revenue Agency (CRA) for secure and accurate tax filing.

Through the CloudTax API, you can embed our tax filing experience directly into your platform. Our API allows for pre-filling user data, handling complex tax calculations, and securely submitting returns to the CRA. Additionally, CloudTax offers a unique advantage: with user consent, partners can access and utilize tax data for deeper integration.

CloudTax prioritizes user data security by using industry-standard encryption protocols, ensuring all sensitive information is protected both in transit and at rest.

Let’s work together to deliver a smooth, secure, and efficient tax filing experience for Canadians, all from within your app.

Pre-Requisites

  1. Partner Onboarding: Complete the onboarding process as a new partner on the CloudTax platform.
  2. API Credentials: Obtain your API key and API secret, which are required to authenticate requests to the CloudTax API.

Steps

The integration flow is elaborated with the illustration below.

  1. Your user initiates Tax Filing somewhere in your web application
  2. In that event, your web application makes an HTTPS call to the CloudTax API endpoint.
    1. In this call, your application passes the following details of the user.
      (Mandatory fields marked with *)
      1. user_id
      2. user_email *
      3. tax_province
      4. personal_info
        1. first_name
        2. middle_name
        3. last_name
        4. date_of_birth
        5. social_insurance_number → The Social Insurance Number should be unique and should match the SIN pattern
        6. marital_status
      5. mailing_address
        1. address_line_1
        2. unit_no
        3. street_name
        4. city
        5. province
        6. postal_code
    2. The API key and the API secret should be passed in the Authorization header with the Basic Authentication scheme, as given below.
      1. Concatenate the API key, a colon (:) and the API Secret together. For example., apikey:apisecret
      2. Base64 encode the concatenated string. For example., the "apikey:apisecret" becomes "YXBpa2V5OmFwaXNlY3JldAo="
      3. Prefix the base64 encoded string with "Basic " and use it in the Authorization header. For example., "Authorization: Basic YXBpa2V5OmFwaXNlY3JldAo="
    3. CloudTax API checks whether the user exists on the system by using the given email id.
      1. If the user does not exist, it saves the incoming details on our database.
    4. Then, a Login URL with a token is generated.
  3. The above-generated URL is sent to your web application in the response body.
  4. Then, your web app can redirect the user to this URL.
    1. This redirect can be either client-side or server-side.
  5. Post redirection, the user lands on the CloudTax web app, and it uses the token in the URL to authenticate your user.
    1. After successful authentication, the user will be automatically logged in and can begin filing their taxes.
    2. Data import (such as name and mailing address) will occur only during the initial API call. If your client makes updates to your portal, we will not automatically update them.

API Specification

This endpoint allows users to generate a secure login URL based on their personal and address details. The API requires authentication using API_KEY:API_SECRET and returns a URL for the user to log in securely.

POST /api/user-login-url  
Host: cloudtax.ca  
Authorization: Basic <BASE64(API_KEY:API_SECRET)>  
Content-Type: application/json

{
    "user_id": "[email protected]",  
    "user_email": "[email protected]",  
    "tax_province": "ON",  
    "personal_info": {  
        "first_name": "Mary",  
        "middle_name": null,  
        "last_name": "Anne",  
        "date_of_birth": "1964-04-24",  
        "social_insurance_number": "870000007",  
        "marital_status": "married"  
    },  
   "mailing_address": {  
        "address_line_1": "RR 5",  
        "unit_no": null,  
        "street_name": null,  
        "city": "Almonte",  
        "province": "ON",  
        "postal_code": "K0A1A0"  
    }  
}

HTTP/1.1 200 OK  
Content-Type: application/json; charset=utf-8

{
    "login_url": "https://tax.yourbank.ca/2025/auth/login?token=<JSON_WEB_TOKEN>"  
}

Payload Schema

The payload schema defines the structure of the data required to generate the login URL. It includes user details such as personal information, mailing address, and tax province. Optional fields are marked accordingly.

type MaritalStatus = 'married' | 'common-law' | 'widowed' | 'divorced' | 'separated' | 'single';

type TaxProvince = 'AB' | 'BC' | 'MB' | 'NB' | 'NL' | 'NS' | 'NT' | 'NU' | 'ON' | 'PE' | 'SK' | 'YT';

interface PersonalInfo {
  first_name: string;
  middle_name?: string;
  last_name: string;
  date_of_birth?: string;
  social_insurance_number?: number;
  marital_status?: MaritalStatus;
}

interface MailingAddress {
  address_line_1?: string;
  unit_no: string;
  street_name: string;
  city: string;
  province: string;
  postal_code: string;
}

interface Payload {
  user_id: string;
  user_email: string;
  tax_province?: TaxProvince;
  year?: number;
  personal_info?: PersonalInfo;
  mailing_address?: MailingAddress;
}

Data Retrieval Process for Individual and Bulk Users

The data retrieval process allows users to request tax-related information for both individual and bulk users via the API. Here's a summary:

Individual User Retrieval:

  • When an individual user's tax data is requested, the API retrieves detailed information such as the taxpayer's name, SIN, birthdate, marital status, address, income details, and relevant tax lines (e.g., Line10100 for employment income, Line13000 for other income).
  • The response includes current and past-year tax data, marital status, residency information, and key tax lines for income and deductions, ensuring the user has a comprehensive overview of their tax details.

Bulk User Retrieval:

  • The API supports batch requests, retrieving multiple users' tax data simultaneously. Each record includes fields similar to individual retrieval (e.g., name, SIN, tax details, income lines).
  • The bulk data is returned in a structured format, enabling efficient handling and processing of large datasets without sacrificing performance or detail.

Both processes return structured JSON objects, with error codes and messages provided to indicate success or highlight issues during the retrieval process.

Admin Panel for Real-Time User Management

In addition to the API, CloudTax offers an admin panel that provides partners with real-time management and viewing capabilities for user information. Through this panel, you can:

  • Manage registered users
  • View filed, failed, and not-submitted returns
  • Monitor refiled returns

Additionally, the admin panel allows partners to view the full tax return details for any of their registered users, providing a comprehensive real-time overview of the entire filing process.

The following example focuses on retrieving information for the T1 General portion of the tax return. However, additional data can be provided upon partner request in a similar format, allowing for flexibility based on specific needs.

GET /api/user/:userid  // For bulk users, GET /api/user/list)
Host: cloudtax.ca  
Authorization: Basic \<BASE64(API_KEY:API_SECRET)>  
Content-Type: application/json

HTTP/1.1 200 OK  
Content-Type: application/json; charset=utf-8

   {
    "TaxPayerName": "Mary Anne",
    "TaxPayerSocialInsuranceNumber": "870000007",
    "TaxPayerBirthDate": "1964-04-24",
    "TaxPayerMaritalStatusCode": 1,
    "Year": 2023,
    "TaxPayerMiddleName": null,
    "TaxPayerLastName": "ONE",
    "SelfEmployedSpouseDeadlineIndicator": 0,
    "AddressCareOfLineText": null,
    "UnitNo": null,
    "AddressLine2": null,
    "City": "Almonte",
    "Province": "ON",
    "PostalCode": "K0A1A0",
    "CurrentResidence": null,
    "StreetName": "RR 5",
    "Email": "[email protected]",
    "HomePhoneNumber": "(613) 5264545",
    "CorrespondenceLanguageCode": 1,
    "SpouseGivenName": "William",
    "SpouseLastName": "One",
    "SpouseSocialInsuranceNumber": "870000015",
    "SpouseBirthDate": "1953-08-30",
    "SpouseNetincomeAmount": 9000,
    "ResProvince": "ON",
    "SelfEmpProvince": null,
    "ImmigrantEntryDate": null,
    "ImmigrantExitDate": null,
    "CanadianCitizenStatus": "1",
    "CRAAuthorizedStatus": "02",
    "SpecifiedForeignPropertyStatus": "N",
    "Line10100": 90000,
    "Line10105": 0,
    "Line10120": 0,
    "Line10130": 0,
    "Line10400": 0,
    "Line11300": 0,
    "Line11400": 0,
    "Line11410": 0,
    "Line11500": 0,
    "Line11600": 0,
    "Line11700": 0,
    "Line11701": 0,
    "Line11900": 0,
    "Line11905": 0,
    "Line12000": 0,
    "Line12010": 0,
    "Line12100": 22000,
    "Line12200": 0,
    "Line12500": 0,
    "Line12599": 0,
    "Line12600": 0,
    "Line12700": 0,
    "Line12799": 0,
    "Line12800": 0,
    "Line12900": 0,
    "Line12905": 0,
    "Line12906": 0,
    "Line13000": 0,
    "Line13010": 0,
    "Line13499": 0,
    "Line13500": 0,
    "Line13699": 0,
    "Line13700": 0,
    "Line13899": 51800,
    "Line13900": 28600,
    "Line14099": 0,
    "Line14100": 0,
    "Line14299": 0,
    "Line14300": 0,
    "Line14400": 0,
    "Line14500": 0,
    "Line14600": 0,
    "Line14700": 0,
    "Line15000": 140600,
    "Line20600": 1500,
    "Line20700": 900,
    "Line20800": 0,
    "Line20805": 0,
    "Line20810": 0,
    "Line21000": 0,
    "Line21200": 300,
    "Line21300": 0,
    "Line21400": 5400,
    "Line21500": 0,
    "Line21699": 0,
    "Line21700": 0,
    "Line21900": 0,
    "Line21999": 0,
    "Line22000": 0,
    "Line22100": 0,
    "Line22200": 0,
    "Line22215": 119.18,
    "Line22400": 0,
    "Line22900": 0,
    "Line23100": 0,
    "Line23200": 500,
    "Line23300": 7219.18,
    "Line23400": 133380.82,
    "Line23500": 0,
    "Line23600": 133380.82,
    "Line24400": 0,
    "Line24900": 0,
    "Line25000": 0,
    "Line25100": 0,
    "Line25200": 0,
    "Line25300": 0,
    "Line25400": 0,
    "Line25500": 0,
    "Line25600": 0,
    "Line25700": 0,
    "Line26000": 133380.82,
    "Line42000": 19724.88,
    "Line42100": 0,
    "Line42200": 0,
    "Line42800": 12112.48,
    "Line43500": 31837.36,
    "Line43700": 29450,
    "Line44000": 0,
    "Line44800": 0,
    "Line45000": 0,
    "Line45200": 0,
    "Line45300": 0,
    "Line45400": 0,
    "Line45600": 0,
    "Line45700": 0,
    "Line46800": 0,
    "Line46900": 0,
    "Line47555": 0,
    "Line47556": 0,
    "Line47557": 0,
    "Line47600": 0,
    "Line47900": 1539,
    "Line48200": 30989,
    "Line48200A": 848.36,
    "Line48400": 0,
    "Line48500": 848.36,
    "Line26600": 2,
    "Line49000": 2,
    "Line48800": 0,
    "Line46500": 0
  }