# FreshBooks

> Invoicing and accounting for small businesses. Manage clients, create, send and track invoices and estimates, record payments and expenses, and log time on projects.

App · 27 actions. Web page: https://docs.lodol.com/docs/integrations/freshbooks

## Actions

### Create client

Add a client: a company or person you bill. Give at least a company, a name or an email address.

**Inputs**

- First name (`first_name`, text): The contact's first name.
- Last name (`last_name`, text): The contact's last name.
- Company (`organization`, text): The client's company or organization name.
- Email (`email`, text): Where invoices and estimates are sent.
- Phone (`phone`, text): The business phone number.
- Mobile phone (`mobile_phone`, text): The mobile phone number.
- Currency (`currency`, text): The currency the client is billed in.
- Street (`street`, text): Billing address: street.
- Street line 2 (`street2`, text): Billing address: second line.
- City (`city`, text): Billing address: city.
- State or province (`province`, text): Billing address: state or province.
- Postal code (`postal_code`, text): Billing address: ZIP or postal code.
- Country (`country`, text): Billing address: country, such as United States.
- Notes (`notes`, text): Your own notes about the client. Clients don't see them.

**Outputs**: A client

- `bus_phone` (text): Business phone
- `currency_code` (text): The currency the client is billed in
- `email` (text): Email address
- `fname` (text): First name
- `id` (number): The client's ID
- `language` (text): Language code for what they are sent, such as en
- `lname` (text): Last name
- `mob_phone` (text): Mobile phone
- `note` (text): Your notes about the client
- `organization` (text): Company name
- `p_city` (text): Billing city
- `p_code` (text): Billing postal code
- `p_country` (text): Billing country
- `p_province` (text): Billing state or province
- `p_street` (text): Billing street
- `p_street2` (text): Billing street, second line
- `signup_date` (text): When the client was added (UTC)
- `updated` (text): When the client was last changed
- `userid` (number): The client's ID again, as older endpoints name it
- `vat_name` (text): Tax number label, such as VAT
- `vat_number` (text): Tax number
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "bus_phone": "",
  "currency_code": "USD",
  "email": "email1@freshbooks.com",
  "fname": "first1",
  "id": 238951,
  "language": "en",
  "lname": "last1",
  "mob_phone": "",
  "note": null,
  "organization": "company1",
  "p_city": "Toronto",
  "p_code": "M6P 3T1",
  "p_country": "Canada",
  "p_province": "Ontario",
  "p_street": "1655 Dupont St. W.",
  "p_street2": "",
  "signup_date": "2022-01-05 12:17:11",
  "updated": "2022-01-05 07:17:12",
  "userid": 238951,
  "vat_name": null,
  "vat_number": "",
  "vis_state": 0
}
```

### Create estimate

Create a draft estimate (a quote) for a client, with one line or several.

**Inputs**

- Client (`client_id`, text, required): The client. Pick one, or give its ID from an earlier step.
- Estimate date (`estimate_date`, date): The date on the estimate. Leave empty for today.
- Currency (`currency`, text): Leave empty for the client's own currency.
- Item or service (`item`, text): Pick a saved item to fill in its name, description, price and taxes, or type what the line is for.
- Quantity (`quantity`, number): How many. Leave empty for 1. At least 0.
- Unit cost (`unit_cost`, number): The price of one. Leave empty to use the saved item's price. At least 0.
- Line description (`line_description`, text): More detail shown on the line.
- Tax (`tax`, text): A tax to add to the line. Leave empty for the item's own taxes.
- Line items (`lines`, list): For several lines, a list such as [{"name": "Design", "quantity": 2, "unit_cost": 150, "tax_name": "GST", "tax_percent": 5}]. Each line takes name, description, quantity, unit_cost, tax_name, tax_percent, second_tax_name and second_tax_percent. Use it instead of the single line's fields.
- Estimate number (`estimate_number`, text): Leave empty for FreshBooks' next number.
- Reference (`po_number`, text): Your reference, such as the client's purchase order number.
- Discount (%) (`discount_percent`, number): A discount on the whole total, in percent. From 0 to 100.
- Notes (`notes`, text): Notes printed for the client, such as thanks or bank details.
- Terms (`terms`, text): Terms printed for the client, such as when to pay.

**Outputs**: An estimate

- `amount` (object): The total
- `create_date` (text): The estimate date (YYYY-MM-DD)
- `created_at` (text): When it was created
- `currency_code` (text): The estimate's currency
- `current_organization` (text): The client's name as it is now
- `customerid` (number): The client's ID
- `discount_value` (text): Discount, in percent
- `display_status` (text): Status as FreshBooks shows it
- `estimate_number` (text): The estimate number shown on it
- `id` (number): The estimate's ID
- `invoiced` (true/false): Whether it has been turned into an invoice
- `lines` (list): The estimate's lines
- `notes` (text): Notes printed on the estimate
- `organization` (text): The client's name as printed on the estimate
- `po_number` (text): Your reference, such as a PO number
- `terms` (text): Terms printed on the estimate
- `ui_status` (text): Status: draft, sent, viewed, accepted, invoiced
- `updated` (text): When it was last changed
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "amount": {
    "amount": "5000.00",
    "code": "USD"
  },
  "create_date": "2016-04-04",
  "created_at": "2016-09-01 16:16:14",
  "currency_code": "USD",
  "current_organization": "Microsoft",
  "customerid": 338441,
  "discount_value": "0",
  "display_status": "draft",
  "estimate_number": "0000007",
  "id": 2168250,
  "invoiced": false,
  "lines": [
    {
      "amount": {
        "amount": "5000.00",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Paperwork",
      "qty": "1",
      "taxAmount1": "0",
      "taxAmount2": "0",
      "taxName1": "",
      "taxName2": "",
      "unit_cost": {
        "amount": "5000.00",
        "code": "USD"
      }
    }
  ],
  "notes": "",
  "organization": "Microsoft",
  "po_number": null,
  "terms": "",
  "ui_status": "draft",
  "updated": "2016-09-01 16:16:15",
  "vis_state": 0
}
```

