Active, Archived, and Deleted Objects

Most FreshBooks objects can be restored after deletion to ensure that you can run your business without clutter, but never live in fear of ending up on the wrong side of the trash bin.

We accomplish this by keeping objects around and just storing whether they are Active, Archived, or Deleted, and allow you to toggle the status.

Deleted objects will not be returned in result lists by default and will not be usable in while deleted (eg. deleted clients can’t be sent new invoices, deleted invoices don’t count against accounting reports, etc.).

The vis_state Field

Many of our resources include the vis_state field, which controls the status of that object. For resources that don’t have a vis_state field includes projects and project-like resources (time-tracking, services, etc.), see “Other Resources” below.

You can see vis_state on many objects and filter for objects in particular states using the numerical values below:

By default list endpoints will return all active and archived resources. To return only certain statuses, a filter must be provided:

• &search[vis_state]=0 returns only active resources
• &search[vis_state]=1 returns only deleted resources
• &search[vis_state]=2 returns only archived resources

Updates and vis_state

Watch out, vis_state can mess up your update calls!

Long ago, for reasons, we broke update actions into phases, and only one phase’s fields can be updated at a time. vis_states are in a different phase from everything else. These are all the phases, in order of precedence:

1. ext_vis_state
2. vis_state
3. actions (like send invoice)
4. regular data updates

If you have a vis_state field in a PUT call, even with the same value it used to have, its phase activates and we throw away the rest of the data silently.

We throw away the rest of the data silently!?

Yes. This also happens if you include ext_vis_state or a special action (like sending an invoice). The first phase to activate from that list above is the only one that activates. None of these fields can be present if you want to modify the other data on your object.

So unless your call is deleting/restoring/sending something, omit vis_state and ext_vis_state from your updates. PUT calls will only update the keys they are given.

Wait, ext_vis_state?

ext_vis_state has to do with statuses being visible by people other than the owner of the object, particularly received invoices and estimates. It is a concept used mostly by FreshBooks Classic and will be removed in future versions of the API. It probably won’t be relevant to anything you ever want to do — in fact, we’d likely leave it out of the documentation entirely if it didn’t force our hand here.

Other Resources

While most resources under /accounting URLs have a vis_state, resources under other URLs (eg. /projects, /timetracking, /comments, and /payments) do not. In many of these cases the status is controlled by an active field. If that field is not present, then the object may be hard deleted (removed from your account and gone) on a DELETE call. If the resource allows archiving, then this would be accomplished with another field (eg. completed). See the resource documentation for details.

For example, Projects:

• active: true indicated a project that has not been deleted
• active: false is a deleted project and cannot have time logged against it.
• completed: true will mark the project as archived. It will still exist, but will no long be displayed on the Project list page by default.