freee HR Payroll API

openapi: 3.0.3
info:
  title: freee API (Accounting and HR/Payroll)
  description: >-
    A representative, hand-authored subset of the public freee REST APIs for the
    freee Accounting product (会計freee) and the freee HR & Payroll product
    (人事労務freee). freee is a Japanese cloud accounting, invoicing, and HR /
    payroll SaaS. Accounting endpoints live under
    https://api.freee.co.jp/api/1 and HR / payroll endpoints under
    https://api.freee.co.jp/hr/api/v1. All requests are authenticated with an
    OAuth 2.0 (authorization code) access token sent as
    `Authorization: Bearer <access_token>`. Most reads and writes are scoped to
    a freee company via the `company_id` parameter. This document is grounded in
    freee's own OpenAPI schemas (github.com/freee/freee-api-schema) but is a
    curated subset - it does not reproduce every operation, field, or response
    of the freee platform. See the official reference for the complete surface.
  version: '2026-02-01'
  contact:
    name: freee Developers Community
    url: https://developer.freee.co.jp/
  license:
    name: © Since 2013 freee K.K.
    url: https://app.secure.freee.co.jp/developers/terms
servers:
  - url: https://api.freee.co.jp
    description: freee production API host (accounting under /api/1, HR under /hr/api/v1)
security:
  - oauth2:
      - read
      - write
tags:
  - name: Companies
    description: freee companies (事業所) the authenticated user can access.
  - name: Deals
    description: Accounting deals / transactions (取引) - income and expense records.
  - name: Account Items
    description: Accounting account items / chart of accounts (勘定科目).
  - name: Partners
    description: Trading partners / counterparties (取引先).
  - name: Invoices
    description: Issued invoices and quotations (請求書・見積書).
  - name: Wallet Transactions
    description: Wallet transactions / statement lines (明細) and walletables (口座).
  - name: Journals
    description: Journals (仕訳帳), manual journals, and trial-balance reports.
  - name: Taxes
    description: Tax codes (税区分) available to a company.
  - name: HR Users
    description: Authenticated HR user context.
  - name: Employees
    description: HR employees (従業員).
  - name: Payroll
    description: Employee payroll statements (給与明細) and bonuses.
  - name: Attendance
    description: Time clocks (打刻) and work records (勤怠).