### Create expense

Record money your business spent, optionally to bill on to a client or project.

**Inputs**

- Category (`category`, text, required): The expense category. Pick one, or type its name.
- Amount (`amount`, number, required): How much was spent. At least 0.
- Date (`expense_date`, date): When it was spent. Leave empty for today.
- Vendor (`vendor`, text): Who was paid, such as a shop or supplier.
- Notes (`notes`, text): What it was for.
- Currency (`currency`, text): Leave empty for your business's currency.
- Client (`client_id`, text): A client to bill the expense to. Leave empty for none.
- Project (`project_id`, text): The project it belongs to. Leave empty for none.

**Outputs**: An expense

- `amount` (object): How much was spent
- `categoryid` (number): The expense category's ID
- `clientid` (number): The client to bill it to; 0 for none
- `date` (text): When it was spent (YYYY-MM-DD)
- `expenseid` (number): The expense's ID again
- `has_receipt` (true/false): Whether a receipt is attached
- `id` (number): The expense's ID
- `invoiceid` (number): The invoice it was billed on
- `notes` (text): Your notes
- `projectid` (number): The project it belongs to; 0 for none
- `staffid` (number): Who spent it
- `status` (number): 0 internal, 1 to bill, 2 billed, 4 billed and paid
- `updated` (text): When it was last changed
- `vendor` (text): Who was paid
- `vis_state` (number): 0 active, 1 deleted

**Example output**

```json
{
  "amount": {
    "amount": "10.00",
    "code": "CAD"
  },
  "categoryid": 121374834,
  "clientid": 0,
  "date": "2016-09-19",
  "expenseid": 1569533,
  "has_receipt": false,
  "id": 1569533,
  "invoiceid": null,
  "notes": "Rocky Road",
  "projectid": 0,
  "staffid": 1,
  "status": 0,
  "updated": "2016-09-27 21:09:13",
  "vendor": "Ice Cream",
  "vis_state": 0
}
```

### Create invoice

Create a draft invoice for a client, with one line or several. Send it with 'Send invoice' or 'Mark invoice as sent'.

**Inputs**

- Client (`client_id`, text, required): The client. Pick one, or give its ID from an earlier step.
- Invoice date (`invoice_date`, date): The date on the invoice. Leave empty for today.
- Due date (`due_date`, date): When it must be paid. Leave empty for FreshBooks' usual terms.
- Currency (`currency`, text): Leave empty for the client's own currency.
- Item or service (`item`, text): Pick a saved item to fill in its name, description, price and taxes, or type what the line is for.
- Quantity (`quantity`, number): How many. Leave empty for 1. At least 0.
- Unit cost (`unit_cost`, number): The price of one. Leave empty to use the saved item's price. At least 0.
- Line description (`line_description`, text): More detail shown on the line.
- Tax (`tax`, text): A tax to add to the line. Leave empty for the item's own taxes.
- Line items (`lines`, list): For several lines, a list such as [{"name": "Design", "quantity": 2, "unit_cost": 150, "tax_name": "GST", "tax_percent": 5}]. Each line takes name, description, quantity, unit_cost, tax_name, tax_percent, second_tax_name and second_tax_percent. Use it instead of the single line's fields.
- Invoice number (`invoice_number`, text): Leave empty for FreshBooks' next number.
- Reference (`po_number`, text): Your reference, such as the client's purchase order number.
- Discount (%) (`discount_percent`, number): A discount on the whole total, in percent. From 0 to 100.
- Notes (`notes`, text): Notes printed for the client, such as thanks or bank details.
- Terms (`terms`, text): Terms printed for the client, such as when to pay.

**Outputs**: An invoice

