NAV Navbar
shell
  • Introduction
  • Authentication
  • Bookings
  • Projects
  • Invoices
  • Quotes
  • Work Orders
  • Billable Items
  • Invoice / Quote Templates
  • Resources
  • Schedules
  • Contacts
  • People
  • Groups
  • Organizations
  • Statuses
  • Custom Fields
  • Rate Schemes
  • Instance Account
  • Rest Hooks
  • Errors
  • Upgrade Notes
  • Introduction

    Welcome to the FoxOMS REST API documentation site!

    You can use our REST API to access and modify the data within your FoxOMS account. This includes all the information within your bookings, projects and invoices that you can use to import / export data or create integrations with other systems and software that you use.

    This documentation should give you enough information to get started with building your integrations, however if you need more support, please don't hesitate to reach out.

    API Access Control Lists (ACL)

    All actions completed in the FoxOMS REST API will check and enforce the ACL's specified for the FoxOMS user linked to the API token.

    Access to the various FoxOMS modules can be controlled in the Admin -> Groups section. API users should have the minimum amount of rights possible for the integration to be successful.

    For example, if your integration only requires Read access to the booking module, create a custom group called 'Read Booking API' and then create a dedicated user for the integration and add them as the exclusive member of this group. Limiting this group to only have read access to the bookings adds a safeguard against any potential security risks within the third party integration.

    Retrieving Records

    To retrieve one or more records you should issue a GET request to the relevant endpoint.

    Requesting from the endpoint root (eg /booking or /resource) will retrieve a paginated list of all records.

    Filtering & Searching Records

    Many of the attributes on each endpoint can be used to filter the results further. Please see the filter_param column in the endpoint Attributes table for each endpoint for the name of the param to send in your request.

    For example, if you'd like just a single record you can issue an ?id= parameter (eg /booking?id=933894).

    Multiple params can be added together, and the filter logic can be changed between AND and OR to further refine your queries (eg /booking?id=5&status_id=3&filter_operator=AND).

    Many params will also accept a comma seperated list of values, (eg /booking?id=90298,39003,3453).

    If an attribute has a string datatype, the filter will actually do a search, equivalent to LIKE % SEARCH_TERM % where % represents a wildcard. All other data types are exact matches, WHERE column = SEARCH_TERM

    You can restrict the fields returned by a GET request by issuing a list of only the fields you'd like (eg /booking?id=5&fields=id,name,start,end).

    Creating / Updating a Record

    Generally speaking you should issue a POST to create a new record and a PUT to update an existing record.

    However the FoxOMS API is quite forgiving and will allow a new record to be created if a PUT is issued without an ID parameter and a POST to update a record if you supply an ID parameter.

    It is currently only possible to create or update one record per request.

    Deleting a Record

    To delete a record you should issue a DELETE with the ID of the record you wish to delete. Deletion is permanent and cannot be undone.

    It is currently only possible to delete one record per request.

    Authentication

    # With shell, you can just pass the correct header with each request
    curl "api_endpoint_here"
      -H "Authorization: Bearer 74305f35862b76db"
    
    # You can also pass the token in via a query parameter
    curl "api_endpoint_here?access_token=74305f35862b76db"
    

    Make sure to replace 74305f35862b76db with your authentication token.

    You can register an API client for either authentication option under API Settings in the Admin section of your FoxOMS account.

    FoxOMS expects the Bearer Authentication Token to be included in all API requests to the server.

    You can either include the token in a header that looks like the following:

    Authorization: Bearer 74305f35862b76db

    Alternatively you can send the token via a query parameter in the URL like the following:

    https://api.foxoms.com/v1/ENDPOINT?access_token=74305f35862b76db

    Token Based

    We offer a Token Based Authentication method, where the FoxOMS API directly issues you with a "Bearer Token" which you can include in your request to gain immediate access to the API.

    Bookings

    Get All Bookings

    curl "https://api.foxoms.com/v1/booking"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 6,
          "name": "Test Booking",
          "start": 1547501100,
          "end": 1547538900,
          "start_date_time": "15/01/2019 08:25",
          "end_date_time": "15/01/2019 18:55",
          "all_day": false,
          "notes": "Some Booking Notes\n\nMulti line, text... see if it comes across",
          "repeat_master": false,
          "repeat_master_id": 0,
          "repeat_rule": "",
          "project": [
            {
              "id": 1,
              "name": "The Simpsons Episode 459",
              "code": "SIMP",
              "description": "Homer accidentally gets sucked into space and gets his bottom stuck in a black hole",
              "status_id": 0,
              "client": [
                {
                  "id": 126,
                  "name": "Bob Miller",
                  "type": "person",
                  "email": "[email protected]"
                }
            ]
            }
          ],
          "client": [
            {
              "id": "4",
              "name": "Jane Someone",
              "type": "person"
            }
           ],
          "status": [
            {
              "id": 2,
              "name": "Confirmed",
              "description": "The confirmed status",
              "notification": "1"
            }
          ],
          "resources": [
            {
              "id": 2,
              "name": "Edit Suite 2",
              "description": "",
              "type_id": 1,
              "type_person_id": 0,
              "parent_id": 0,
              "parent_name": "",
              "updated": 1549688599,
              "icon": {
                "name": "Avid_AppAdrenaline",
                "alias": "87e73ab25155974c230d09494548201b9f",
                "extension": "png"
              }
            },
            {
              "id": 1,
              "name": "Edit Suite 1",
              "description": "Avid Media Composer!",
              "type_id": 1,
              "type_person_id": 0,
              "parent_id": 0,
              "parent_name": "",
              "updated": 1549688599,
              "icon": {
                "name": "Avid_AppAdrenaline",
                "alias": "87e73ab25155974c230d09494548201b9f",
                "extension": "png"
              }
            },
            {
              "id": 7,
              "name": "Nik",
              "description": "",
              "type_id": 2,
              "type_person_id": 1,
              "parent_id": 9,
              "parent_name": "Staff",
              "updated": 1549861886,
              "icon": {
                "name": "1",
                "alias": "63241c3d48630432920ee9baab8811",
                "extension": "jpg"
              }
            },
            {
              "id": 8,
              "name": "Timothy",
              "description": "",
              "type_id": 2,
              "type_person_id": 2,
              "parent_id": 9,
              "parent_name": "Staff",
              "updated": 1549754805,
              "icon": {
                "name": "Tim",
                "alias": "9ddb6766",
                "extension": "jpg"
              }
            }
          ],
          "custom_fields": [
              {
                "id": 3,
                "name": "Dinner Menu",
                "value": "Pizza",
                "value_id": 5,
                "update_key": "2_1_3"
              },
              {
                "id": 5,
                "name": "Producer Name",
                "value": "Ben Smith",
                "value_id": 0,
                "update_key": "1_1_5"
              }],
          "files": [],
          "quotes": [
            {
              "id": "13",
              "prefix": "QU-",
              "number": "2",
              "total": "630.00"
            }
          ],
          "invoices": [
            {
              "id": "3",
              "prefix": "INV-",
              "number": "3",
              "total": "630.00"
            },
            {
              "id": "10",
              "prefix": "INV-",
              "number": "10",
              "total": "1260.00"
            }
          ],
          "lock_created_id": 0,
          "lock_created_name": "",
          "lock_expire_date": 0,
          "created_id": 1,
          "created": 1547251455,
          "updated_id": 1,
          "updated": 1549189452
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all bookings. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/booking

    Special Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,start,end
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    where_in_resource false Allows returning only bookings that are linked to one or more of these resource IDs where_in_resource=45,233,898
    from_time false Return any bookings starting after the given UNIX timestamp from_time=1549058744
    to_time false Return any bookings starting before the given UNIX timestamp to_time=1549404344
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order
    updated_after false Return results that were added, edited or deleted since this UNIX timestamp updated_after=1610161282

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only bookings that have a status id of 2 by adding the following query parameter

    status_id=2

    You can also separate multiple search values by a comma, for example to return multiple records.

    id=2,3,43,109,23

    You can also concatenate multiple attributes to search for and change the filtering logic using the filter_operator

    id=5&status_id=3&filter_operator=AND

    The above code snippet would only return records that have an id of 5 AND a status_id of 3

    Attributes

    Below are all possible booking object attributes. Please note that not all attributes will be output by default, those need to be manually requested in the fields parameter.

    Name Type Filter Param Description
    id integer id Unique ID of the booking
    name string name Name of the booking
    start integer start UNIX time of the start of the booking
    end integer end UNIX time of the end of the booking
    start_date_time string User defined date formatted result of the booking start
    end_date_time string User defined date formatted result of the booking end
    start_date_time_iso string start_iso ISO-8601 formatted result of the booking start
    end_date_time_iso string end_iso ISO-8601 formatted result of the booking end
    duration_min integer Duration of the booking in minutes
    all_day boolean all_day True if this is an all day booking (no times are recorded)
    notes string notes Any notes added to the booking
    repeat_master boolean repeat_master True if this booking is a master from a set of repeating bookings
    repeat_master_id integer repeat_master_id The unique ID of the booking that is a master. If this value is anything other than zero it is implied that this booking is a slave booking
    repeat_rule string repeat_rule The repetition logic that determines the frequency and amount of repetitions
    project array of single object project_id The project assigned to this booking. Use the project_id parameter to filter bookings by project
    client array of single object client_id The client (either person or organization) attached to this booking
    status array of single object status_id The status assigned to this booking
    resources array of objects where_in_resource Resources that have been added to this booking
    custom_fields array of objects Returns any custom fields that exist for the booking module as well as any values selected for this booking
    files array of objects Returns any files that have been uploaded to this booking
    quotes array of objects Returns any quotes generated from this booking
    invoices array of objects Returns any invoices generated from this booking
    workorders array of objects Returns any work orders generated for this booking
    lock_created_id integer lock_created_id The unique ID of the person (user) who created this lock
    lock_created_name string The full name of the person (user) who created this lock
    lock_expire_date integer lock_expire_date The UNIX time value of the lock expiry time
    created_id integer created_id The unique ID of the person (user) who created this record
    created_name string The full name of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated_name string The full name of the person (user) who updated this record
    updated integer updated The UNIX time value of the last update
    deleted boolean deleted If this booking has been deleted

    Get a Specific Booking

    curl "https://api.foxoms.com/v1/booking?id=6&fields=id,name,project"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 6,
          "name": "Test Booking",
          "project": [
            {
              "id": 1,
              "name": "The Simpsons Episode 459",
              "code": "SIMP",
              "description": "Homer accidentally gets sucked into space and gets his bottom stuck in a black hole"
            }
          ]
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same booking endpoint is used with a filter applied to return only a specific booking. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/booking?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the booking to retrieve
    fields Allows you to return only attributes that you require fields=id,start,end
    filter_operator Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    where_in_resource Allows returning only bookings that are linked to one or more of these resource IDs where_in_resource=45,233,898
    from_time Return any bookings starting after the given UNIX timestamp from_time=1549058744
    to_time Return any bookings starting before the given UNIX timestamp to_time=1549404344

    Get Booking Updates After X

    curl "https://api.foxoms.com/v1/booking?updated_after=1582663551"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this: Note the additional boolean deleted attribute appears when the updated_after flag is used

    {
      "data": [
        {
          "id": 6,
          "name": "New event",
          "start": 1582117500,
          "end": 1582119600,
          "start_date_time": "20/02/2020 00:05",
          "end_date_time": "20/02/2020 00:40",
          "all_day": false,
          "notes": "",
          "repeat_master": false,
          "repeat_master_id": 0,
          "repeat_rule": "",
          "project": [],
          "client": [],
          "status": [],
          "resources": [],
          "custom_fields": [],
          "files": [],
          "quotes": [
            {
              "id": "1",
              "prefix": "QU-",
              "number": "1",
              "date": "1582517555",
              "total": "0.00"
            }
          ],
          "invoices": [],
          "created_id": 1,
          "created": 1582517526,
          "updated_id": 1,
          "updated": 1582663925,
          "deleted": true
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves any bookings that have been added, edited or even been deleted since an X timestamp. This is useful when you're maintaining a local cache of booking data and only want to retrieve data that has changed since you last updated your cache.

    An additional boolean deleted attribute is displayed when the updated_after parameter is used.

    HTTP Request

    GET https://api.foxoms.com/v1/booking?updated_after=<UNIX TIMESTAMP>

    URL Parameters

    Parameter Description Example
    id The ID of the booking to retrieve
    fields Allows you to return only attributes that you require fields=id,start,end
    filter_operator Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    where_in_resource Allows returning only bookings that are linked to one or more of these resource IDs where_in_resource=45,233,898
    updated_after Return any bookings added, edited or deleted after the given UNIX timestamp updated_after=1549058744

    Get Booking Clashes

    curl "https://api.foxoms.com/v1/booking/checkclash?start=1488417601&end=1488417602&booking_id=349&resources=1,2,5"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this if one or more clashes are found:

    {
        "data": [
            {
                "id": 2,
                "name": "'Wall-E' Assemble Edit",
                "start": 1357221600,
                "end": 1357250400,
                "start_date_time": "04/01/2013 01:00",
                "end_date_time": "04/01/2013 09:00",
                "resources": [
                    {
                        "id": 1,
                        "name": "Edit Suite 1",
                        "description": "Avid Media Composer",
                        "type_id": 1,
                        "type_person_id": 0,
                        "parent_id": 0,
                        "parent_name": "",
                        "updated": 1388552400,
                        "icon": {
                            "name": "Avid_AppAdrenaline",
                            "alias": "87e73ab25155974c230d09494548201b9f5056efbf38169730e14dd7d3e097d0",
                            "extension": "png"
                        }
                    }
                ]
            },
            {
                "id": 3,
                "name": "Another Booking Name",
                "start": 1357308000,
                "end": 1357336800,
                "start_date_time": "05/01/2013 01:00",
                "end_date_time": "05/01/2013 09:00",
                "resources": [
                    {
                        "id": 1,
                        "name": "Edit Suite 1",
                        "description": "Avid Media Composer",
                        "type_id": 1,
                        "type_person_id": 0,
                        "parent_id": 0,
                        "parent_name": "",
                        "updated": 1388552400,
                        "icon": {
                            "name": "Avid_AppAdrenaline",
                            "alias": "87e73ab25155974c230d09494548201b9f5056efbf38169730e14dd7d3e097d0",
                            "extension": "png"
                        }
                    }
                ]
            }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    If no clashes are found the following is output

    {
      "data": [],
      "meta": {
        "pagination": {
          "total": 0,
          "count": 0,
          "per_page": 0,
          "current_page": 1,
          "total_pages": 0,
          "links": []
        }
      }
    }
    

    This endpoint can be used to determine if there are any clashes on booking resources in a determined time slot

    HTTP Request

    GET https://api.foxoms.com/v1/booking/checkclash?start=<START UNIX TIME RANGE>&end=<END UNIX TIME RANGE>&id=<ID>&resources=<RESOURCE IDS>

    URL Parameters

    Parameter Description Example
    start UNIX time value of the start of the range we should be checking for clashes
    end UNIX time value of the end of the range we should be checking for clashes
    resources Comma separated list of resource id's that we should check for clashes on. If none are provided, we'll return results from any booking that matches the time range
    id * Optional. The ID of a booking to exclude from the clash check
    fields Allows you to return only attributes that you require fields=id,start,end
    filter_operator Allows overriding of the default filtering method (either AND or OR). filter_operator=AND

    Attributes

    Name Type Description
    id integer Unique ID of the clashed booking
    name string Name of the clashed booking
    start integer UNIX time of the start of the clashed booking
    end integer UNIX time of the end of the clashed booking
    start_date_time string User defined date formatted result of the clashed booking start
    end_date_time string User defined date formatted result of the clashed booking end
    resources array of objects One or more resources that are causing the clash

    Create Booking

    POST https://api.foxoms.com/v1/booking

    curl "https://api.foxoms.com/v1/booking"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "20189"
      }
    }
    

    To add resources to this booking, pass in the id's of the resources as follows

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"resources": {
            "ids":[109,223,211]
            }'
    

    Alternatively specify the resources within an array of objects, the same as they are shown within the API GET requests

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"resources":[
                {
                    "id":273
                },
                {
                    "id":9328
                }
            ]'
    

    To modify the custom fields on a booking, you need to specify the custom fields "update_key" as the key, and the value you wish to have as the value.

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"custom_fields":{"1_1_8":"Director", "1_1_9":"Longform Production"}'
    

    This endpoint allows you to create a booking. Use any of the attributes listed under the GET request.

    The created booking ID will be returned upon successful creation.

    Checking for clashes

    The default behaviour of the bookings create and update endpoints is to check for clashes. If a clash is detected, saving will be aborted and the details of the conflicting booking will be returned. If you wish to proceed with the booking simply change check_clashes=false.

    If you've specified resources on your bookings, clashes will only be returned for the resources you've asked to be added to your booking. If no resources are specified, clashes will be returned for all resources, based purely on the set times.

    Notifications

    Notifications will be sent if you create a booking and assign a user resource, assuming they have notifications enabled and the booking status is not blocking notifications from being sent.

    Modifying Custom Fields

    To set or modify the custom fields on a booking, you need to specify the custom_fields "update_key" as the key, ie 1_1_9

    Adding or editing booking project

    The project must be set with project_id

    Adding or editing booking status

    The status must be set with status_id

    Adding or editing booking client

    The client must be set with client_id, in the format p123 for people clients and o123 for organization clients.

    Creating a Repeating Booking

    Repeat bookings are generated when a booking is given a repeat_rule that defines the logic for the repeat bookings. The booking with the repeat_rule becomes the 'master' booking and all bookings generated from this logic are known as 'repeats'.

    These 'repeat' bookings are still technically independent bookings, (they are given their own ID's), however any changes to the master are automatically replicated to these bookings

    Repeat Rule Segment Description Options Example
    FREQ=X The frequency that recurring bookings are created Hourly, Daily, Weekly, Monthly FREQ=daily;
    INTERVAL=X The interval of the above frequency between repeats 0-99 FREQ=daily;INTERVAL=3; (booking should repeat every 3 days)
    BYDAY=X Only applies if frequency is set to weekly, which days should this booking repeat on mo,tu,we,th,fr,sa,su FREQ=weekly;BYDAY=TU,TH,SA; (booking should repeat every week on Tuesday, Thursday and Saturday)
    REPENDTYPE=X What mechanism stops the repeat booking count, date REPENDTYPE=count;
    COUNT=X How many bookings should there be after the repeats have been generated (includes the original booking) 0-99 COUNT=5; (there will be 4 repeats and 1 original booking)
    UNTIL=X The last date that booking repeats will be generated on Date/Time in YYYYMMDDTHHMMSS format UNTIL=20190621T183000 is the 21st of June 2019 at 18:30 in the evening;

    URL Parameters

    The following URL parameters are optional

    Parameter Description Example
    check_clashes Allows you to check for booking clashes before saving check_clashes=true

    Update a Booking

    PUT https://api.foxoms.com/v1/booking?id=

    curl "https://api.foxoms.com/v1/booking?id=20189"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "20189"
      }
    }
    

    This endpoint allows you to update a booking. Use any of the attributes listed under the GET request with an ID parameter to specify the booking you wish to update. Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    URL Parameters

    Parameter Description Example
    id The ID of the booking to update 3

    Delete a Booking

    DELETE https://api.foxoms.com/v1/booking?id=

    curl "https://api.foxoms.com/v1/booking?id=454"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true,
        "id": 454
      }
    }
    

    This endpoint allows you to delete a booking.

    This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the booking to delete 3
    delete_repeats Applies only when deleting a master booking, if true all repeat bookings will also be deleted true

    Lock a Booking

    PUT https://api.foxoms.com/v1/booking/lock?id=

    curl "https://api.foxoms.com/v1/booking/lock?id=<ID>"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"lock_created_id": 1, "lock_expire_date":1613361324'
    

    A successful put will return the following JSON:

    {
      "status": {
        "success": true,
        "id": 454
      }
    }
    

    This endpoint allows you to lock a booking. The booking locks feature must be enabled for this endpoint to be active.

    URL Parameters

    Parameter Description Example
    id The ID of the booking to lock 3

    Unlock a Booking

    PUT https://api.foxoms.com/v1/booking/unlock?id=

    curl "https://api.foxoms.com/v1/booking/unlock?id=<ID>"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
    

    A successful put will return the following JSON:

    {
      "status": {
        "success": true,
        "id": 454
      }
    }
    

    This endpoint allows you to unlock a booking. The booking locks feature must be enabled for this endpoint to be active.

    URL Parameters

    Parameter Description Example
    id The ID of the booking to unlock 3

    Projects

    Get All Projects

    curl "https://api.foxoms.com/v1/project"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
      {
          "id": 1,
          "name": "The Simpsons Episode 459",
          "code": "SIMP",
          "description": "Homer accidentally gets sucked into space and gets his bottom stuck in a black hole",
          "status_id": 0,
          "status": [
              {
                "id": 0,
                "name": "In Progress"
              }
          ],
          "start": 1365811200,
          "end": 1374969600,
          "private": true,
          "parent_folder_id": 5,
          "client_person_id": 4,
          "client_organization_id": 0,
          "client": [
              {
                "id": "4",
                "name": "Jane Someone",
                "type": "person"
              }
          ],
          "order": 0,
          "color_background": "#B0A7F1",
          "color_text": "#000000",
          "people": {
            "users": [
              {
                "id": 3,
                "name": "Bob Smith",
                "admin_flag": 0,
                "role_id": 0,
                "role_name": "0"
              },
              {
                "id": 4,
                "name": "Jane Someone",
                "admin_flag": 1,
                "role_id": 3,
                "role_name": "Video Editor"
              },
              {
                "id": 5,
                "name": "Jack Brown",
                "admin_flag": 0,
                "role_id": 0,
                "role_name": "0"
              },
              {
                "id": 6,
                "name": "Anna Marie",
                "admin_flag": 0,
                "role_id": 0,
                "role_name": "0"
              },
              {
                "id": 8,
                "name": "John Jefferson",
                "admin_flag": 0,
                "role_id": 0,
                "role_name": "0"
              }
            ],
            "groups": [
              {
                "id": 2,
                "name": "Staff"
              }
            ]
          },
          "custom_fields": [
            {
              "id": 1,
              "name": "Producer",
              "value": "Someone Famous",
              "value_id": 0
            },
            {
              "id": 2,
              "name": "Lunch Choice",
              "value": "Pizza",
              "value_id": 1
            }
          ],
          "files": [
            {
              "name": "Snapshot - Windspray",
              "alias": "66425cee6abaffc56f1b128aad5cc2d43a86225b89e359d748d1a3683835234c",
              "extension": "png",
              "size": "518829"
            }
          ],
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1476593200
        }
        ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 10,
          "count": 8,
          "per_page": 10,
          "current_page": 1,
          "total_pages": 8,
          "links": {
            "next" : 2
          }
        }
      }
    }
    

    This endpoint retrieves all projects. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/project

    Special Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,name,code
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    show_folders false Returns project folders amongst the projects, useful if you have to build a project tree of projects and their folders show_folders=true
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order
    with_acl false When true, only returns projects according to the acl's applied to the current user with_acl=true
    updated_after false Return results that were added, edited or deleted since this UNIX timestamp updated_after=1610161282

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only projects that have a status id of 2 by adding the following query parameter

    status_id=2

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the project
    name string name Title of the project
    code string code Short code used to identify the project
    description string description A couple of sentences used to describe the purpose of the project
    status_id integer status_id Unique ID of the selected status
    status array of single object The status of the project
    start integer start UNIX time of the start of the project timeframe
    end integer end UNIX time of the end of the project timeframe
    private boolean private Is the project viewable to everyone, or just the users and groups assigned
    parent_folder_id integer parent_folder_id The ID of the folder that this project is sitting in
    is_folder boolean is_folder True if this is project folder, useful for differentiating between projects and folders with the show_folder option
    order integer order The order that this project appears (if a custom order has been specified)
    color_background string color_background A hex color value of the background of this project
    color_text string color_text A hex color value of the text of this project
    client_person_id integer client_person_id Unique ID of the person selected as a client
    client_organization_id integer client_organization_id Unique ID of the organization selected as a client
    client array of single object client_id The client (either person or organization) attached to this project
    people array of objects The users and groups assigned to this project. Also contains information regarding project admin status and role information
    custom_fields array of objects Returns any custom fields that exist for the project module as well as any values selected for this project
    files array of objects Returns any files that have been uploaded to this project
    feed string feed Returns the feed (currently only one feed is allowed per project) associated with this project
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update

    Get a Project

    curl "https://api.foxoms.com/v1/project?id=4&fields=name,code,start,end"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "name": "Futurama Episode 191",
          "code": "FTR",
          "start": 1365811200,
          "end": 1366329600
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same project endpoint is used with a filter applied to return only a specific project. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/project?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the project to retrieve
    fields Allows you to return only attributes that you require fields=name,code,start,end

    Get Project Folders

    curl "https://api.foxoms.com/v1/project/folder"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 5,
          "name": "Animations",
          "parent_folder_id": 0,
          "order": 3,
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1388552400
        },
        {
          "id": 6,
          "name": "Grand Designs Episodes",
          "parent_folder_id": 0,
          "order": 2,
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1388552400
        },
        {
          "id": 7,
          "name": "UK Episodes",
          "parent_folder_id": 6,
          "order": 4,
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1388552400
        },
        {
          "id": 8,
          "name": "AU Episodes",
          "parent_folder_id": 6,
          "order": 1,
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1388552400
        }
      ],
      "meta": {
        "pagination": {
          "total": 4,
          "count": 1,
          "per_page": 4,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all project folders. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/project/folder

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,name
    limit 10 The number of results returned per page limit=50

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only project folder that have a parent folder id of 2 by adding the following query parameter

    parent_folder_id=2

    Attributes

    Name Type Description
    id integer Unique ID of the project folder
    name string Title of the project folder
    parent_folder_id integer The ID of the folder that this project folder is sitting in
    order integer The order that this project folder appears (if a custom order has been specified)
    created_id integer The unique ID of the person (user) who created this record
    created integer The UNIX time value of the creation time
    updated_id integer The unique ID of the person (user) who last updated this record
    updated integer The UNIX time value of the last update

    Create Project

    POST https://api.foxoms.com/v1/project

    curl "https://api.foxoms.com/v1/project"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "2785"
      }
    }
    

    To modify the client on a project you need to specify the client_id with a prefix of p for person or o for organization

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"client_id":"p23"'
    

    To modify the people who have access to the project, you need to specify an array of objects as shown below

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"people":[
            {
                "id":2,
                "type":"user",
                "admin":false
            },
            {
                "id":3,
                "type":"group",
                "admin":false
            }
        ]'
    

    To modify the custom fields on a project, you need to specify the custom fields "update_key" as the key, and the value you wish to have as the value.

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"custom_fields":{"1_4_8":"Director", "1_4_9":"Longform Production"}'
    

    This endpoint allows you to create a project. Use any of the attributes listed under the GET request.

    The created project ID will be returned upon successful creation.

    Required Fields

    The following fields are only required on creation of a new project

    Name Type Description
    name string Title of the project folder

    Automatic setting of Project Text Color

    If you specify the color_background, FoxOMS will automatically choose an appropriate readable text color and prefill the color_text. If you specify color_text FoxOMS will use the value you provided, even if the background / text color are hard to read.

    URL Parameters

    No URL Parameters are required for creating a project.

    Update a Project

    PUT https://api.foxoms.com/v1/project?id=

    curl "https://api.foxoms.com/v1/project?id=15"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "2785"
      }
    }
    

    This endpoint allows you to update a project. Use any of the attributes listed under the GET request with an ID parameter to specify the project you wish to update. Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    URL Parameters

    Parameter Description Example
    id The ID of the project to update 3

    Reorder Projects

    PUT https://api.foxoms.com/v1/project/reorder

    curl "https://api.foxoms.com/v1/project/reorder"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"order": [
                       {
                         "id": "1",
                         "parent_id": 0,
                         "order": 0
                       },
                       {
                         "id": "2",
                         "parent_id": 0,
                         "order": 1
                       },
                       {
                         "id": "5",
                         "parent_id": 0,
                         "order": 2
                       },
                       {
                         "id": "4",
                         "parent_id": "5",
                         "order": 0
                       },
                       {
                         "id": "6",
                         "parent_id": "5",
                         "order": 1
                       },
                       {
                         "id": "9",
                         "parent_id": 0,
                         "order": 3
                       },
                       {
                         "id": "8",
                         "parent_id": "9",
                         "order": 0
                       },
                       {
                         "id": "7",
                         "parent_id": "9",
                         "order": 1
                       },
                       {
                         "id": "13",
                         "parent_id": 5,
                         "order": 4
                       }
                     ]'
    

    This endpoint allows you to change the order and heirachy of projects and project folders.

    Supply the new order as an array in an attribute called "order" to the /project/reorder endpoint.

    Delete Project

    DELETE https://api.foxoms.com/v1/project?id=

    curl "https://api.foxoms.com/v1/project?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true,
        "id": 1
      }
    }
    

    This endpoint allows you to delete a project.

    Deleting a project also deletes all bookings and files associated with it. This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the project to delete 3

    Invoices

    Get All Invoices

    curl "https://api.foxoms.com/v1/invoice"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 10,
          "prefix": "INV-",
          "number": 1,
          "date": 1583578132,
          "due_date": 1586170132,
          "status_id": 1,
          "status": [
            {
                "id": 1,
                "name": "Draft"
            }
          ],
          "project": [
            {
              "id": 3,
              "name": "Miniscule Series 5 Ep 1",
              "code": "",
              "description": "A clever french animation of the lives of insects"
            }
          ],
          "client": [
            {
              "id": "3",
              "name": "Bob Smith",
              "type": "person"
            }
          ],
          "items": [
            {
              "id": 59,
              "item": "Edit Suite 1",
              "item_id": 1,
              "item_type_id": 1,
              "item_type": "resource",
              "ratescheme_id": "1",
              "source_name": "Booking -> Rate Scheme (Edit Suites) -> Resource (Edit Suite 1)",
              "booking_id": 7,
              "description": "Edit Suites - Base rate for edit suite services\r\nTest Booking - Tue 3rd Mar 2020 9:55AM --> Tue 3rd Mar 2020 8:40PM",
              "quantity": "10.75",
              "unit": "hourly",
              "cost": "200.00",
              "tax": true,
              "discount": "0.00",
              "total": "2150.00",
              "order": 0
            },
            {
              "id": 60,
              "item": "Edit Suite 3",
              "item_id": 3,
              "item_type_id": 1,
              "item_type": "resource",
              "ratescheme_id": "0",
              "source_name": "Booking",
              "booking_id": 7,
              "description": "Test Booking",
              "quantity": "10.75",
              "unit": "hourly",
              "cost": "0.00",
              "tax": true,
              "discount": "0.00",
              "total": "0.00",
              "order": 1
            },
            {
              "id": 61,
              "item": "Aspera Uploads",
              "item_id": 0,
              "item_type_id": 0,
              "item_type": "custom",
              "ratescheme_id": "0",
              "source_name": "Work Order",
              "booking_id": 7,
              "description": "Something",
              "quantity": "3.00",
              "unit": "Upload",
              "cost": "150.00",
              "tax": true,
              "discount": "0.00",
              "total": "450.00",
              "order": 2
            },
            {
              "id": 62,
              "item": "Catering 1 Persons",
              "item_id": 0,
              "item_type_id": 0,
              "item_type": "custom",
              "ratescheme_id": "0",
              "source_name": "Work Order",
              "booking_id": 7,
              "description": "Catering",
              "quantity": "3.00",
              "unit": "Food",
              "cost": "100.00",
              "tax": true,
              "discount": "0.00",
              "total": "300.00",
              "order": 3
            }
          ],
          "custom_fields": [
            {
              "id": 3,
              "name": "PO Number",
              "value": "23478",
              "value_id": 0,
              "update_key": "1_9_3"
            }
          ],
          "sub_total": "2900.00",
          "discount_total": "0.00",
          "tax_total": "290.00",
          "total": "3190.00",
          "template_id": 0,
          "currency": "AUD",
          "tax_rate": "10.00",
          "created_id": 1,
          "created": 1583578143,
          "updated_id": 1,
          "updated": 1583634262
        },
        ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all invoices. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/invoice

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,prefix,number
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only invoices that have a status id of 1 by adding the following query parameter

    status_id=1

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the invoice
    prefix string prefix Prefix to the invoice number
    number integer number Number of the invoice
    type_id integer type_id Type of record, ie 1 = invoice, 2 = quote, 3 = workorder
    date integer date UNIX time of the date shown on the invoice
    date_time_iso string date_iso ISO-8601 formatted result of the invoice date
    due_date integer due_date UNIX time of the due date shown on the invoice
    due_date_time_iso string due_date_iso ISO-8601 formatted result of the invoice due date
    status_id integer status_id Unique ID of the selected status
    status array of single object The status of the invoice
    booking_id integer booking_id Booking ID related to this record (applicable to work orders only)
    project array of single object project_id The project assigned to this invoice. Use the project_id parameter to filter invoices by project
    client array of single object client_id The client (either person or organization) attached to this invoice
    items array of objects The line items that make up the invoice
    custom_fields array of objects Returns any custom fields that exist for the invoice module as well as any values selected for this invoice
    sub_total decimal sub_total Total of all invoice items before tax and discounts are applied
    discount_total decimal discount_total Total amount discounted from the invoice
    tax_total decimal tax_total The amount of tax charged on the invoice
    total decimal total The final amount of this invoice
    template_id integer template_id The ID of the invoice template being used
    currency string currency Currency code (two character format) that this invoice is in
    tax_rate decimal tax_rate The tax rate percent that was applied to this invoice
    cloned_id integer cloned_id The ID of the quote this invoice was cloned from (applies only to invoices)
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created UNIX time of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated UNIX time value of the last update to this record

    Item Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the invoice item
    invoice_id integer invoice_id Unique ID of the invoice this item belongs to
    item_text string item_text Text of the invoice item field
    item_id integer item_id The unique ID of the item as defined by item_type, Eg, if item_type = 2 then this is the ID of the billable item
    item_type_id integer item_type_id 0 = Custom, 1 = Rate Scheme, 2 = Billable Item
    ratescheme_id integer ratescheme_id The unique ID of the rate scheme, only applies if item_type = 1
    source_name string source_name Name of the rate scheme used, only applied if item_type = 1
    booking_id integer booking_id The unique ID of the booking, only applies if this item was prefilled from a booking
    description string description Text of the description field
    quantity decimal quantity Number of this item to multiply by
    unit string unit Unit label for this item
    unit_amount decimal unit_amount Individual unit cost of this item
    tax boolean tax Is this item taxable?
    discount decimal discount Discount percentage
    total decimal total Total amount of this item
    order integer order The order that this item appears relative to all others
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created UNIX time of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated UNIX time value of the last update to this record

    Get a Specific Invoice

    curl "https://api.foxoms.com/v1/invoice?id=16&fields=id,prefix,number,project_id,total"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 16,
          "prefix": "INV-",
          "number": 6002,
          "total": "50.00"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same invoice endpoint is used with a filter applied to return only a specific invoice. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/invoice?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the booking to retrieve
    fields Allows you to return only attributes that you require fields=id,prefix,number,total

    Create Invoice

    POST https://api.foxoms.com/v1/invoice

    curl "https://api.foxoms.com/v1/invoice"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "20189"
      }
    }
    

    This endpoint allows you to create an invoice. Use any of the attributes listed under the GET request.

    The created invoice ID will be returned upon successful creation.

    Update an Invoice

    PUT https://api.foxoms.com/v1/invoice?id=

    curl "https://api.foxoms.com/v1/invoice?id=27"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "27"
      }
    }
    

    This endpoint allows you to update an invoice. Use any of the attributes listed under the GET request with an ID parameter to specify the invoice you wish to update.

    Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    Delete Invoice

    DELETE https://api.foxoms.com/v1/invoice?id=

    curl "https://api.foxoms.com/v1/invoice?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete an invoice

    This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the invoice to delete 3

    Quotes

    Get All Quotes

    curl "https://api.foxoms.com/v1/quote"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 7,
          "prefix": "QU-",
          "number": 5,
          "date": 1583548272,
          "due_date": 1586140272,
          "status_id": 1,
          "status": [
            {
                "id": 1,
                "name": "Draft"
            }
          ],
          "project": [
            {
              "id": 4,
              "name": "Futurama Episode 191",
              "code": "",
              "description": "Bender accidentally falls in a blender"
            }
          ],
          "client": [
            {
              "id": "5",
              "name": "Jack Brown",
              "type": "person"
            }
          ],
          "items": [
            {
              "id": 21,
              "item": "Edit Suite 1",
              "item_id": 1,
              "item_type_id": 1,
              "item_type": "resource",
              "ratescheme_id": "1",
              "source_name": "Booking -> Rate Scheme (Edit Suites) -> Resource (Edit Suite 1)",
              "booking_id": 7,
              "description": "Edit Suites - Base rate for edit suite services\r\ntest - Tue 3rd Mar 2020 9:55AM --> Tue 3rd Mar 2020 8:40PM",
              "quantity": "1.00",
              "unit": "daily",
              "cost": "800.00",
              "tax": true,
              "discount": "0.00",
              "total": "800.00",
              "order": 0
            },
            {
              "id": 22,
              "item": "Edit Suite 3",
              "item_id": 3,
              "item_type_id": 1,
              "item_type": "resource",
              "ratescheme_id": "1",
              "source_name": "Booking -> Rate Scheme (Edit Suites) -> Resource (Edit Suite 3)",
              "booking_id": 7,
              "description": "Edit Suites - Base rate for edit suite services\r\ntest - Tue 3rd Mar 2020 9:55AM --> Tue 3rd Mar 2020 8:40PM",
              "quantity": "1.00",
              "unit": "daily",
              "cost": "800.00",
              "tax": true,
              "discount": "0.00",
              "total": "800.00",
              "order": 1
            },
            {
              "id": 23,
              "item": "Aspera Uploads",
              "item_id": 0,
              "item_type_id": 0,
              "item_type": "custom",
              "ratescheme_id": "0",
              "source_name": "Work Order",
              "booking_id": 7,
              "description": "Something",
              "quantity": "3.00",
              "unit": "Upload",
              "cost": "150.00",
              "tax": true,
              "discount": "0.00",
              "total": "450.00",
              "order": 2
            },
            {
              "id": 24,
              "item": "Catering 1 Persons",
              "item_id": 0,
              "item_type_id": 0,
              "item_type": "custom",
              "ratescheme_id": "0",
              "source_name": "Work Order",
              "booking_id": 7,
              "description": "",
              "quantity": "3.00",
              "unit": "Food",
              "cost": "100.00",
              "tax": true,
              "discount": "0.00",
              "total": "300.00",
              "order": 3
            }
          ],
          "custom_fields": [
            {
              "id": 3,
              "name": "PO Number",
              "value": null,
              "value_id": 0,
              "update_key": "1_9_3"
            }
          ],
          "sub_total": "2350.00",
          "discount_total": "0.00",
          "tax_total": "0.00",
          "total": "2350.00",
          "template_id": 0,
          "currency": "AUD",
          "tax_rate": "0.00",
          "created_id": 1,
          "created": 1583548327,
          "updated_id": 1,
          "updated": 1583634125
        },
        ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all quotes. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/quote

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,prefix,number
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only quotes that have a status id of 1 by adding the following query parameter

    status_id=1

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the quote
    prefix string prefix Prefix to the quote number
    number integer number Number of the quote
    type_id integer type_id Type of record, ie 1 = quote, 2 = quote, 3 = workorder
    date integer date UNIX time of the date shown on the quote
    date_time_iso string date_iso ISO-8601 formatted result of the quote date
    due_date integer due_date UNIX time of the due date shown on the quote
    due_date_time_iso string due_date_iso ISO-8601 formatted result of the quote due date
    status_id integer status_id Unique ID of the selected status
    status array of single object The status of the quote
    booking_id integer booking_id Booking ID related to this record (applicable to work orders only)
    project array of single object project_id The project assigned to this quote. Use the project_id parameter to filter quotes by project
    client array of single object client_id The client (either person or organization) attached to this quote
    items array of objects The line items that make up the quote
    custom_fields array of objects Returns any custom fields that exist for the quote module as well as any values selected for this quote
    sub_total decimal sub_total Total of all quote items before tax and discounts are applied
    discount_total decimal discount_total Total amount discounted from the quote
    tax_total decimal tax_total The amount of tax charged on the quote
    total decimal total The final amount of this quote
    template_id integer template_id The ID of the quote template being used
    currency string currency Currency code (two character format) that this quote is in
    tax_rate decimal tax_rate The tax rate percent that was applied to this quote
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created UNIX time of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated UNIX time value of the last update to this record

    Item Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the quote item
    invoice_id integer invoice_id Unique ID of the quote this item belongs to
    item_text string item_text Text of the quote item field
    item_id integer item_id The unique ID of the item as defined by item_type, Eg, if item_type = 2 then this is the ID of the billable item
    item_type_id integer item_type_id 0 = Custom, 1 = Rate Scheme, 2 = Billable Item
    ratescheme_id integer ratescheme_id The unique ID of the rate scheme, only applies if item_type = 1
    source_name string source_name Name of the rate scheme used, only applied if item_type = 1
    booking_id integer booking_id The unique ID of the booking, only applies if this item was prefilled from a booking
    description string description Text of the description field
    quantity decimal quantity Number of this item to multiply by
    unit string unit Unit label for this item
    unit_amount decimal unit_amount Individual unit cost of this item
    tax boolean tax Is this item taxable?
    discount decimal discount Discount percentage
    total decimal total Total amount of this item
    order integer order The order that this item appears relative to all others
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created UNIX time of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated UNIX time value of the last update to this record

    Get a Specific Quote

    curl "https://api.foxoms.com/v1/quote?id=14&fields=id,prefix,number,total"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 14,
          "prefix": "QU-",
          "number": 11,
          "total": "814.80"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same quote endpoint is used with a filter applied to return only a specific quote. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/quote?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the booking to retrieve
    fields Allows you to return only attributes that you require fields=id,prefix,number,total

    Create Quote

    POST https://api.foxoms.com/v1/quote

    curl "https://api.foxoms.com/v1/quote"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "20189"
      }
    }
    

    This endpoint allows you to create a quote. Use any of the attributes listed under the GET request.

    The created quote ID will be returned upon successful creation.

    Update an Quote

    PUT https://api.foxoms.com/v1/quote?id=

    curl "https://api.foxoms.com/v1/quote?id=27"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "27"
      }
    }
    

    This endpoint allows you to update a quote. Use any of the attributes listed under the GET request with an ID parameter to specify the quote you wish to update.

    Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    Delete Quote

    DELETE https://api.foxoms.com/v1/quote?id=

    curl "https://api.foxoms.com/v1/quote?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete an quote

    This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the quote to delete 3

    Work Orders

    Get All Work Orders

    curl "https://api.foxoms.com/v1/workorder"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 9,
          "prefix": "WO-",
          "number": 3,
          "booking_id": 10,
          "project": [],
          "client": [],
          "items": [
            {
              "id": 55,
              "item": "Aspera Uploads",
              "item_id": 1,
              "item_type_id": 2,
              "item_type": "billable-item",
              "ratescheme_id": "0",
              "source_name": "",
              "booking_id": 10,
              "description": "Something",
              "quantity": "5.00",
              "unit": "Upload",
              "cost": "150.03",
              "tax": true,
              "discount": "0.00",
              "total": "750.15",
              "order": 0
            },
            {
              "id": 56,
              "item": "Catering 1 Persons",
              "item_id": 2,
              "item_type_id": 2,
              "item_type": "billable-item",
              "ratescheme_id": "0",
              "source_name": "",
              "booking_id": 10,
              "description": "Japanese for 2s",
              "quantity": "2.00",
              "unit": "Food",
              "cost": "95.46",
              "tax": true,
              "discount": "0.00",
              "total": "190.92",
              "order": 1
            }
          ],
          "sub_total": "941.07",
          "discount_total": "0.00",
          "tax_total": "94.11",
          "total": "1035.18",
          "template_id": 0,
          "currency": "USD",
          "tax_rate": "10.00",
          "created_id": 1,
          "created": 1583562070,
          "updated_id": 1,
          "updated": 1583576834
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all work orders. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/workorder

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,prefix,number
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only the work order linked to booking_id of 1292 by adding the following query parameter

    booking_id=1292

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the workorder
    prefix string prefix Prefix to the workorder number
    number integer number Number of the workorder
    type_id integer type_id Type of record, ie 1 = workorder, 2 = quote, 3 = workorder
    date integer date UNIX time of the date shown on the workorder
    due_date integer due_date UNIX time of the due date shown on the workorder
    status_id integer status_id Unique ID of the selected status
    booking_id integer booking_id Booking ID related to this record (applicable to work orders only)
    project array of single object project_id The project assigned to this workorder. Use the project_id parameter to filter workorders by project
    client array of single object client_id The client (either person or organization) attached to this workorder
    items array of objects The line items that make up the workorder
    custom_fields array of objects Returns any custom fields that exist for the workorder module as well as any values selected for this workorder
    sub_total decimal sub_total Total of all workorder items before tax and discounts are applied
    discount_total decimal discount_total Total amount discounted from the workorder
    tax_total decimal tax_total The amount of tax charged on the workorder
    total decimal total The final amount of this workorder
    template_id integer template_id The ID of the workorder template being used
    currency string currency Currency code (two character format) that this workorder is in
    tax_rate decimal tax_rate The tax rate percent that was applied to this workorder
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created UNIX time of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated UNIX time value of the last update to this record

    Item Attributes

    Name Type Description
    id integer Unique ID of the workorder item
    invoice_id integer Unique ID of the workorder this item belongs to
    item_text string Text of the workorder item field
    item_id integer The unique ID of the item as defined by item_type, Eg, if item_type = 2 then this is the ID of the billable item
    item_type_id integer 0 = Custom, 1 = Rate Scheme, 2 = Billable Item
    ratescheme_id integer The unique ID of the rate scheme, only applies if item_type = 1
    source_name string Name of the rate scheme used, only applied if item_type = 1
    booking_id integer The unique ID of the booking, only applies if this item was prefilled from a booking
    description string Text of the description field
    quantity decimal Number of this item to multiply by
    unit string Unit label for this item
    cost decimal Individual cost of this item
    tax boolean Is this item taxable?
    discount decimal Discount percentage
    total decimal Total amount of this item
    order integer The order that this item appears relative to all others

    Get a Specific Work Order

    curl "https://api.foxoms.com/v1/workorder?id=16&fields=id,prefix,number,booking_id,total"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 9,
          "prefix": "WO-",
          "number": 3,
          "booking_id": 10,
          "total": "1035.18"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same work order endpoint is used with a filter applied to return only a specific work order. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/workorder?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the booking to retrieve
    fields Allows you to return only attributes that you require fields=id,prefix,number,booking_id,total

    Create Work Order

    POST https://api.foxoms.com/v1/workorder

    curl "https://api.foxoms.com/v1/workorder"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "2785"
      }
    }
    

    This endpoint allows you to create a workorder. Use any of the attributes listed under the GET request.

    The created workorder ID will be returned upon successful creation.

    Update a Work Order

    PUT https://api.foxoms.com/v1/workorder?id=

    curl "https://api.foxoms.com/v1/workorder?id=15"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "2785"
      }
    }
    

    This endpoint allows you to update a workorder. Use any of the attributes listed under the GET request with an ID parameter to specify the workorder you wish to update. Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    URL Parameters

    Parameter Description Example
    id The ID of the workorder to update 3

    Delete Work Order

    DELETE https://api.foxoms.com/v1/workorder?id=

    curl "https://api.foxoms.com/v1/workorder?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true,
        "id": 1
      }
    }
    

    This endpoint allows you to delete a work order.

    This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the workorder to delete 3

    Billable Items

    Get All Billable Items

    curl "https://api.foxoms.com/v1/billableitem"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Portable HDD",
          "description": "A 1TB portable SSD",
          "unit_name": "",
          "cost": "299.95",
          "default_tax": true,
          "order": 1,
          "custom_fields": [
            {
                "id": 34,
                "name": "Item",
                "value": null,
                "value_id": 0,
                "update_key": "1_10_34"
            }
          ],
          "created_id": 1,
          "created": 10,
          "updated_id": 1,
          "updated": 1568063417
        },
        {
          "id": 3,
          "name": "Server Storage Allocation (1TB)",
          "description": "Storage allocation on the main server. Billed per Terrabyte",
          "unit_name": "",
          "cost": "10.00",
          "default_tax": true,
          "order": 2,
          "custom_fields": [
            {
                "id": 34,
                "name": "Item",
                "value": null,
                "value_id": 0,
                "update_key": "1_10_34"
            }
          ],
          "created_id": 1,
          "created": 1567980458,
          "updated_id": 1,
          "updated": 1568190715
        }
      ],
      "meta": {
        "pagination": {
          "total": 2,
          "count": 1,
          "per_page": 2,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all Billable Items which can be things like consumables and other predefined inventory items.

    HTTP Request

    GRT https://api.foxoms.com/v1/billableitem

    Special Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,start,end
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example you can ask the API to only return Billable Items that have a default tax applied by supplying the following query parameter

    default_tax=true

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the billable item
    name string name Title of the billable item
    description string description Description of the billable item
    unit_name string unit_name Name of the unit shown on the quote or invoice
    cost decimal cost Total cost of the billable item
    default_tax boolean default_tax Add tax to item by default
    order integer order Value representing the order that this item will appear in the billable items admin section
    custom_fields array of objects Returns any custom fields that exist for the billable items module as well as any values selected for this billable item
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update

    Get a Specific Billable Item

    curl "https://api.foxoms.com/v1/billableitem?id=3&fields=id,name,cost"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 3,
          "name": "Server Storage Allocation (1TB)",
          "cost": "10.00"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same billable item endpoint is used with a filter applied to return only a specific billable item. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/billableitem?id=<ID>

    Create Billable Item

    POST https://api.foxoms.com/v1/billableitem

    curl "https://api.foxoms.com/v1/billableitem"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value", "key2":"value2"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "192"
      }
    }
    

    This endpoint allows you to create a billable item. Use any of the attributes listed under the GET request to create a billable item.

    The created billable item ID will be returned upon successful creation.

    Update Billable Item

    PUT https://api.foxoms.com/v1/billableitem?id=

    curl "https://api.foxoms.com/v1/billableitem?id=27"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "27"
      }
    }
    

    This endpoint allows you to update a billable item. Use any of the attributes listed under the GET request to update a billable item.

    Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    URL Parameters

    Parameter Description Example
    id The ID of the billable item to update 3

    Reorder Billable Items

    PUT https://api.foxoms.com/v1/billableitem/reorder

    curl "https://api.foxoms.com/v1/billableitem/reorder"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"order": {
            "ids":[109,223,211,237]
            }'
    

    This endpoint allows you to update the order of billable items.

    If you need to change the order of many billable items, you can do so in one request, by supplying the new order of Billable Item IDs as an array in an object called "order" to the /billableitem/reorder endpoint.

    Delete Billable Item

    DELETE https://api.foxoms.com/v1/billableitem?id=

    curl "https://api.foxoms.com/v1/billableitem?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete a billable item.

    Deleting a billable item does not remove it from existing quotes or invoices, but prevents it from being added to future quotes or invoices.

    URL Parameters

    Parameter Description Example
    id The ID of the billable item to delete 3

    Invoice / Quote Templates

    Get all Templates

    GET https://api.foxoms.com/v1/invoicetemplate

    curl "https://api.foxoms.com/v1/invoicetemplate"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Custom Template",
          "description": "Super cool template",
          "type_id": 7,
          "default": true,
          "title": "Invoice",
          "logo": [
            {
              "name": "Company Logo",
              "alias": "79eac69a2c57ccf59cc65d93253b15d90a1150f1f54deaa88d6407c0254c5a36",
              "extension": "png",
              "size": "39664"
            }
          ],
          "top_left_container": "Left Content",
          "top_center_container": "centered",
          "top_right_container": "<h3>[invoiceNumber]</h3>\r\n\r\n[companyName]\r\n[contactDetails]\r\n\r\n<b>Date:</b> [invoiceDate]\r\n<b>Project:</b> [projectName]",
          "middle_left_container": "<b>Due:</b> [invoiceDue]",
          "middle_center_container": "middle center",
          "middle_right_container": "right middle",
          "bottom_left_container": "<h4>Invoice Terms</h4>\r\n[invoiceTerms]",
          "bottom_center_container": "bottom centered",
          "bottom_right_container": "biottom right",
          "created_id": 42,
          "created": 1545866522,
          "updated_id": 1,
          "updated": 1545983535
        }
        ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    
    

    This endpoint retrieves all invoice or quote templates. The results returned are paginated.

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,prefix,number
    limit 10 The number of results returned per page limit=50

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    You can differentiate between invoice and quote templates by the type_id field.

    Following returns only invoice templates

    type_id=1

    Following returns only quote templates

    type_id=2

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the invoice template
    name string name Name of the invoice template
    description string description Desription of the invoice template
    type_id integer type_id 1 = Invoice, 2 = Quote
    default boolean default True means this invoice template will be selected by default on the creation of new invoice
    title string title The title shown in the top left hand corner of the template, usually QUOTE or INVOICE
    logo array of single object alias Returns the logo image file of this invoice template
    top_left_container string top_left_container Top left container of the invoice
    top_center_container string top_center_container Top center container of the invoice
    top_right_container string top_right_container Top right container of the invoice
    middle_left_container string middle_left_container Middle left container of the invoice
    middle_center_container string middle_center_container Middle center container of the invoice
    middle_right_container string middle_right_container Middle right container of the invoice
    bottom_left_container string bottom_left_container Bottom left container of the invoice
    bottom_center_container string bottom_center_container Bottom center container of the invoice
    bottom_right_container string bottom_right_container Bottom right container of the invoice
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created UNIX time of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated UNIX time value of the last update to this record

    Get a Template

    GET https://api.foxoms.com/v1/invoicetemplate?id=

    curl "https://api.foxoms.com/v1/invoicetemplate?id=1&fields=id,name,default,title"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Custom Template",
          "default": false,
          "title": "Invoice"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same invoice endpoint is used with a filter applied to return only a specific invoice / quote template. We've also specifically requested the fields we need to improve speed and readability.

    URL Parameters

    Parameter Description Example
    id The ID of the invoice/quote template to retrieve 3
    fields Allows you to return only attributes that you require fields=id,name,default,title

    Create Template

    POST https://api.foxoms.com/v1/invoicetemplate

    curl "https://api.foxoms.com/v1/invoicetemplate"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    This endpoint allows you to create an invoice or quote template. Use any of the attributes listed under the GET request with a type_id parameter to specify the type of template you wish to create. The created templates ID will be returned upon successful creation.

    You must specify a valid type_id and a name when creating an invoice or quote template.

    URL Parameters

    No URL Parameters are required for creating an invoice template.

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "20"
      }
    }
    

    To set a logo, you must pass the logo alias in an array, to unset, simply pass in an empty alias

    curl "https://api.foxoms.com/v1/invoicetemplate"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"logo": [{
                "alias":"79eac69a2c57ccf59cc65d93253b15d90a11"
            }]'
    

    Update Template

    PUT https://api.foxoms.com/v1/invoicetemplate?id=

    curl "https://api.foxoms.com/v1/invoicetemplate?id=1"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    This endpoint allows you to update an invoice or quote template. Use any of the attributes listed under the GET request with an ID parameter to specify the template you wish to update.

    URL Parameters

    Parameter Description Example
    id The ID of the invoice/quote template to update 3

    A successful update will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    Delete Template

    DELETE https://api.foxoms.com/v1/invoicetemplate?id=

    curl "https://api.foxoms.com/v1/invoicetemplate?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    This endpoint allows you to delete an invoice or quote template.

    URL Parameters

    Parameter Description Example
    id The ID of the invoice/quote template to delete 3

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    Resources

    Get All Resources

    curl "https://api.foxoms.com/v1/resource"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Edit Suite 1",
          "description": "Avid Media Composer!",
          "schedules": [
            {
              "id": 1,
              "name": "Sydney Office (Surry Hills)",
              "description": "The schedule for the Sydney Team"
            },
            {
              "id": 2,
              "name": "Sydney Office Shared",
              "description": "Schedule for shared division of Sydney Office"
            }
          ],
          "type_id": 1,
          "type_person_id": 0,
          "parent_id": 0,
          "order": 1,
          "icon": [
            {
              "name": "Avid_AppAdrenaline",
              "alias": "87e73ab25155974c230d09494548201b9f5056efbf38",
              "extension": "png",
              "size": "174285"
            }
          ],
          "color_background": "#B0A7F1",
          "color_text": "#000000",
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1547713557
        },
    ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 14,
          "count": 2,
          "per_page": 10,
          "current_page": 1,
          "total_pages": 2,
          "links": {
            "next": 2
          }
        }
      }
    }
    

    This endpoint retrieves all resources (and resource groups). The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/resource

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,name,description
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order
    updated_after false Return results that were added, edited or deleted since this UNIX timestamp updated_after=1610161282

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only resources that have a type id of 2 by adding the following query parameter

    type_id=2

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the resource
    name string name Title of the resource
    description string description Description of the resource
    schedules array of objects Returns schedules that this resource has been added to
    type_id integer type_id 1 = Room, 2 = Person, 3 = Equipment, 4 = Resource Group, 5 = Action
    type_person_id integer type_person_id The unique ID of the person (only applies if this resource is a person)
    parent_id integer parent_id The unigue ID of the resource group that this resource is a child of
    order integer order Value representing the order that this resource will appear in various parts of the application
    feed string Returns the feed (currently only one feed is allowed per resource) associated with this resource
    icon array of single object alias Returns the image file of this resource icon
    color_background string color_background A hex color value of the background of this resource
    color_text string color_text A hex color value of the text of this resource
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update
    deleted integer deleted Has this record been soft deleted

    Get a Resource

    curl "https://api.foxoms.com/v1/resource?id=4&fields=id,name,description,parent_id"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 4,
          "name": "Alexa Camera",
          "description": "",
          "parent_id": 5
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same resource endpoint is used with a filter applied to return only a specific resource. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/resource?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the resource to retrieve
    fields Allows you to return only attributes that you require fields=id,name,description

    Create Resource

    POST https://api.foxoms.com/v1/resource

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "20"
      }
    }
    

    To set an icon, you must pass the icon alias in an array, to unset, simply pass in an empty alias

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"icon": [{
                "alias":"79eac69a2c57ccf59cc65d93253b15d90a11"
            }]'
    

    To assign this resource to schedules, pass in the id's of the schedules as follows

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"schedules": {
            "ids":[109,223,211]
            }'
    

    This endpoint allows you to create a resource of any type. Use any of the attributes listed under the GET request with a type_id parameter to specify the type of resource you wish to create.

    The created resource ID will be returned upon successful creation.

    Creating a Person Resource

    If you wish to create a person resource, you must specify name = undefined and type_id = 2 and type_person_id with a valid person_id. This person cannot already be a "resource" related to another resource.

    The name value must be sent because it is a required parameter, however it will be overwritten immediately with the persons full name.

    If the person has set an avatar this will also be added to the resource object under the icon field automatically.

    Resource Group Nesting

    If you wish to nest the resource under a resource group, you must specify a valid parent_id, which itself must have a type_id = 4 (resource group).

    Automatic setting of Resource Text Color

    If you specify the color_background, FoxOMS will automatically choose an appropriate readable text color and prefill the color_text. If you specify color_text FoxOMS will use the value you provided, even if the background / text color are hard to read.

    URL Parameters

    No URL Parameters are required for creating a resource.

    Update Resource

    PUT https://api.foxoms.com/v1/resource?id=

    curl "https://api.foxoms.com/v1/resource?id=15"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to update a resource. Use any of the attributes listed under the GET request with an ID parameter to specify the resource you wish to update. Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    Updating the type_id of a Resource

    You can freely convert the type_id's of resources, ie changing a resource from a 'room' to an 'equipment'. You can also convert any resource type to a 'person resource', by following the directions above.

    However you cannot convert an existing 'person resource' to any other type of resource.

    You also cannot reassign an existing person resource to be linked to another person.

    Updating the parent_id of a Resource Group

    The schedule allows nesting of resource groups within resource groups. FoxOMS will not allow you to set the parent_id of a resource group to a descendant of itself.

    URL Parameters

    Parameter Description Example
    id The ID of the resource to update 3

    Reorder Resources

    PUT https://api.foxoms.com/v1/resource/reorder

    curl "https://api.foxoms.com/v1/resource/reorder"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"order": [
                       {
                         "id": "1",
                         "parent_id": 0,
                         "order": 0
                       },
                       {
                         "id": "2",
                         "parent_id": 0,
                         "order": 1
                       },
                       {
                         "id": "5",
                         "parent_id": 0,
                         "order": 2
                       },
                       {
                         "id": "4",
                         "parent_id": "5",
                         "order": 0
                       },
                       {
                         "id": "6",
                         "parent_id": "5",
                         "order": 1
                       },
                       {
                         "id": "9",
                         "parent_id": 0,
                         "order": 3
                       },
                       {
                         "id": "8",
                         "parent_id": "9",
                         "order": 0
                       },
                       {
                         "id": "7",
                         "parent_id": "9",
                         "order": 1
                       },
                       {
                         "id": "13",
                         "parent_id": 5,
                         "order": 4
                       }
                     ]'
    

    This endpoint allows you to change the order and heirachy of resources and resource groups.

    Supply the new order as an array in an attribute called "order" to the /resource/reorder endpoint.

    Delete Resource

    DELETE https://api.foxoms.com/v1/resource?id=

    curl "https://api.foxoms.com/v1/resource?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete a resource.

    Deleting a resource removes it from all schedules and rate schemes, but does not affect existing bookings. This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the resource to delete 3

    Schedules

    Get All Schedules

    curl "https://api.foxoms.com/v1/schedule"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Sydney Office",
          "description": "The schedule for the Sydney Team",
          "resources": [
            {
              "id": 1,
              "name": "Edit Suite 1",
              "description": "Avid Media Composer",
              "type_id": 1,
              "type_person_id": 0,
              "parent_id": 0,
              "parent_name": ""
            },
            {
              "id": 2,
              "name": "Edit Suite 2",
              "description": "Avid Media Composer",
              "type_id": 1,
              "type_person_id": 0,
              "parent_id": 0,
              "parent_name": ""
            },
            {
              "id": 7,
              "name": "Joe Smith",
              "description": "",
              "type_id": 2,
              "type_person_id": 15,
              "parent_id": 9,
              "parent_name": "Staff"
            },
            {
              "id": 9,
              "name": "Staff",
              "description": "",
              "type_id": 4,
              "type_person_id": 0,
              "parent_id": 0,
              "parent_name": ""
            }
          ],
          "access": [
            {
              "id": "1",
              "name": "Base",
              "type": "group"
            },
            {
              "id": "2",
              "name": "Staff",
              "type": "group"
            },
            {
              "id": "3",
              "name": "Administrators",
              "type": "group"
            },
            {
              "id": "4",
              "name": "Super Administrators",
              "type": "group"
            },
            {
              "id": "10",
              "name": "Video Editors",
              "type": "group"
            }
          ],
          "feed": "https://test.foxoms.com/feed/schedule/891e37cc6f9bef7923fe8d8c5ed66e74615a6",
          "order": 4,
          "default": false,
          "default_color_mode": "resource",
          "sunday_start": false,
          "first_hour": 11,
          "last_hour": 20,
          "scroll_hour": 0,
          "time_step_min": 5,
          "fill_cell": false,
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1489151475
        },
        ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 2,
          "count": 1,
          "per_page": 2,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all schedules. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/schedule

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,name,description
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order
    with_acl false When true, only returns schedules according to the acl's applied to the current user with_acl=true
    updated_after false Return results that were added, edited or deleted since this UNIX timestamp updated_after=1610161282

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only schedules that have a sunday start flag of 1 by adding the following query parameter

    sunday_start_flag=1

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the schedule
    name string name Title of the schedule
    description string description Description of the schedule
    resources array of objects Returns resources that have been added to this schedule
    access array of objects Returns users and groups that have been access to this schedule
    feed string Returns the feed (currently only one feed is allowed per schedule) associated with this schedule
    order integer order The order that this schedule will appear in the returned results
    sunday_start boolean sunday_start If the week starts with a Sunday (true) or on Monday (false)
    working_week integer working_week The working week configuration for this schedule. 0 = Monday -> Friday, 1 = Monday -> Saturday, 2 = Saturday -> Thursday, 3 = Sunday -> Thursday
    first_hour integer first_hour The first hour shown on the schedule (0 - 23)
    last_hour integer last_hour The last hour shown on the schedule (1 - 24)
    scroll_hour integer scroll_hour The hour to scroll to on load (applies to daily and weekly calendar views only) (1 - 12)
    time_step_min integer time_step_min The number of minutes between each ‘step’ on the schedule (5,10,15,30,60)
    fill_cell boolean fill_cell If true, the entire schedule cell is filled with the booking, if false, the booking is shown with its start and end times (applied to timeline views only)
    country_region string country_region The country / region that this schedule is located in... used for public holiday information
    show_public_holiday boolean show_public_holiday If true, public holidays will be loaded on the Schedule
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update

    Get a Specific Schedule

    curl "https://api.foxoms.com/v1/schedule?id=2&fields=id,name,description,resources"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 2,
          "name": "Sydney Office Shared",
          "description": "Schedule for shared division of Sydney Office",
          "resources": [
            {
              "id": 1,
              "name": "Edit Suite 1",
              "description": "Avid Media Composer",
              "type_id": 1,
              "type_person_id": 0,
              "parent_id": 0,
              "parent_name": ""
            },
            {
              "id": 29,
              "name": "Edit Action",
              "description": "",
              "type_id": 5,
              "type_person_id": 0,
              "parent_id": 0,
              "parent_name": ""
            }
          ]
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same schedule endpoint is used with a filter applied to return only a specific schedule. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/schedule?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the schedule to retrieve
    fields Allows you to return only attributes that you require fields=id,name,description,resources

    Create Schedule

    POST https://api.foxoms.com/v1/schedule

    curl "https://api.foxoms.com/v1/schedule"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "20"
      }
    }
    

    To assign this resources to this schedule, pass in the id's of the resources as follows

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"resources": {
            "ids":[109,223,211]
            }'
    

    To assign access for users and groups to this schedule, pass in the id's of the users (prefixed with u) and groups (prefixed with g) as follows

    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"access": {
            "ids":[u1022,u2323,g26111]
            }'
    

    This endpoint allows you to create a schedule. Use any of the attributes listed under the GET request. The created schedule ID will be returned upon successful creation.

    URL Parameters

    No URL Parameters are required for creating a schedule.

    Update Schedule

    PUT https://api.foxoms.com/v1/schedule?id=

    curl "https://api.foxoms.com/v1/schedule?id=53"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to update a schedule. Use any of the attributes listed under the GET request with an ID parameter to specify the schedule you wish to update.

    URL Parameters

    Parameter Description Example
    id The ID of the schedule to update 17

    Delete Schedule

    DELETE https://api.foxoms.com/v1/schedule?id=

    curl "https://api.foxoms.com/v1/schedule?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete a schedule.

    Deleting a schedule removes it for all users, but does not affect bookings. However this cannot be undone so please use caution.

    URL Parameters

    Parameter Description Example
    id The ID of the schedule to delete 78

    Contacts

    Get All Contacts

    curl "https://api.foxoms.com/v1/contact"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    
    {
        "data": [
            {
                "id": 1,
                "name": "ABC Australia",
                "type": "organization",
                "client": true,
                "email_1": "[email protected]",
                "email_2": "[email protected]",
                "email_3": "",
                "phone_1": "",
                "phone_2": "",
                "phone_3": "",
                "address_line_1": "",
                "address_line_2": "",
                "address_line_3": "",
                "address_city": "",
                "address_state": "",
                "website": "",
                "notes": "",
                "created_id": 1,
                "created": 1409651928,
                "updated_id": 1,
                "updated": 1628277154
            },
            {
                "id": 6,
                "name": "Anna Marie",
                "type": "person",
                "client": true,
                "email_1": "[email protected]",
                "email_2": null,
                "email_3": null,
                "phone_1": null,
                "phone_2": null,
                "phone_3": null,
                "address_line_1": null,
                "address_line_2": null,
                "address_line_3": null,
                "address_city": null,
                "address_state": null,
                "website": null,
                "notes": null,
                "created_id": 1,
                "created": 1388552400,
                "updated_id": 1,
                "updated": 1388552400
            },
            ...MORE_RESULTS_TRUNCATED...
        ],
        "meta": {
            "pagination": {
                "total": 10,
                "count": 1,
                "per_page": 10,
                "current_page": 1,
                "total_pages": 1,
                "links": []
            }
        }
    }
    

    This endpoint retrieves all contacts. This endpoint merges people and organizations into a single endpoint.

    HTTP Request

    GET https://api.foxoms.com/v1/contact

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,first_name,last_name,username
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order
    updated_after false Return results that were added, edited or deleted since this UNIX timestamp updated_after=1610161282

    People

    Get All People

    curl "https://api.foxoms.com/v1/people"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 6,
          "first_name": "Anna",
          "last_name": "Marie",
          "username": "annamarie",
          "primary_email": "[email protected]",
          "user": false,
          "resource": false,
          "client": true,
          "group_id": 0,
          "organization_id": 1,
          "email_2": "",
          "email_3": "",
          "phone_1": "",
          "phone_2": "",
          "phone_3": "",
          "address_line_1": "123 Awesome Street",
          "address_line_2": "Lane 2",
          "address_line_3": "Place Somewhere",
          "address_city": "Sydney",
          "address_state": "NSW",
          "address_postcode": "2250",
          "address_country": "Australia",
          "website": "",
          "notes": "",
          "timezone": "",
          "locale": "en_US",
          "date_format": "j/n/y",
          "time_format": "1",
          "avatar_file_id": 0,
          "expires": 0,
          "custom_fields": [
            {
              "id": 8,
              "name": "Extra Postcode",
              "value": null,
              "value_id": 0
            }
          ],
          "created_id": 1,
          "created": 1388552400,
          "updated_id": 1,
          "updated": 1480481190
        },
        ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 8,
          "count": 1,
          "per_page": 8,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all people. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/people

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,first_name,last_name,username
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order
    updated_after false Return results that were added, edited or deleted since this UNIX timestamp updated_after=1610161282

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only people that have been designated as users by adding the following query parameter

    user=1

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the person
    name string Full name of the person
    first_name string first_name First name of the person
    last_name string last_name Last name of the person
    username string username Username that can be used to login
    primary_email string primary_email The main email of the person, also can be used to login
    user boolean user Is the person selected as a user
    resource boolean resource Is the person selected as a resource
    resource_id integer resource_id The unique ID of the resource that this person is linked to. Only applies if resource is set to TRUE
    client boolean client Is the person selected as a client
    schedules array of objects Returns schedules that this person resource has been added to (only appears if the person has been marked as a resource)
    group_id integer group_id The unique ID of the group that this person (user) is added to
    group array of single object The group that this person has been added to
    organization_id integer organization_id The unique ID of the organization that this person is added to
    organization array of single object The organization that this person has been added to
    email_2 string email_2 Second email address
    email_3 string email_3 Third email address
    phone_1 string phone_1 Phone 1
    phone_2 string phone_2 Phone 2
    phone_3 string phone_3 Phone 3
    address_line_1 string address_line_1 Address Line 1
    address_line_2 string address_line_2 Address Line 2
    address_line_3 string address_line_3 Address Line 3
    address_city string address_city Address City
    address_state string address_state Address State
    address_postcode string address_postcode Address Postcode
    address_country string address_country Address Country
    website string website Website
    notes string notes Any notes on the person
    timezone string timezone Timezone selected by the person (user)
    locale string locale Locale selected by the person (user)
    date_format string date_format Date Format selected by the person (user)
    time_format string time_format Time Format selected by the person (user)
    notifications boolean notifications Does this person want to receive email notifications
    avatar_file_id integer avatar_file_id Unique image file ID linked to this person
    expires integer expires Account expiry date in UNIX time
    schedule_view_mode integer schedule_view_mode Applies only to people with the User and Resource flags both set to True. 0 = Show all bookings, 1 = Anonymize other bookings, 2 = Hide other bookings
    sso_login boolean sso_login Sets whether this user will login via SSO or standard user account
    custom_fields array of objects Returns any custom fields that exist for the people module as well as any values selected for this person
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated The UNIX time value of when this record was last updated
    deleted boolean deleted Flag indicates if this record has been deleted

    Get All Clients

    curl "https://api.foxoms.com/v1/people/clients"
      -H "Authorization: Bearer 74305f35862b76db"
    

    This endpoint retrieves all people clients. It is identical to the /people endpoint except it will only return results of people who have client=true. This endpoint allows retrieving clients without requiring admin level ACL permissions.

    The results returned are paginated.

    Get a Specific Person

    curl "https://api.foxoms.com/v1/people?id=1&fields=id,first_name,last_name,user"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "first_name": "Joe",
          "last_name": "Smith",
          "user": true
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same people endpoint is used with a filter applied to return only a specific person. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/people?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the person to retrieve
    fields Allows you to return only attributes that you require fields=id,first_name,last_name,user_flag

    Get Updates to People After X

    curl "https://api.foxoms.com/v1/people?fields=id,name,deleted&updated_after=1609802669"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this: Note the additional boolean deleted attribute appears when the updated_after flag

    {
        "data": [
            {
                "id": 162,
                "name": "Adam Miller",
                "deleted": true
            },
            {
                "id": 257,
                "name": "Annie Frank",
                "deleted": false
            },
            {
                "id": 597,
                "name": "Codeception Test 0",
                "deleted": true
            }
        ],
        "meta": {
            "pagination": {
                "total": 14,
                "count": 2,
                "per_page": 10,
                "current_page": 1,
                "total_pages": 2,
                "links": {
                    "next": 2
                }
            }
        }
    }
    

    This endpoint retrieves any people that have been added, edited or even been deleted since an X timestamp. This is useful when you're maintaining a local cache of people or client data and only want to retrieve data that has changed since you last updated your cache.

    An additional boolean deleted attribute is displayed when the updated_after parameter is used.

    HTTP Request

    URL Parameters

    Parameter Description Example
    id The ID of the person to retrieve
    fields Allows you to return only attributes that you require fields=id,start,end
    filter_operator Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    updated_after Return any people added, edited or deleted after the given UNIX timestamp updated_after=1549058744

    Create Person

    POST https://api.foxoms.com/v1/people

    curl "https://api.foxoms.com/v1/people"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "15"
      }
    }
    

    This endpoint allows you to create a person. Use any of the attributes under the GET request. The created person ID will be returned upon successful creation.

    URL Parameters

    Parameter Description Example
    notify_new_user Allows you to disable sending the welcome email to the new user notify_new_user=false

    Update Person

    PUT https://api.foxoms.com/v1/people?id=

    curl "https://api.foxoms.com/v1/people?id=53"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "53"
      }
    }
    

    This endpoint allows you to update a person. Use any of the attributes listed under the GET request with an ID parameter to specify the person you wish to update.

    URL Parameters

    Parameter Description Example
    id The ID of the person to update 28

    Delete Person

    DELETE https://api.foxoms.com/v1/people?id=

    curl "https://api.foxoms.com/v1/people?id=24"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete a person. If the person is also a resource, they will be deleted as well.

    Deleting a person removes them from all bookings, schedules, invoices, projects etc. This cannot be undone so please use caution.

    URL Parameters

    Parameter Description Example
    id The ID of the person to delete 78

    Groups

    Get All Groups

    curl "https://api.foxoms.com/v1/group"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
        "data": [
            {
                "id": 2,
                "name": "Staff",
                "description": "Staff",
                "members": [
                    {
                        "id": 2,
                        "first_name": "Tim",
                        "last_name": "Smith",
                        "primary_email": "[email protected]"
                    },
                    {
                        "id": 4,
                        "first_name": "Jane",
                        "last_name": "Someone",
                        "primary_email": "[email protected]"
                    }
                ],
                "acl_schedule": "RW",
                "acl_project": "RW",
                "acl_task": "RW",
                "acl_finance": "--",
                "acl_admin": "--",
                "acl_account": "--",
                "created_id": 1,
                "created": 1388552400,
                "updated_id": 1,
                "updated": 1388552400
            },
            {
                "id": 3,
                "name": "Administrators",
                "description": "Admins",
                "members": [],
                "acl_schedule": "RW",
                "acl_project": "RW",
                "acl_task": "RW",
                "acl_finance": "RW",
                "acl_admin": "RW",
                "acl_account": "--",
                "created_id": 1,
                "created": 1388552400,
                "updated_id": 1,
                "updated": 1388552400
            },
            {
                "id": 4,
                "name": "Super Administrators",
                "description": "Super Admins",
                "members": [
                    {
                        "id": 5,
                        "first_name": "Steve",
                        "last_name": "Smith",
                        "primary_email": "[email protected]"
                    }
                ],
                "acl_schedule": "RW",
                "acl_project": "RW",
                "acl_task": "RW",
                "acl_finance": "RW",
                "acl_admin": "RW",
                "acl_account": "RW",
                "created_id": 1,
                "created": 1388552400,
                "updated_id": 1,
                "updated": 1388552400
            },
            {
                "id": 6,
                "name": "Editor Admins",
                "description": "",
                "members": [],
                "acl_schedule": "RW",
                "acl_project": "RW",
                "acl_task": "RW",
                "acl_finance": "RW",
                "acl_admin": "--",
                "acl_account": "--",
                "created_id": 1,
                "created": 1488454242,
                "updated_id": 1,
                "updated": 1488454996
            }
        ],
        "meta": {
            "pagination": {
                "total": 4,
                "count": 1,
                "per_page": 4,
                "current_page": 1,
                "total_pages": 1,
                "links": []
            }
        }
    }
    

    This endpoint retrieves all groups. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/group

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,name,description
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only groups that have read and write access to the admin module by adding the following query parameter

    acl_admin=RW

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the group
    name string name Name of the group
    description string description Desription of the group
    members array of objects Lists the members (currently only users) of this group
    acl_schedule string acl_schedule Level of access to the schedule module
    acl_project string acl_project Level of access to the project module
    acl_task string acl_task Level of access to the task module
    acl_finance string acl_finance Level of access to the finance module
    acl_admin string acl_admin Level of access to the admin module
    acl_account string acl_account Level of access to the account module (Reserved for future use)
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated The UNIX time value of the last person (user) who updated this record

    Get a Specific Group

    curl "https://api.foxoms.com/v1/group?id=4&fields=id,name,description,acl_task"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 4,
          "name": "Super Administrators",
          "description": "Super Admins",
          "acl_task": "RW"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same group endpoint is used with a filter applied to return only a specific group. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/group?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the resource to retrieve
    fields Allows you to return only attributes that you require fields=id,name,description,acl_task

    Organizations

    Get All Organizations

    curl "https://api.foxoms.com/v1/organization"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "ABC Australia",
          "client": true,
          "email_1": "",
          "email_2": "",
          "phone_1": "",
          "phone_2": "",
          "address_line_1": "A Line",
          "address_line_2": "B Line",
          "address_line_3": "C Line",
          "address_city": "City",
          "address_state": "VIC",
          "address_postcode": "2023",
          "address_country": "Australia",
          "website": "",
          "notes": "",
          "custom_fields": [
            {
              "id": 3,
              "name": "Organization Field",
              "value": "Test",
              "value_id": 0
            }
          ],
          "created_id": 1,
          "created": 1409651928,
          "updated_id": 1,
          "updated": 1481439436
        },
        ...MORE_RESULTS_TRUNCATED...
      ],
      "meta": {
        "pagination": {
          "total": 2,
          "count": 1,
          "per_page": 2,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all organizations. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/organization

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,name
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only groups that have read and write access to the admin module by adding the following query parameter

    acl_admin=RW

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the organization
    name string name Name of the organization
    client boolean client Is the organization able to be selected as a client on bookings, projects etc.
    email_1 string email_1 First email address
    email_2 string email_2 Second email address
    phone_1 string phone_1 First phone number
    phone_2 string phone_2 Second phone number
    address_line_1 string address_line_1 Address Line 1
    address_line_2 string address_line_2 Address Line 2
    address_line_3 string address_line_3 Address Line 3
    address_city string address_city Address City
    address_state string address_state Address State
    address_postcode string address_postcode Address Postcode
    address_country string address_country Address Country
    website string website Website
    notes string notes Any notes on the organization
    custom_fields array of objects Returns any custom fields that exist for the organization module as well as any values selected for this organization
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the last person (user) who updated this record
    updated integer updated The UNIX time value of when this record was last updated

    Get All Clients

    curl "https://api.foxoms.com/v1/organization/clients"
      -H "Authorization: Bearer 74305f35862b76db"
    

    This endpoint retrieves all organization clients. It is identical to the /organization endpoint except it will only return results of organizations who have client=true. This endpoint allows retrieving clients without requiring admin level ACL permissions.

    The results returned are paginated.

    Get a Specific Organization

    curl "https://api.foxoms.com/v1/organization?id=1&fields=id,name,address_state,address_country"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "ABC Australia",
          "address_state": "VIC",
          "address_country": "Australia"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same organization endpoint is used with a filter applied to return only a specific organization. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/organization?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the resource to retrieve
    fields Allows you to return only attributes that you require fields=id,name,description,address_state,address_country

    Create Organization

    POST https://api.foxoms.com/v1/organization

    curl "https://api.foxoms.com/v1/organization"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "147"
      }
    }
    

    This endpoint allows you to create a organization. Use any of the attributes under the GET request. The created organization ID will be returned upon successful creation.

    URL Parameters

    No URL Parameters are required for creating an organization.

    Update Organization

    PUT https://api.foxoms.com/v1/organization?id=

    curl "https://api.foxoms.com/v1/organization?id=147"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "147"
      }
    }
    

    This endpoint allows you to update an organization. Use any of the attributes listed under the GET request with an ID parameter to specify the organization you wish to update.

    URL Parameters

    Parameter Description Example
    id The ID of the organization to update 28

    Delete Organization

    DELETE https://api.foxoms.com/v1/organization?id=

    curl "https://api.foxoms.com/v1/organization?id=24"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete an organization.

    Deleting an organization removes them from all bookings, invoices, projects etc. This cannot be undone so please use caution.

    URL Parameters

    Parameter Description Example
    id The ID of the organization to delete 78

    Statuses

    Get All Statuses

    curl "https://api.foxoms.com/v1/status"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Pending",
          "description": "The pending status",
          "type_id": 1,
          "notification": 1,
          "order": 0,
          "color_background": "",
          "color_text": "",
          "created_id": 0,
          "created": 0,
          "updated_id": 0,
          "updated": 0
        },
        {
          "id": 2,
          "name": "Confirmed",
          "description": "The confirmed status",
          "type_id": 1,
          "notification": 1,
          "order": 0,
          "color_background": "#ffff00",
          "color_text": "#000000",
          "created_id": 0,
          "created": 0,
          "updated_id": 1,
          "updated": 1559442474
        }
      ],
      "meta": {
        "pagination": {
          "total": 2,
          "count": 1,
          "per_page": 2,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all statuses. Currently only booking statuses are supported, however it will soon be expanded to also support project statuses.

    HTTP Request

    GRT https://api.foxoms.com/v1/status

    Special Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,start,end
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example you can ask the API to only return booking statuses by supplying the following query parameter

    type_id=1

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the status
    name string name Name of the status
    description string description Description of what the status represents
    type_id integer type_id 1 = Booking, 2 = Project (Future Use)
    notification integer notification Should booking notifications be sent for bookings that have this status set? Only applies for statuses with type_id of 1
    order integer order Value representing the order that this status will appear in various menus across the application
    color_background string color_background A hex color value of the background of bookings with this status
    color_text string color_text A hex color value of the text of bookings with this status
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update

    Get a Specific Status

    curl "https://api.foxoms.com/v1/status?id=2&fields=id,name,color_background"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 2,
          "name": "Confirmed",
          "color_background": "#ffff00"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same status endpoint is used with a filter applied to return only a specific status. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/status?id=<ID>

    Reorder Statuses

    To set the order of all the booking statuses, supply an array of ids as shown below.

    curl "https://api.foxoms.com/v1/status/reorder"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '"order": {
            "ids":[109,223,211,237]
            }'
    

    If you need to change the order of many statuses, you can do so in one request, by supplying the new order as an array in an object called "order" to the /status/reorder endpoint.

    Create Status

    POST https://api.foxoms.com/v1/status

    curl "https://api.foxoms.com/v1/status"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value", "key2":"value2"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "192"
      }
    }
    

    This endpoint allows you to create a status. Use any of the attributes listed under the GET request with a type_id parameter to specify the type of status you wish to create.

    The created status ID will be returned upon successful creation.

    Update Status

    PUT https://api.foxoms.com/v1/status?id=

    curl "https://api.foxoms.com/v1/status?id=27"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "27"
      }
    }
    

    This endpoint allows you to update a status. Use any of the attributes listed under the GET request with an ID parameter to specify the status you wish to update.

    Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    Updating the type_id of a Status

    It is currently not possible to update the type_id of a status.

    If you wish to modify the status type_id, you will need to delete the status and then recreate it with the desired type_id.

    URL Parameters

    Parameter Description Example
    id The ID of the status to update 3

    Delete Status

    DELETE https://api.foxoms.com/v1/status?id=

    curl "https://api.foxoms.com/v1/status?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete a status.

    Deleting a status removes it from all existing bookings! This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the status to delete 3

    Custom Fields

    Get All Custom Fields

    curl "https://api.foxoms.com/v1/customfield"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Producer",
          "description": "The name of the producer",
          "type": "text",
          "options": [],
          "module": "project",
          "order": 3,
          "required": true,
          "created_id": 0,
          "created": 0,
          "updated_id": 0,
          "updated": 0
        },
        {
          "id": 2,
          "name": "Lunch Choice",
          "description": "Pick your lunch choice",
          "type": "select",
          "options": [
            {
              "id": "1",
              "name": "Pizza",
              "order": "2"
            },
            {
              "id": "2",
              "name": "Butter Chicken Curry",
              "order": "0"
            },
            {
              "id": "3",
              "name": "Sushi",
              "order": "1"
            },
            {
              "id": "4",
              "name": "Lasanya",
              "order": "3"
            }
          ],
          "module": "project",
          "order": 1,
          "required": true,
          "created_id": 0,
          "created": 0,
          "updated_id": 0,
          "updated": 0
        },
        {
          "id": 3,
          "name": "Organization Field",
          "description": "",
          "type": "text",
          "options": [],
          "module": "organization",
          "order": 0,
          "required": false,
          "created_id": 1,
          "created": 1476831564,
          "updated_id": 1,
          "updated": 1476831564
        },
        {
          "id": 4,
          "name": "PO Field",
          "description": "This is a PO Field",
          "type": "text",
          "options": [],
          "module": "quote_invoice",
          "order": 0,
          "required": false,
          "created_id": 1,
          "created": 1477423612,
          "updated_id": 1,
          "updated": 1477423612
        },
        {
          "id": 5,
          "name": "Other Field",
          "description": "",
          "type": "select",
          "options": [
            {
              "id": "5",
              "name": "Test",
              "order": "0"
            },
            {
              "id": "6",
              "name": "Testing",
              "order": "1"
            },
            {
              "id": "7",
              "name": "Testing Again",
              "order": "2"
            }
          ],
          "module": "invoice",
          "order": 0,
          "required": false,
          "created_id": 1,
          "created": 1477509348,
          "updated_id": 1,
          "updated": 1477509719
        },
        {
          "id": 6,
          "name": "Booking Type",
          "description": "",
          "type": "select",
          "options": [
            {
              "id": "8",
              "name": "0. Grade",
              "order": "0"
            },
            {
              "id": "9",
              "name": "1. Sound Mix",
              "order": "1"
            },
            {
              "id": "10",
              "name": "2. Picture Edit",
              "order": "2"
            }
          ],
          "module": "booking",
          "order": 0,
          "required": false,
          "created_id": 1,
          "created": 1478544788,
          "updated_id": 1,
          "updated": 1489358581
        },
        {
          "id": 7,
          "name": "Booking Producer",
          "description": "",
          "type": "text",
          "options": [],
          "module": "booking",
          "order": 2,
          "required": true,
          "created_id": 1,
          "created": 1479506071,
          "updated_id": 1,
          "updated": 1489383284
        },
        {
          "id": 8,
          "name": "Extra Postcode",
          "description": "",
          "type": "text",
          "options": [],
          "module": "people",
          "order": 0,
          "required": false,
          "created_id": 1,
          "created": 1481432042,
          "updated_id": 1,
          "updated": 1481432042
        }
      ],
      "meta": {
        "pagination": {
          "total": 9,
          "count": 1,
          "per_page": 9,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all custom fields. The results returned are paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/customfield

    Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,name
    limit 10 The number of results returned per page limit=50

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only text based custom fields by adding the following query parameter

    type=text

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the custom field
    name string name Name of the custom field
    description string description Comments on the what information is tracked by the custom field
    type string type Input type of field, eg text input or select menu
    options array of objects The available options for this field (if type is set to select)
    module string module The module that this custom field is assigned to
    order integer order The order in which the custom field appears
    required boolean required Does this field need to be filled in or can it be left blank
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update

    Types of Custom Fields

    Type ID Type
    1 Text Field
    2 Select Menu
    3 Text Area

    Custom Field Modules

    Module ID Module
    1 Boooking
    4 Project
    5 People
    6 Organization
    7 Quote
    8 Invoice
    9 Quote and Invoice Shared

    Get a Specific Custom Field

    curl "https://api.foxoms.com/v1/customfield?id=4&fields=id,name,type,module"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 4,
          "name": "PO Field",
          "type": "text",
          "module": "quote_invoice"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same custom field endpoint is used with a filter applied to return only a specific custom field. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/customfield?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the custom field to retrieve
    fields Allows you to return only attributes that you require fields=id,name,type

    Rate Schemes

    Get All Rate Schemes

    curl "https://api.foxoms.com/v1/ratescheme"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "type_id": 1,
          "name": "Edit Suites",
          "description": "",
          "booking_description_template": "[rateSchemeName] - [rateSchemeDescription]\n[bookingName] - [rateSchemeStartDateCode]|(D jS M Y g:iA) --> [rateSchemeEndDateCode]|(D jS M Y g:iA)",
          "resources": [
            {
              "id": 1,
              "name": "Edit Suite 1",
              "description": "Avid Media Composer",
              "type_id": 1,
              "type_user_id": 0,
              "parent_id": 0,
              "parent_name": ""
            },
            {
              "id": 2,
              "name": "Edit Suite 2",
              "description": "Avid Media Composer",
              "type_id": 1,
              "type_user_id": 0,
              "parent_id": 0,
              "parent_name": ""
            },
            {
              "id": 3,
              "name": "Edit Suite 3",
              "description": "Avid ProTools",
              "type_id": 1,
              "type_user_id": 0,
              "parent_id": 0,
              "parent_name": ""
            }
          ],
          "clients": [],
          "projects": [],
          "custom_field_options": [],
          "hour_rate": "55.00",
          "day_rate": "150.00",
          "fixed_date": false,
          "date_start": "0000-00-00",
          "date_end": "0000-00-00",
          "time_start": "00:00:00",
          "time_end": "00:00:00",
          "overtime_hours": "0.00",
          "override_base": true,
          "default_unit": 0,
          "default_tax": true,
          "note": "",
          "created_id": 0,
          "created": 1534572218,
          "updated_id": 0,
          "updated": 1534572218
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves all rate schemes. The results are returned paginated.

    HTTP Request

    GET https://api.foxoms.com/v1/ratescheme

    Query Paramaters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,start,end
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    where_in_resource false Allows returning only rate schemes that have been assigned to one or more resource ids where_in_resource=45,233,898

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example, you can return only rateschemes that have a type id of 4 by adding the following query parameter

    type_id=4

    You can also separate multiple search values by a comma, for example to return multiple records.

    id=2,3,43,109,23

    You can also concatenate multiple attributes to search for and change the filtering logic using the filter_operator

    id=5&type_id=3&filter_operator=AND

    The above code snippet would only return records that have an id of 5 AND a type_id of 3

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the rate scheme
    name string name Name of the Rate Scheme
    type_id integer type_id 1 = Base Rate, 2 = Seasonal Adjustment, 3 = Hourly Adjustment, 4 = Client Adjustment, 5 = Advanced Adjustment (Deprecated), 6 = Project Adjustment, 7 = Overtime Adjustment, 8 = Custom Field Option Adjustment
    description string description A description on what this rate scheme is for. Could be customer facing if using in the booking description template
    booking_description_template string booking_description_template Template used for quote/invoice line item descriptions when prefilled from a booking
    resources array of objects Returns resources that have been added to this rate scheme
    clients array of objects Returns people and organizations that have been added as clients to this rate scheme
    projects array of objects Returns projects that have been added to this rate scheme
    custom_field_options array of objects Returns custom field options that have been added to this rate scheme
    hour_rate string hour_rate The hourly rate of all resources scoped to this rate scheme
    hour_rate_percent boolean hour_rate_percent If the hourly rate is actually a percentage (worked out from a base rate)
    day_rate string day_rate The daily rate of all resources scoped to this rate scheme
    day_rate_percent boolean day_rate_percent If the daily rate is actually a percentage (worked out from a base rate)
    fixed_date boolean fixed_date True if the rate scheme does not recur every year
    date_start string date_start Date this rate scheme starts in SQL Date format
    date_end string date_end Date this rate scheme ends in SQL Date format
    time_start string time_start Time this rate scheme starts in SQL Time format
    time_end string time_end Time this rate scheme ends in SQL Time format
    overtime_hours string overtime_hours Number of hours can elapse in a booking before it goes into overtime
    override_base boolean override_base False = don't override any other base rates, True = Override other base rates and replace with this one
    default_unit integer default_unit 0 = Hourly, 1 = Daily
    default_tax boolean default_tax 0 = Dont Apply Tax, 1 = Apply Tax
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update

    Get a Specific Rate Scheme

    curl "https://api.foxoms.com/v1/ratescheme?id=3&fields=id,name,date_start,date_end"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 3,
          "name": "Project Discounts",
          "date_start": "0000-00-00",
          "date_end": "0000-00-00"
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    The same endpoint is used with a filter applied to return only a specific ratescheme. We've also specifically requested the fields we need to improve speed and efficiency.

    HTTP Request

    GET https://api.foxoms.com/v1/ratescheme?id=<ID>

    URL Parameters

    Parameter Description Example
    id The ID of the ratescheme to retrieve
    fields Allows you to return only attributes that you require fields=id,start,end
    filter_operator Allows overriding of the default filtering method (either AND or OR). filter_operator=AND

    Create Rate Scheme

    POST https://api.foxoms.com/v1/ratescheme

    curl "https://api.foxoms.com/v1/ratescheme"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "155"
      }
    }
    

    To set one or more resources on the rate scheme

    # body.json
    {
        "resources":{
            "ids":[2,3,99]
        }
    }
    
    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        --data-binary @body.json
    

    To set one or more clients on the rate scheme

    # body.json
    {
        "clients":{
            "ids":["p8","o2"]
        }
    }
    
    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        --data-binary @body.json
    

    To set one or more projects on the rate scheme

    # body.json
    {
        "projects":{
            "ids":[2,4,80]
        }
    }
    
    curl "https://api.foxoms.com/v1/resource"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        --data-binary @body.json
    

    This endpoint allows you to create a rate scheme of any type. Use any of the combinations listed under the GET request with a type_id paramater to specify the type of rate schem you wish to create.

    The newly created rate scheme ID will be returned upon successful creation.

    Setting hourly or daily rates

    If you wish to set an hourly or daily rate on a base rate scheme, it must be a whole decimal number. All other rate scheme (adjustments) are allowed to be set as percentages.

    Update Rate Scheme

    PUT https://api.foxoms.com/v1/ratescheme?id=

    curl "https://api.foxoms.com/v1/ratescheme?id=15"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to update a rate scheme. Use any of the attributes listed under the GET request with an ID parameter to specify the rate scheme you wish to update. Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    URL Parameters

    Parameter Description Example
    id The ID of the rate scheme to update 3

    Delete Rate Scheme

    DELETE https://api.foxoms.com/v1/ratescheme?id=

    curl "https://api.foxoms.com/v1/ratescheme?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete a rate scheme.

    Deleting a ratescheme does not affect any existing invoices or quotes. This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the rate scheme to delete 3

    Instance Account

    Get Account Info

    curl "https://api.foxoms.com/v1/account"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "active": true,
          "package": [
            {
              "id": 9,
              "name": "FoxOMS (Trial)",
              "description": "",
              "allowed_users": 40,
              "allowed_resources": 80,
              "allowed_schedules": 5
            }
          ],
          "total_users": 4,
          "total_resources": 9,
          "total_schedules": 5
        }
      ],
      "meta": {
        "pagination": {
          "total": 1,
          "count": 1,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": []
        }
      }
    }
    

    This endpoint retrieves the data related to your FoxOMS account instance.

    HTTP Request

    GET https://api.foxoms.com/v1/account

    Attributes

    Name Type Filter Param Description
    active boolean active Whether this FoxOMS instance / account is active or not
    package array of objects Details of the package in use
    total_users integer total_users Total users in use
    total_resources integer total_resources Total resources in use
    total_schedules integer total_schedules Total schedules in use
    this_user array of objects Information about the account being used to connect to the API

    Rest Hooks

    Rest hooks allow you to subscribe to certain events when they occur within FoxOMS.

    You can subscribe to the following events:

    Get All Rest Hooks

    curl "https://api.foxoms.com/v1/resthook"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
        "data": [
            {
                "id": 7,
                "event_name": "bookingCreated",
                "target_url": "https://hooks.foxoms.com/fake-subscription-url",
                "triggered_count": 0,
                "last_triggered": 0,
                "created_id": 1,
                "created": 1597279654,
                "updated_id": 1,
                "updated": 1597279654
            },
            {
                "id": 8,
                "event_name": "bookingCreated",
                "target_url": "https://hooks.foxoms.com/fake-subscription-url",
                "triggered_count": 0,
                "last_triggered": 0,
                "created_id": 1,
                "created": 1597304823,
                "updated_id": 1,
                "updated": 1597304823
            }
        ],
        "meta": {
            "pagination": {
                "total": 4,
                "count": 1,
                "per_page": 4,
                "current_page": 1,
                "total_pages": 1,
                "links": []
            }
        }
    }
    

    This endpoint retrieves all active rest hooks.

    HTTP Request

    GRT https://api.foxoms.com/v1/resthook

    Special Query Parameters

    Parameter Default Description Example
    page false Return results pertaining to that page page=3
    fields false Allows you to return only attributes that you require fields=id,start,end
    limit 10 The number of results returned per page limit=50
    filter_operator OR Allows overriding of the default filtering method (either AND or OR). filter_operator=AND
    order_asc id Allows ordering of results by any attribute order_asc=order
    order_desc false Allows ordering of results by any attribute order_desc=order

    Filtering Results

    You can also filter the results by specifying almost any attribute returned as a parameter.

    For example you can ask the API to only return rest hooks for the bookingCreated event by supplying the following query parameter

    event_name=bookingCreated

    Attributes

    Name Type Filter Param Description
    id integer id Unique ID of the resthook
    event_name string event_name The event name this webhook is subscribed to
    target_url string target_url The target URL we will push updates to
    triggered_count integer triggered_count The number of times we have triggered this URL
    last_triggered integer last_triggered The UNIX timestamp that this was last triggered
    created_id integer created_id The unique ID of the person (user) who created this record
    created integer created The UNIX time value of the creation time
    updated_id integer updated_id The unique ID of the person (user) who last updated this record
    updated integer updated The UNIX time value of the last update

    Get a Specific Resthook

    curl "https://api.foxoms.com/v1/resthook?id=10&fields=id,event_name,target_url"
      -H "Authorization: Bearer 74305f35862b76db"
    

    The above command returns JSON structured like this:

    {
        "data": [
            {
                "id": 10,
                "event_name": "bookingCreated",
                "target_url": "https://hooks.foxoms.com/fake-subscription-url"
            }
        ],
        "meta": {
            "pagination": {
                "total": 1,
                "count": 1,
                "per_page": 1,
                "current_page": 1,
                "total_pages": 1,
                "links": []
            }
        }
    }
    

    The same rest hook endpoint is used with a filter applied to return only a specific rest hook. We've also specifically requested the fields we need to improve speed and readability.

    HTTP Request

    GET https://api.foxoms.com/v1/resthook?id=<ID>

    Create Rest Hook

    POST https://api.foxoms.com/v1/resthook

    curl "https://api.foxoms.com/v1/resthook"
        -X POST
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value", "key2":"value2"}'
    

    event_name and target_url are required fields

    {
        "event_name":"bookingCreated",
        "target_url":"https://hooks.foxoms.com/fake-subscription-url"
    }
    

    A successful create will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "192"
      }
    }
    

    This endpoint allows you to create a resthook. Use any of the attributes listed under the GET request.

    The created rest hook ID will be returned upon successful creation.

    Update Rest Hook

    PUT https://api.foxoms.com/v1/resthook?id=

    curl "https://api.foxoms.com/v1/resthook?id=27"
        -X PUT
        -H "Authorization: Bearer 74305f35862b76db"
        -H "Content-Type: application/json"
        -d '{"key1":"value"}'
    

    A successful update will return the following JSON:

    {
      "status": {
        "success": true,
        "id": "27"
      }
    }
    

    This endpoint allows you to update a resthook. Use any of the attributes listed under the GET request with an ID parameter to specify the rest hook you wish to update.

    Also see the notes under the Create documentation for more hints on what behaviours you might encounter.

    Delete Rest Hook

    DELETE https://api.foxoms.com/v1/resthook?id=

    curl "https://api.foxoms.com/v1/resthook?id=1"
        -X DELETE
        -H "Authorization: Bearer 74305f35862b76db"
    

    A successful delete will return the following JSON:

    {
      "status": {
        "success": true
      }
    }
    

    This endpoint allows you to delete a resthook.

    This cannot be undone so be careful.

    URL Parameters

    Parameter Description Example
    id The ID of the rest hook to delete 3

    Errors

    The FoxOMS API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications
    401 Unauthorized -- If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials
    403 Forbidden -- The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated
    404 Not Found -- The server has not found anything matching the Request-URI.
    409 Conflict -- The request could not be completed due to a conflict with the current state of the resource
    429 Too Many Requests -- We allow a maximum of 1 request per second
    500 Internal Server Error -- The server encountered an unexpected condition which prevented it from fulfilling the request
    503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

    Upgrade Notes

    API Updates

    The FoxOMS REST API is constantly being improved and updated and although we do our very best to avoid making changes that break backwards compatibility, it is sometimes simply unavoidable. Here you'll find information about the changes made, to allow you to update your software to be compatible with our API.

    2020.3

    This update introduced the new work orders module but also updated both the quote and invoice endpoints.

    Quotes / Invoices

    Previous Attribute Previous Datatype New Attribute New Datatype Notes
    client_person_id integer client array of single object You can now access the client id by using client->id
    client_organization_id integer client array of single object You can now access the client id by using client->id
    project_id integer project array of single object You can now access the project id by using project->id

    Quotes->Items / Invoices->Items

    Previous Attribute Previous Datatype New Attribute New Datatype Notes
    object_type string item_type string Name change
    object_id integer item_id integer Name change
    N/A N/A type_id integer 0 = Custom, 1 = Resource, 2 = Billable Item
    N/A N/A ratescheme_id integer The ID of the ratescheme (if used to populate a resource)
    type string source_name string Name change