Active 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 or Deleted, and allow you to toggle that field at will. Deleted objects will not be returned in result lists by default. But as we often find in life, things are a little bit more complex than that. Meet vis_state.
The vis_state Field
| State | Value | Description |
|---|---|---|
| Active / Enabled | 0 | active refers to objects that are both completed and non-completed. Deleted objects will not be included |
| Deleted / Inactive | 1 | deleted objects will still be stored but seperated from the completed/non-completed objects. |
| Archived / Hidden | 2 | archived objects only include objects that have been marked as completed. Deleted objects will not be included |
vis_state is the field that has the status of objects. You can see vis_state on many objects and filter for objects in particular states using the numerical values above.
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:
- ext_vis_state
- vis_state
- actions (like send invoice)
- 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 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.