- `amount` (object): The total
- `create_date` (text): The invoice date (YYYY-MM-DD)
- `created_at` (text): When it was created
- `currency_code` (text): The invoice's currency
- `current_organization` (text): The client's name as it is now
- `customerid` (number): The client's ID
- `date_paid` (text): When it was fully paid
- `discount_value` (text): Discount, in percent
- `display_status` (text): Status as FreshBooks shows it
- `due_date` (text): The due date (YYYY-MM-DD)
- `due_offset_days` (number): Days from the invoice date to the due date
- `fname` (text): The client contact's first name
- `id` (number): The invoice's ID
- `invoice_number` (text): The invoice number shown on it, such as 0000007
- `invoiceid` (number): The invoice's ID again
- `lines` (list): The invoice's lines
- `lname` (text): The client contact's last name
- `notes` (text): Notes printed on the invoice
- `organization` (text): The client's name as printed on the invoice
- `outstanding` (object): What is still owed after any payments. This is the figure a payment reminder should quote, not amount
- `paid` (object): What has been paid
- `payment_status` (text): unpaid, partial or paid
- `po_number` (text): Your reference, such as a PO number
- `terms` (text): Terms printed on the invoice
- `updated` (text): When it was last changed
- `v3_status` (text): Status: draft, sent, viewed, partial, paid, overdue and so on
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}
```

### Create project

Create a project to track time and expenses against, billed by the hour or at a fixed price.

**Inputs**

- Title (`title`, text, required): The project's name.
- Client (`client_id`, text): The client it is for. Leave empty for none.
- Billing (`project_type`, text): Bill by the hour or at a fixed price. One of: `hourly_rate` (Hourly rate), `fixed_price` (Fixed price). Default: `hourly_rate`.
- Hourly rate (`rate`, number): For hourly projects, the rate per hour. Only when Billing is Hourly rate. At least 0.
- Fixed price (`fixed_price`, number): For fixed-price projects, the price. Only when Billing is Fixed price. At least 0.
- Due date (`due_date`, date): When the project should be finished.
- Description (`description`, text): What the project is about.

**Outputs**: A project

- `active` (true/false): False once the project is deleted
- `billing_method` (text): How time is billed
- `client_id` (number): The client billed for it
- `complete` (true/false): Whether it is marked completed
- `created_at` (text): When it was created (UTC)
- `description` (text): What the project is about
- `due_date` (text): When it is due (YYYY-MM-DD)
- `fixed_price` (text): The price, for fixed-price projects
- `id` (number): The project's ID
- `internal` (true/false): Whether it is internal work, with no client
- `project_type` (text): hourly_rate or fixed_price
- `rate` (text): The hourly rate, for hourly projects
- `title` (text): The project's title
- `updated_at` (text): When it was last changed (UTC)

**Example output**

```json
{
  "active": true,
  "billing_method": null,
  "client_id": 97499,
  "complete": false,
  "created_at": "2017-07-12T17:22:25",
  "description": null,
  "due_date": null,
  "fixed_price": "500",
  "id": 779803,
  "internal": false,
  "project_type": "fixed_price",
  "rate": null,
  "title": "My Cool Project",
  "updated_at": "2017-07-12T17:22:25"
}
```

### Delete client

Delete a client. FreshBooks keeps it in its deleted list, where it can be restored.

**Inputs**

- Client (`client_id`, text, required): The client. Pick one, or give its ID from an earlier step.

**Outputs**: The client deleted

- `client_id` (number): The client's ID
- `deleted` (true/false): Always true once deleted

**Example output**

```json
{
  "client_id": 238951,
  "deleted": true
}
```

### Delete estimate

Delete an estimate. FreshBooks keeps it in its deleted list, where it can be restored.

**Inputs**

- Estimate ID (`estimate_id`, text, required): The estimate's ID, from 'Create estimate'.

**Outputs**: The estimate deleted

- `deleted` (true/false): Always true once deleted
- `estimate_id` (number): The estimate's ID

**Example output**

```json
{
  "deleted": true,
  "estimate_id": 2168250
}
```

### Delete expense

Delete an expense. FreshBooks keeps it in its deleted list, where it can be restored.

**Inputs**

- Expense ID (`expense_id`, text, required): The expense's ID, from 'Create expense' or 'List expenses'.

**Outputs**: The expense deleted

- `deleted` (true/false): Always true once deleted
- `expense_id` (number): The expense's ID

**Example output**

```json
{
  "deleted": true,
  "expense_id": 1569533
}
```

### Delete invoice

Delete an invoice. FreshBooks keeps it in its deleted list, where it can be restored.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.

**Outputs**: The invoice deleted

- `deleted` (true/false): Always true once deleted
- `invoice_id` (number): The invoice's ID

**Example output**

```json
{
  "deleted": true,
  "invoice_id": 1627
}
```

### Delete payment

Delete a payment recorded by mistake. The invoice is owed again.

**Inputs**

- Payment ID (`payment_id`, text, required): The payment's ID, from 'Record payment' or 'List payments'.

**Outputs**: The payment deleted

- `deleted` (true/false): Always true once deleted
- `payment_id` (number): The payment's ID

**Example output**

```json
{
  "deleted": true,
  "payment_id": 10865341
}
```

### Delete project

Delete a project for good.

**Inputs**

- Project (`project_id`, text, required): The project. Pick one, or give its ID from an earlier step.

**Outputs**: The project deleted

- `deleted` (true/false): Always true once deleted
- `project_id` (number): The project's ID

**Example output**

```json
{
  "deleted": true,
  "project_id": 779803
}
```

### Delete time entry

Delete logged time for good.

**Inputs**

- Time entry ID (`time_entry_id`, text, required): The time entry's ID, from 'Log time' or 'List time entries'.

**Outputs**: The time entry deleted

- `deleted` (true/false): Always true once deleted
- `time_entry_id` (number): The time entry's ID

**Example output**

```json
{
  "deleted": true,
  "time_entry_id": 5100
}
```

### Find client

Find a client by email address, or by part of their name or company. Says whether one was found, so a workflow can create the client when not.

**Inputs**

- Email (`email`, text): The client's exact email address.
- Name or company (`name`, text): Part of the client's name or company.

**Outputs**: The client found

- `client` (object): The first client found; empty when none
- `count` (number): How many clients matched
- `found` (true/false): Whether any client matched

**Example output**

```json
{
  "client": {
    "bus_phone": "",
    "currency_code": "USD",
    "email": "email1@freshbooks.com",
    "fname": "first1",
    "id": 238951,
    "language": "en",
    "lname": "last1",
    "mob_phone": "",
    "note": null,
    "organization": "company1",
    "p_city": "Toronto",
    "p_code": "M6P 3T1",
    "p_country": "Canada",
    "p_province": "Ontario",
    "p_street": "1655 Dupont St. W.",
    "p_street2": "",
    "signup_date": "2022-01-05 12:17:11",
    "updated": "2022-01-05 07:17:12",
    "userid": 238951,
    "vat_name": null,
    "vat_number": "",
    "vis_state": 0
  },
  "count": 1,
  "found": true
}
```

### Get client

Get a client's details by ID.

**Inputs**

- Client (`client_id`, text, required): The client. Pick one, or give its ID from an earlier step.

**Outputs**: A client

- `bus_phone` (text): Business phone
- `currency_code` (text): The currency the client is billed in
- `email` (text): Email address
- `fname` (text): First name
- `id` (number): The client's ID
- `language` (text): Language code for what they are sent, such as en
- `lname` (text): Last name
- `mob_phone` (text): Mobile phone
- `note` (text): Your notes about the client
- `organization` (text): Company name
- `p_city` (text): Billing city
- `p_code` (text): Billing postal code
- `p_country` (text): Billing country
- `p_province` (text): Billing state or province
- `p_street` (text): Billing street
- `p_street2` (text): Billing street, second line
- `signup_date` (text): When the client was added (UTC)
- `updated` (text): When the client was last changed
- `userid` (number): The client's ID again, as older endpoints name it
- `vat_name` (text): Tax number label, such as VAT
- `vat_number` (text): Tax number
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "bus_phone": "",
  "currency_code": "USD",
  "email": "email1@freshbooks.com",
  "fname": "first1",
  "id": 238951,
  "language": "en",
  "lname": "last1",
  "mob_phone": "",
  "note": null,
  "organization": "company1",
  "p_city": "Toronto",
  "p_code": "M6P 3T1",
  "p_country": "Canada",
  "p_province": "Ontario",
  "p_street": "1655 Dupont St. W.",
  "p_street2": "",
  "signup_date": "2022-01-05 12:17:11",
  "updated": "2022-01-05 07:17:12",
  "userid": 238951,
  "vat_name": null,
  "vat_number": "",
  "vis_state": 0
}
```