paths:
  /api/1/companies:
    get:
      operationId: getCompanies
      tags: [Companies]
      summary: List companies
      description: Lists the freee companies (事業所) the authenticated user belongs to.
      responses:
        '200':
          description: A list of companies.
          content:
            application/json:
              schema:
                type: object
                properties:
                  companies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/companies/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: getCompany
      tags: [Companies]
      summary: Get a company
      description: Retrieves details, account items, taxes, and settings for one company.
      responses:
        '200':
          description: The requested company.
          content:
            application/json:
              schema:
                type: object
                properties:
                  company:
                    $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/1/deals:
    get:
      operationId: getDeals
      tags: [Deals]
      summary: List deals
      description: >-
        Lists accounting deals / transactions (取引) for a company. A deal is an
        income (収入) or expense (支出) record with one or more detail lines.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
        - name: partner_id
          in: query
          schema: { type: integer }
        - name: account_item_id
          in: query
          schema: { type: integer }
        - name: status
          in: query
          description: Settlement status.
          schema:
            type: string
            enum: [unsettled, settled]
        - name: type
          in: query
          schema:
            type: string
            enum: [income, expense]
        - name: start_issue_date
          in: query
          schema: { type: string, format: date }
        - name: end_issue_date
          in: query
          schema: { type: string, format: date }
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of deals.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deals:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deal'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDeal
      tags: [Deals]
      summary: Create a deal
      description: Creates a new accounting deal (取引).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealCreateParams'
      responses:
        '201':
          description: The created deal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deal:
                    $ref: '#/components/schemas/Deal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/deals/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: getDeal
      tags: [Deals]
      summary: Get a deal
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: The requested deal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deal:
                    $ref: '#/components/schemas/Deal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateDeal
      tags: [Deals]
      summary: Update a deal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealCreateParams'
      responses:
        '200':
          description: The updated deal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deal:
                    $ref: '#/components/schemas/Deal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDeal
      tags: [Deals]
      summary: Delete a deal
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '204':
          description: The deal was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/1/account_items:
    get:
      operationId: getAccountItems
      tags: [Account Items]
      summary: List account items
      description: Lists the account items / chart of accounts (勘定科目) for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: A list of account items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAccountItem
      tags: [Account Items]
      summary: Create an account item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, name]
              properties:
                company_id: { type: integer }
                name: { type: string }
                tax_code: { type: integer }
                account_category_id: { type: integer }
      responses:
        '201':
          description: The created account item.
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_item:
                    $ref: '#/components/schemas/AccountItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/account_items/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: getAccountItem
      tags: [Account Items]
      summary: Get an account item
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: The requested account item.
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_item:
                    $ref: '#/components/schemas/AccountItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAccountItem
      tags: [Account Items]
      summary: Update an account item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company_id: { type: integer }
                name: { type: string }
      responses:
        '200':
          description: The updated account item.
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_item:
                    $ref: '#/components/schemas/AccountItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteAccountItem
      tags: [Account Items]
      summary: Delete an account item
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '204':
          description: The account item was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/partners:
    get:
      operationId: getPartners
      tags: [Partners]
      summary: List partners
      description: Lists trading partners / counterparties (取引先) for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
        - name: keyword
          in: query
          schema: { type: string }
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of partners.
          content:
            application/json:
              schema:
                type: object
                properties:
                  partners:
                    type: array
                    items:
                      $ref: '#/components/schemas/Partner'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPartner
      tags: [Partners]
      summary: Create a partner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, name]
              properties:
                company_id: { type: integer }
                name: { type: string }
                code: { type: string }
      responses:
        '201':
          description: The created partner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  partner:
                    $ref: '#/components/schemas/Partner'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/partners/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: getPartner
      tags: [Partners]
      summary: Get a partner
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: The requested partner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  partner:
                    $ref: '#/components/schemas/Partner'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updatePartner
      tags: [Partners]
      summary: Update a partner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company_id: { type: integer }
                name: { type: string }
      responses:
        '200':
          description: The updated partner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  partner:
                    $ref: '#/components/schemas/Partner'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deletePartner
      tags: [Partners]
      summary: Delete a partner
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '204':
          description: The partner was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/invoices:
    get:
      operationId: getInvoices
      tags: [Invoices]
      summary: List invoices
      description: Lists issued invoices (請求書) for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/invoices/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: getInvoice
      tags: [Invoices]
      summary: Get an invoice
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: The requested invoice.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/1/quotations:
    get:
      operationId: getQuotations
      tags: [Invoices]
      summary: List quotations
      description: Lists issued quotations / estimates (見積書) for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: A list of quotations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  quotations:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/wallet_txns:
    get:
      operationId: getWalletTxns
      tags: [Wallet Transactions]
      summary: List wallet transactions
      description: Lists wallet transactions / statement lines (明細) for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
        - name: walletable_type
          in: query
          schema:
            type: string
            enum: [bank_account, credit_card, wallet]
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of wallet transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet_txns:
                    type: array
                    items:
                      $ref: '#/components/schemas/WalletTxn'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWalletTxn
      tags: [Wallet Transactions]
      summary: Create a wallet transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, entry_side, amount, date, walletable_type, walletable_id]
              properties:
                company_id: { type: integer }
                entry_side:
                  type: string
                  enum: [income, expense]
                amount: { type: integer }
                date: { type: string, format: date }
                walletable_type:
                  type: string
                  enum: [bank_account, credit_card, wallet]
                walletable_id: { type: integer }
      responses:
        '201':
          description: The created wallet transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet_txn:
                    $ref: '#/components/schemas/WalletTxn'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/wallet_txns/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: getWalletTxn
      tags: [Wallet Transactions]
      summary: Get a wallet transaction
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: The requested wallet transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet_txn:
                    $ref: '#/components/schemas/WalletTxn'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWalletTxn
      tags: [Wallet Transactions]
      summary: Delete a wallet transaction
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '204':
          description: The wallet transaction was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/walletables:
    get:
      operationId: getWalletables
      tags: [Wallet Transactions]
      summary: List walletables
      description: Lists walletables (口座) - bank accounts, credit cards, and wallets - for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
        - name: type
          in: query
          schema:
            type: string
            enum: [bank_account, credit_card, wallet]
      responses:
        '200':
          description: A list of walletables.
          content:
            application/json:
              schema:
                type: object
                properties:
                  walletables:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/journals:
    get:
      operationId: getJournals
      tags: [Journals]
      summary: Request a journals export
      description: >-
        Starts an asynchronous export of journals (仕訳帳) for a company in CSV,
        PDF, or freee's yayoi format. Poll the reports status / download
        endpoints for the generated file.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
        - name: download_type
          in: query
          schema:
            type: string
            enum: [csv, pdf, yayoi, generic_v2]
        - name: start_date
          in: query
          schema: { type: string, format: date }
        - name: end_date
          in: query
          schema: { type: string, format: date }
      responses:
        '202':
          description: The export request was accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  journals:
                    type: object
                    properties:
                      id: { type: integer }
                      company_id: { type: integer }
                      download_type: { type: string }
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/manual_journals:
    get:
      operationId: getManualJournals
      tags: [Journals]
      summary: List manual journals
      description: Lists manual journal entries (振替伝票) for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
      responses:
        '200':
          description: A list of manual journals.
          content:
            application/json:
              schema:
                type: object
                properties:
                  manual_journals:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createManualJournal
      tags: [Journals]
      summary: Create a manual journal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, issue_date, details]
              properties:
                company_id: { type: integer }
                issue_date: { type: string, format: date }
                details:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        '201':
          description: The created manual journal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  manual_journal:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/reports/trial_pl:
    get:
      operationId: getTrialPl
      tags: [Journals]
      summary: Get profit and loss trial balance
      description: Returns the profit-and-loss trial balance (試算表・損益計算書) for a company.
      parameters:
        - $ref: '#/components/parameters/CompanyIdQueryRequired'
        - name: fiscal_year
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: The P&L trial balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  trial_pl:
                    type: object
                    additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/1/taxes/codes:
    get:
      operationId: getTaxCodes
      tags: [Taxes]
      summary: List tax codes
      description: Lists the tax codes / tax classifications (税区分) available in freee.
      responses:
        '200':
          description: A list of tax codes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  taxes:
                    type: array
                    items:
                      type: object
                      properties:
                        code: { type: integer }
                        name: { type: string }
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hr/api/v1/users/me:
    get:
      operationId: getHrMe
      tags: [HR Users]
      summary: Get current HR user
      description: >-
        Returns the authenticated user and the HR companies (事業所) they can
        access in freee人事労務.
      responses:
        '200':
          description: The current HR user.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hr/api/v1/employees:
    get:
      operationId: getEmployees
      tags: [Employees]
      summary: List employees
      description: Lists employees (従業員) for an HR company and month.
      parameters:
        - name: company_id
          in: query
          required: true
          schema: { type: integer }
        - name: year
          in: query
          schema: { type: integer }
        - name: month
          in: query
          schema: { type: integer }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of employees.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEmployee
      tags: [Employees]
      summary: Create an employee
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, employee]
              properties:
                company_id: { type: integer }
                employee:
                  type: object
                  additionalProperties: true
      responses:
        '201':
          description: The created employee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hr/api/v1/employees/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: getEmployee
      tags: [Employees]
      summary: Get an employee
      parameters:
        - name: company_id
          in: query
          required: true
          schema: { type: integer }
        - name: year
          in: query
          schema: { type: integer }
        - name: month
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: The requested employee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateEmployee
      tags: [Employees]
      summary: Update an employee
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company_id: { type: integer }
                employee:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The updated employee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteEmployee
      tags: [Employees]
      summary: Delete an employee
      parameters:
        - name: company_id
          in: query
          required: true
          schema: { type: integer }
      responses:
        '204':
          description: The employee was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hr/api/v1/salaries/employee_payroll_statements:
    get:
      operationId: getEmployeePayrollStatements
      tags: [Payroll]
      summary: List employee payroll statements
      description: >-
        Lists employee salary payroll statements (給与明細) for an HR company and
        pay month.
      parameters:
        - name: company_id
          in: query
          required: true
          schema: { type: integer }
        - name: year
          in: query
          required: true
          schema: { type: integer }
        - name: month
          in: query
          required: true
          schema: { type: integer }
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of payroll statements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  employee_payroll_statements:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hr/api/v1/employees/{employee_id}/time_clocks:
    parameters:
      - name: employee_id
        in: path
        required: true
        schema: { type: integer }
    get:
      operationId: getTimeClocks
      tags: [Attendance]
      summary: List time clocks
      description: Lists an employee's time-clock punches (打刻).
      parameters:
        - name: company_id
          in: query
          required: true
          schema: { type: integer }
        - name: from_date
          in: query
          schema: { type: string, format: date }
        - name: to_date
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: A list of time clocks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeClock'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTimeClock
      tags: [Attendance]
      summary: Register a time clock
      description: Registers a time-clock punch (clock in / out / break) for an employee.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [company_id, type]
              properties:
                company_id: { type: integer }
                type:
                  type: string
                  enum: [clock_in, break_begin, break_end, clock_out]
                datetime: { type: string }
                base_date: { type: string, format: date }
      responses:
        '201':
          description: The registered time clock.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeClock'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /hr/api/v1/employees/{employee_id}/work_records/{date}:
    parameters:
      - name: employee_id
        in: path
        required: true
        schema: { typ

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/freee/refs/heads/main/openapi/freee-openapi.yml