### Get invoice

Get an invoice with its lines, totals and status.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.

**Outputs**: An invoice

- `amount` (object): The total
- `create_date` (text): The invoice date (YYYY-MM-DD)
- `created_at` (text): When it was created
- `currency_code` (text): The invoice's currency
- `current_organization` (text): The client's name as it is now
- `customerid` (number): The client's ID
- `date_paid` (text): When it was fully paid
- `discount_value` (text): Discount, in percent
- `display_status` (text): Status as FreshBooks shows it
- `due_date` (text): The due date (YYYY-MM-DD)
- `due_offset_days` (number): Days from the invoice date to the due date
- `fname` (text): The client contact's first name
- `id` (number): The invoice's ID
- `invoice_number` (text): The invoice number shown on it, such as 0000007
- `invoiceid` (number): The invoice's ID again
- `lines` (list): The invoice's lines
- `lname` (text): The client contact's last name
- `notes` (text): Notes printed on the invoice
- `organization` (text): The client's name as printed on the invoice
- `outstanding` (object): What is still owed after any payments. This is the figure a payment reminder should quote, not amount
- `paid` (object): What has been paid
- `payment_status` (text): unpaid, partial or paid
- `po_number` (text): Your reference, such as a PO number
- `terms` (text): Terms printed on the invoice
- `updated` (text): When it was last changed
- `v3_status` (text): Status: draft, sent, viewed, partial, paid, overdue and so on
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}
```

### List clients

List clients, optionally only those whose name matches.

**Inputs**

- Name or company contains (`search`, text): Only clients whose name or company contains this.
- Page (`page`, number): Which page of results, starting at 1. Leave empty for the first. At least 1.
- Per page (`per_page`, number): How many per page, 1 to 100. Leave empty for 100. From 1 to 100.

**Outputs**: One page of clients

- `clients` (list): The clients on this page
- `count` (number): How many clients are on this page
- `page` (number): This page's number, starting at 1
- `pages` (number): How many pages there are
- `total` (number): How many clients match, on every page

**Example output**

```json
{
  "clients": [
    {
      "bus_phone": "",
      "currency_code": "USD",
      "email": "email1@freshbooks.com",
      "fname": "first1",
      "id": 238951,
      "language": "en",
      "lname": "last1",
      "mob_phone": "",
      "note": null,
      "organization": "company1",
      "p_city": "Toronto",
      "p_code": "M6P 3T1",
      "p_country": "Canada",
      "p_province": "Ontario",
      "p_street": "1655 Dupont St. W.",
      "p_street2": "",
      "signup_date": "2022-01-05 12:17:11",
      "updated": "2022-01-05 07:17:12",
      "userid": 238951,
      "vat_name": null,
      "vat_number": "",
      "vis_state": 0
    }
  ],
  "count": 1,
  "page": 1,
  "pages": 1,
  "total": 1
}
```

### List expenses

List expenses, optionally by category, client, project or date.

**Inputs**

- Category (`category`, text): Only expenses in this category.
- Client (`client_id`, text): Only this client's. Leave empty for every client.
- Project (`project_id`, text): Only expenses for this project.
- Spent on or after (`from_date`, date): Only expenses dated on or after this day.
- Spent on or before (`to_date`, date): Only expenses dated on or before this day.
- Page (`page`, number): Which page of results, starting at 1. Leave empty for the first. At least 1.
- Per page (`per_page`, number): How many per page, 1 to 100. Leave empty for 100. From 1 to 100.

**Outputs**: One page of expenses

- `count` (number): How many expenses are on this page
- `expenses` (list): The expenses on this page
- `page` (number): This page's number, starting at 1
- `pages` (number): How many pages there are
- `total` (number): How many expenses match, on every page

**Example output**

```json
{
  "count": 1,
  "expenses": [
    {
      "amount": {
        "amount": "10.00",
        "code": "CAD"
      },
      "categoryid": 121374834,
      "clientid": 0,
      "date": "2016-09-19",
      "expenseid": 1569533,
      "has_receipt": false,
      "id": 1569533,
      "invoiceid": null,
      "notes": "Rocky Road",
      "projectid": 0,
      "staffid": 1,
      "status": 0,
      "updated": "2016-09-27 21:09:13",
      "vendor": "Ice Cream",
      "vis_state": 0
    }
  ],
  "page": 1,
  "pages": 1,
  "total": 1
}
```

### List invoices

List invoices, optionally by client, status or date, or only those overdue by a number of days. Each comes with the client's email and its amounts and due date ready to put in a message.

**Inputs**

- Client (`client_id`, text): Only this client's. Leave empty for every client.
- Status (`status`, text): Only invoices in this status. One of: `draft`, `sent`, `viewed`, `partial` (Partly paid), `paid`, `overdue`, `disputed`.
- Dated on or after (`from_date`, date): Only invoices dated on or after this day.
- Dated on or before (`to_date`, date): Only invoices dated on or before this day.
- Overdue by at least (days) (`overdue_by_days`, number): Beta. Only sent invoices that still owe money and whose due date was at least this many days ago, oldest first: 1 gives everything overdue, 31 gives invoices more than 30 days overdue. Every matching invoice is returned in one list, so no paging or date check is needed; leave Status, Page and Per page empty. Leave empty to list invoices whether overdue or not. At least 1.
- Page (`page`, number): Which page of results, starting at 1. Leave empty for the first. At least 1.
- Per page (`per_page`, number): How many per page, 1 to 100. Leave empty for 100. From 1 to 100.

**Outputs**: One page of invoices

- `count` (number): How many invoices are on this page
- `incomplete` (true/false): Beta. True only when Overdue by at least (days) had more than 5,000 unpaid invoices to look through and stopped there, so some may be missing
- `invoices` (list): The invoices on this page
- `page` (number): This page's number, starting at 1
- `pages` (number): How many pages there are
- `total` (number): How many invoices match, on every page
- `total_outstanding_display` (text): Beta. What the invoices returned still owe, added up and written for a message, such as $4,200.50 (one total per currency)

**Example output**

```json
{
  "count": 1,
  "incomplete": false,
  "invoices": [
    {
      "amount": {
        "amount": "264.00",
        "code": "USD"
      },
      "amount_display": "$264.00",
      "client_email": "email1@freshbooks.com",
      "client_first_name": "F_Name",
      "client_name": "Test Client company",
      "create_date": "2021-08-17",
      "created_at": "2021-08-17 08:20:11",
      "currency_code": "USD",
      "current_organization": "Test Client company",
      "customerid": 2280,
      "date_paid": null,
      "days_overdue": 32,
      "discount_value": "0",
      "display_status": "sent",
      "due_date": "2021-09-16",
      "due_date_display": "Sep 16, 2021",
      "due_offset_days": 30,
      "fname": "F_Name",
      "id": 1627,
      "invoice_number": "0000003",
      "invoiceid": 1627,
      "lines": [
        {
          "amount": {
            "amount": "240",
            "code": "USD"
          },
          "description": "",
          "lineid": 1,
          "name": "Photography Services",
          "qty": "1",
          "taxAmount1": "10",
          "taxAmount2": "0",
          "taxName1": "GST",
          "taxName2": "",
          "unit_cost": {
            "amount": "240",
            "code": "USD"
          }
        }
      ],
      "lname": "L_Name",
      "notes": "Enter notes or Bank transfer details",
      "organization": "Test Client company",
      "outstanding": {
        "amount": "264.00",
        "code": "USD"
      },
      "outstanding_display": "$264.00",
      "paid": {
        "amount": "0.00",
        "code": "USD"
      },
      "payment_status": "unpaid",
      "po_number": null,
      "terms": "Pay within 30 days.",
      "updated": "2021-08-17 08:20:12",
      "v3_status": "sent",
      "vis_state": 0
    }
  ],
  "page": 1,
  "pages": 1,
  "total": 1,
  "total_outstanding_display": "$264.00"
}
```

### List payments

List payments received, optionally by invoice, client or date.

**Inputs**

- Invoice ID (`invoice_id`, text): Only payments on this invoice.
- Client (`client_id`, text): Only this client's. Leave empty for every client.
- Paid on or after (`from_date`, date): Only payments made on or after this day.
- Paid on or before (`to_date`, date): Only payments made on or before this day.
- Page (`page`, number): Which page of results, starting at 1. Leave empty for the first. At least 1.
- Per page (`per_page`, number): How many per page, 1 to 100. Leave empty for 100. From 1 to 100.

**Outputs**: One page of payments

- `count` (number): How many payments are on this page
- `page` (number): This page's number, starting at 1
- `pages` (number): How many pages there are
- `payments` (list): The payments on this page
- `total` (number): How many payments match, on every page

**Example output**

```json
{
  "count": 1,
  "page": 1,
  "pages": 1,
  "payments": [
    {
      "amount": {
        "amount": "10.00",
        "code": "USD"
      },
      "clientid": 1831231,
      "date": "2013-12-10",
      "from_credit": false,
      "gateway": null,
      "id": 10865341,
      "invoiceid": 2214249,
      "note": "",
      "type": "Check",
      "updated": "2016-09-29 19:09:17",
      "vis_state": 0
    }
  ],
  "total": 1
}
```

### List projects

List projects, open, completed or both.

**Inputs**

- Status (`status`, text): Only open or only completed projects. Leave empty for both. One of: `open`, `completed`.
- Page (`page`, number): Which page of results, starting at 1. Leave empty for the first. At least 1.
- Per page (`per_page`, number): How many per page, 1 to 100. Leave empty for 100. From 1 to 100.

**Outputs**: One page of projects

- `count` (number): How many projects are on this page
- `page` (number): This page's number, starting at 1
- `pages` (number): How many pages there are
- `projects` (list): The projects on this page
- `total` (number): How many projects match, on every page

**Example output**

```json
{
  "count": 1,
  "page": 1,
  "pages": 1,
  "projects": [
    {
      "active": true,
      "billing_method": null,
      "client_id": 97499,
      "complete": false,
      "created_at": "2017-07-12T17:22:25",
      "description": null,
      "due_date": null,
      "fixed_price": "500",
      "id": 779803,
      "internal": false,
      "project_type": "fixed_price",
      "rate": null,
      "title": "My Cool Project",
      "updated_at": "2017-07-12T17:22:25"
    }
  ],
  "total": 1
}
```

### List time entries

List logged time, optionally by client or when it started.

**Inputs**

- Client (`client_id`, text): Only this client's. Leave empty for every client.
- Started from (`started_from`, date and time): Only time that started at or after this moment.
- Started until (`started_to`, date and time): Only time that started at or before this moment.
- Page (`page`, number): Which page of results, starting at 1. Leave empty for the first. At least 1.
- Per page (`per_page`, number): How many per page, 1 to 100. Leave empty for 100. From 1 to 100.

**Outputs**: One page of time entries

- `count` (number): How many time entries are on this page
- `page` (number): This page's number, starting at 1
- `pages` (number): How many pages there are
- `time_entries` (list): The time entries on this page
- `total` (number): How many time entries match, on every page

**Example output**

```json
{
  "count": 1,
  "page": 1,
  "pages": 1,
  "time_entries": [
    {
      "active": true,
      "client_id": 2149780,
      "duration": 7200,
      "id": 5100,
      "is_logged": true,
      "note": "Stuff",
      "project_id": 153125,
      "started_at": "2016-08-16T20:00:00Z"
    }
  ],
  "total": 1
}
```

### Log time

Log time you worked, as yourself, optionally on a project or for a client.

**Inputs**

- Hours (`hours`, number, required): How long, in hours, such as 1.5 for an hour and a half. At least 0.
- Started (`started_at`, date and time): When the work started. Leave empty for work ending now.
- Note (`note`, text): What you worked on.
- Project (`project_id`, text): The project it belongs to. Leave empty for none.
- Client (`client_id`, text): The client the time is for. Leave empty for none.

**Outputs**: A time entry

- `active` (true/false): False once deleted
- `client_id` (number): The client the time is for
- `duration` (number): How long, in seconds
- `id` (number): The time entry's ID
- `is_logged` (true/false): False while a timer is still running
- `note` (text): What was done
- `project_id` (number): The project worked on
- `started_at` (text): When the work started (UTC)

**Example output**

```json
{
  "active": true,
  "client_id": 2149780,
  "duration": 7200,
  "id": 5100,
  "is_logged": true,
  "note": "Stuff",
  "project_id": 153125,
  "started_at": "2016-08-16T20:00:00Z"
}
```

### Mark invoice as sent

Mark a draft invoice as sent without emailing it, for one you deliver yourself. FreshBooks then counts it in its reports.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.

**Outputs**: An invoice

- `amount` (object): The total
- `create_date` (text): The invoice date (YYYY-MM-DD)
- `created_at` (text): When it was created
- `currency_code` (text): The invoice's currency
- `current_organization` (text): The client's name as it is now
- `customerid` (number): The client's ID
- `date_paid` (text): When it was fully paid
- `discount_value` (text): Discount, in percent
- `display_status` (text): Status as FreshBooks shows it
- `due_date` (text): The due date (YYYY-MM-DD)
- `due_offset_days` (number): Days from the invoice date to the due date
- `fname` (text): The client contact's first name
- `id` (number): The invoice's ID
- `invoice_number` (text): The invoice number shown on it, such as 0000007
- `invoiceid` (number): The invoice's ID again
- `lines` (list): The invoice's lines
- `lname` (text): The client contact's last name
- `notes` (text): Notes printed on the invoice
- `organization` (text): The client's name as printed on the invoice
- `outstanding` (object): What is still owed after any payments. This is the figure a payment reminder should quote, not amount
- `paid` (object): What has been paid
- `payment_status` (text): unpaid, partial or paid
- `po_number` (text): Your reference, such as a PO number
- `terms` (text): Terms printed on the invoice
- `updated` (text): When it was last changed
- `v3_status` (text): Status: draft, sent, viewed, partial, paid, overdue and so on
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}
```

### Record payment

Record a payment you received against an invoice. With no amount, it pays what is still owed.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
- Amount (`amount`, number): How much was paid. Leave empty for what is still owed. At least 0.
- Payment date (`payment_date`, date): When it was paid. Leave empty for today.
- Payment method (`payment_type`, text): How it was paid. One of: `Cash`, `Check`, `Bank Transfer`, `Credit Card`, `Debit` (Debit card), `ACH`, `PayPal`, `VISA`, `MASTERCARD`, `AMEX` (American Express), and 6 more.
- Note (`note`, text): A note, such as a check or reference number.

**Outputs**: A payment

- `amount` (object): How much was paid
- `clientid` (number): The client who paid
- `date` (text): When it was paid (YYYY-MM-DD)
- `from_credit` (true/false): Whether it was paid from the client's credit
- `gateway` (text): The online payment service, if any
- `id` (number): The payment's ID
- `invoiceid` (number): The invoice it pays
- `note` (text): Your note on the payment
- `type` (text): How it was paid, such as Check or Cash
- `updated` (text): When it was last changed
- `vis_state` (number): 0 active, 1 deleted

**Example output**

```json
{
  "amount": {
    "amount": "10.00",
    "code": "USD"
  },
  "clientid": 1831231,
  "date": "2013-12-10",
  "from_credit": false,
  "gateway": null,
  "id": 10865341,
  "invoiceid": 2214249,
  "note": "",
  "type": "Check",
  "updated": "2016-09-29 19:09:17",
  "vis_state": 0
}
```

### Send invoice

Email an invoice from FreshBooks, with a link to view and pay it. Marks it as sent.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
- Send to (`recipients`, text): Email addresses, separated by commas. Leave empty for the client's email.
- Subject (`subject`, text): Leave empty for FreshBooks' usual subject.
- Message (`message`, text): Leave empty for FreshBooks' usual message.
- Attach PDF (`attach_pdf`, true/false): Attach the invoice as a PDF too. Default: `false`.

**Outputs**: The invoice sent

- `invoice` (object): An invoice
- `recipients` (list): The email addresses it was sent to

**Example output**

```json
{
  "invoice": {
    "amount": {
      "amount": "264.00",
      "code": "USD"
    },
    "create_date": "2021-08-17",
    "created_at": "2021-08-17 08:20:11",
    "currency_code": "USD",
    "current_organization": "Test Client company",
    "customerid": 2280,
    "date_paid": null,
    "discount_value": "0",
    "display_status": "sent",
    "due_date": "2021-09-16",
    "due_offset_days": 30,
    "fname": "F_Name",
    "id": 1627,
    "invoice_number": "0000003",
    "invoiceid": 1627,
    "lines": [
      {
        "amount": {
          "amount": "240",
          "code": "USD"
        },
        "description": "",
        "lineid": 1,
        "name": "Photography Services",
        "qty": "1",
        "taxAmount1": "10",
        "taxAmount2": "0",
        "taxName1": "GST",
        "taxName2": "",
        "unit_cost": {
          "amount": "240",
          "code": "USD"
        }
      }
    ],
    "lname": "L_Name",
    "notes": "Enter notes or Bank transfer details",
    "organization": "Test Client company",
    "outstanding": {
      "amount": "264.00",
      "code": "USD"
    },
    "paid": {
      "amount": "0.00",
      "code": "USD"
    },
    "payment_status": "unpaid",
    "po_number": null,
    "terms": "Pay within 30 days.",
    "updated": "2021-08-17 08:20:12",
    "v3_status": "sent",
    "vis_state": 0
  },
  "recipients": [
    "email1@freshbooks.com"
  ]
}
```

### Update client

Change a client's details. Only the fields you fill in change.

**Inputs**

- Client (`client_id`, text, required): The client. Pick one, or give its ID from an earlier step.
- First name (`first_name`, text): The contact's first name.
- Last name (`last_name`, text): The contact's last name.
- Company (`organization`, text): The client's company or organization name.
- Email (`email`, text): Where invoices and estimates are sent.
- Phone (`phone`, text): The business phone number.
- Mobile phone (`mobile_phone`, text): The mobile phone number.
- Currency (`currency`, text): The currency the client is billed in.
- Street (`street`, text): Billing address: street.
- Street line 2 (`street2`, text): Billing address: second line.
- City (`city`, text): Billing address: city.
- State or province (`province`, text): Billing address: state or province.
- Postal code (`postal_code`, text): Billing address: ZIP or postal code.
- Country (`country`, text): Billing address: country, such as United States.
- Notes (`notes`, text): Your own notes about the client. Clients don't see them.

**Outputs**: A client

- `bus_phone` (text): Business phone
- `currency_code` (text): The currency the client is billed in
- `email` (text): Email address
- `fname` (text): First name
- `id` (number): The client's ID
- `language` (text): Language code for what they are sent, such as en
- `lname` (text): Last name
- `mob_phone` (text): Mobile phone
- `note` (text): Your notes about the client
- `organization` (text): Company name
- `p_city` (text): Billing city
- `p_code` (text): Billing postal code
- `p_country` (text): Billing country
- `p_province` (text): Billing state or province
- `p_street` (text): Billing street
- `p_street2` (text): Billing street, second line
- `signup_date` (text): When the client was added (UTC)
- `updated` (text): When the client was last changed
- `userid` (number): The client's ID again, as older endpoints name it
- `vat_name` (text): Tax number label, such as VAT
- `vat_number` (text): Tax number
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "bus_phone": "",
  "currency_code": "USD",
  "email": "email1@freshbooks.com",
  "fname": "first1",
  "id": 238951,
  "language": "en",
  "lname": "last1",
  "mob_phone": "",
  "note": null,
  "organization": "company1",
  "p_city": "Toronto",
  "p_code": "M6P 3T1",
  "p_country": "Canada",
  "p_province": "Ontario",
  "p_street": "1655 Dupont St. W.",
  "p_street2": "",
  "signup_date": "2022-01-05 12:17:11",
  "updated": "2022-01-05 07:17:12",
  "userid": 238951,
  "vat_name": null,
  "vat_number": "",
  "vis_state": 0
}
```

### Update invoice

Change an invoice's dates, number, reference, discount, notes, terms or lines. Only the fields you fill in change.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's ID, from 'Create invoice', 'List invoices' or a trigger.
- Invoice date (`invoice_date`, date): A new date for the invoice. Leave empty to keep it.
- Due date (`due_date`, date): A new due date. Leave empty to keep it.
- Invoice number (`invoice_number`, text): A new invoice number. Leave empty to keep it.
- Reference (`po_number`, text): A new reference. Leave empty to keep it.
- Discount (%) (`discount_percent`, number): A new discount on the whole total. Leave empty to keep it. From 0 to 100.
- Notes (`notes`, text): New notes for the client. Leave empty to keep them.
- Terms (`terms`, text): New terms. Leave empty to keep them.
- Line items (`lines`, list): Replaces every line, as a list such as [{"name": "Design", "quantity": 2, "unit_cost": 150}]. Each line takes name, description, quantity, unit_cost, tax_name, tax_percent, second_tax_name and second_tax_percent. Leave empty to keep the lines.

**Outputs**: An invoice

- `amount` (object): The total
- `create_date` (text): The invoice date (YYYY-MM-DD)
- `created_at` (text): When it was created
- `currency_code` (text): The invoice's currency
- `current_organization` (text): The client's name as it is now
- `customerid` (number): The client's ID
- `date_paid` (text): When it was fully paid
- `discount_value` (text): Discount, in percent
- `display_status` (text): Status as FreshBooks shows it
- `due_date` (text): The due date (YYYY-MM-DD)
- `due_offset_days` (number): Days from the invoice date to the due date
- `fname` (text): The client contact's first name
- `id` (number): The invoice's ID
- `invoice_number` (text): The invoice number shown on it, such as 0000007
- `invoiceid` (number): The invoice's ID again
- `lines` (list): The invoice's lines
- `lname` (text): The client contact's last name
- `notes` (text): Notes printed on the invoice
- `organization` (text): The client's name as printed on the invoice
- `outstanding` (object): What is still owed after any payments. This is the figure a payment reminder should quote, not amount
- `paid` (object): What has been paid
- `payment_status` (text): unpaid, partial or paid
- `po_number` (text): Your reference, such as a PO number
- `terms` (text): Terms printed on the invoice
- `updated` (text): When it was last changed
- `v3_status` (text): Status: draft, sent, viewed, partial, paid, overdue and so on
- `vis_state` (number): 0 active, 1 deleted, 2 archived

**Example output**

```json
{
  "amount": {
    "amount": "264.00",
    "code": "USD"
  },
  "create_date": "2021-08-17",
  "created_at": "2021-08-17 08:20:11",
  "currency_code": "USD",
  "current_organization": "Test Client company",
  "customerid": 2280,
  "date_paid": null,
  "discount_value": "0",
  "display_status": "sent",
  "due_date": "2021-09-16",
  "due_offset_days": 30,
  "fname": "F_Name",
  "id": 1627,
  "invoice_number": "0000003",
  "invoiceid": 1627,
  "lines": [
    {
      "amount": {
        "amount": "240",
        "code": "USD"
      },
      "description": "",
      "lineid": 1,
      "name": "Photography Services",
      "qty": "1",
      "taxAmount1": "10",
      "taxAmount2": "0",
      "taxName1": "GST",
      "taxName2": "",
      "unit_cost": {
        "amount": "240",
        "code": "USD"
      }
    }
  ],
  "lname": "L_Name",
  "notes": "Enter notes or Bank transfer details",
  "organization": "Test Client company",
  "outstanding": {
    "amount": "264.00",
    "code": "USD"
  },
  "paid": {
    "amount": "0.00",
    "code": "USD"
  },
  "payment_status": "unpaid",
  "po_number": null,
  "terms": "Pay within 30 days.",
  "updated": "2021-08-17 08:20:12",
  "v3_status": "sent",
  "vis_state": 0
}
```
