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)
As of August 2019, all actions completed in the FoxOMS REST API will now check and enforce the ACL's specified for the FoxOMS user that the API token was generated against.
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 an additional safeguard against some 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 records.
If you'd like just a single record you can issue an ?id= parameter (eg /booking?id=933894
).
Filtering can also be achieved on most endpoints by adding additional fields into the parameter string (eg /booking?id=5&status_id=3&filter_operator=AND
).
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.
FoxOMS has two authentication options that allow access to the API. You can choose to authenticate either with OAuth 2.0 (recommended) or Token Based Authentication.
You can register an API client for either authentication option under API Settings in the Admin section of your FoxOMS account.
Regardless of the authentication method you choose, 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
OAuth 2.0
The FoxOMS API supports OAuth 2.0, by generating a Client Id and Client Secret which you use to authenticate to our https://api.foxoms.com/token
endpoint and retrieve a token. This 'Authentication Token' is then included with your requests to gain access to the API.
OAuth 2.0 Token Expiry
A security feature of OAuth 2.0 is that the Authentication tokens generated expire after 2 hours and your application will need to submit the Client Id and Client Secret to https://api.foxoms.com/token
to continue using the API.
Token Based
We also offer a simpler 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. This method is considered less secure because these tokens do not expire.
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"
}
],
"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,
"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,
"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,
"updated": 1549861886,
"icon": {
"name": "1",
"alias": "63241c3d48630432920ee9baab8811",
"extension": "jpg"
}
},
{
"id": 8,
"name": "Timothy",
"description": "",
"type_id": 2,
"type_person_id": 2,
"parent_id": 9,
"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"
}
],
"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 |
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
Name | Type | Description |
---|---|---|
id | integer | Unique ID of the booking |
name | string | Name of the booking |
start | integer | UNIX time of the start of the booking |
end | integer | 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 |
all_day | boolean | True if this is an all day booking (no times are recorded) |
notes | string | Any notes added to the booking |
repeat_master | boolean | True if this booking is a master from a set of repeating bookings |
repeat_master_id | integer | 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 | The repetition logic that determines the frequency and amount of repetitions |
project | array of single object | The project assigned to this booking. Use the project_id paramater to filter bookings by project |
client | array of single object | The client (either person or organization) attached to this booking |
status | array of single object | The status assigned to this booking |
resources | array of objects | 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 |
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 |
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 | false | Allows returning only bookings that are linked to one or more of these resource IDs |
from_time | false | Return any bookings starting after the given UNIX timestamp |
to_time | false | Return any bookings starting before the given UNIX timestamp |
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": 178,
"name": "Something else",
"start": 1488417600,
"end": 1488431400,
"start_date_time": "02/03/2017 12:20",
"end_date_time": "02/03/2017 16:10",
"resources": [
{
"id": 1,
"name": "Edit Suite 1",
"description": "Avid Media Composer",
"type_id": 1,
"parent_id": 0
},
{
"id": 2,
"name": "Edit Suite 2",
"description": "Avid Media Composer",
"type_id": 1,
"parent_id": 0
}
]
}
],
"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]
}'
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
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
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,
"start": 1365811200,
"end": 1374969600,
"private": true,
"parent_folder_id": 5,
"client_person_id": 0,
"client_organization_id": 0,
"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": {
"5": {
"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
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 |
show_folders | false | Returns project folders amongst the projects, useful if you have to built a project tree of projects and their folders | show_folders=true |
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 | Description |
---|---|---|
id | integer | Unique ID of the project |
name | string | Title of the project |
code | string | Short code used to identify the project |
description | string | A couple of sentences used to describe the purpose of the project |
status_id | integer | Unique ID of the selected status |
start | integer | UNIX time of the start of the project timeframe |
end | integer | UNIX time of the end of the project timeframe |
private | boolean | Is the project viewable to everyone, or just the users and groups assigned |
parent_folder_id | integer | The ID of the folder that this project is sitting in |
client_person_id | integer | Unique ID of the person selected as a client |
client_organization_id | integer | Unique ID of the organization selected as a client |
order | integer | The order that this project appears (if a custom order has been specified) |
color_background | string | A hex color value of the background of this project |
color_text | string | A hex color value of the text of 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 |
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 |
Get a Specific 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 |
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": 16,
"prefix": "INV-",
"number": 6002,
"date": 1484372456,
"due_date": 1486964456,
"client_person_id": 3,
"client_organization_id": 0,
"project_id": 0,
"status_id": 1,
"items": [
{
"id": 21,
"object_type": "resource",
"object_id": 1,
"booking_id": 0,
"item": "Edit Suite 1",
"type": "Base Rate",
"description": "",
"order": 0,
"quantity": "10.00",
"unit": "hourly",
"cost": "15.00",
"tax": true,
"discount": "100.00",
"total": "0.00"
},
{
"id": 22,
"object_type": "custom",
"object_id": 0,
"booking_id": 0,
"item": "Something",
"type": "",
"description": "Custom thing",
"order": 1,
"quantity": "5.00",
"unit": "hourly",
"cost": "10.00",
"tax": true,
"discount": "0.00",
"total": "50.00"
}
],
"custom_fields": [
{
"id": 5,
"name": "Other Field",
"value": "Test",
"value_id": 5
},
{
"id": 4,
"name": "PO Field",
"value": null,
"value_id": 0
}
],
"sub_total": "200.00",
"discount_total": "150.00",
"tax_total": "0.00",
"total": "50.00",
"template_id": 0,
"currency": "AUD",
"tax_rate": "0.00",
"created_id": 1,
"created": 1484373044,
"updated_id": 1,
"updated": 1486279626
},
...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 |
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 | Description |
---|---|---|
id | integer | Unique ID of the invoice |
prefix | string | Prefix to the invoice number |
number | integer | Number of the invoice |
date | integer | UNIX time of the date shown on the invoice |
due_date | integer | UNIX time of the due date shown on the invoice |
client_person_id | integer | Unique ID of the person selected as client |
client_organization_id | integer | Unique ID of the organization selected as a client |
project_id | integer | Unique ID of the project linked to this invoice |
status_id | integer | Unique ID of the selected status |
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 | Total of all invoice items before tax and discounts are applied |
discount_total | decimal | Total amount discounted from the invoice |
tax_total | decimal | The amount of tax charged on the invoice |
total | decimal | The final amount of this invoice |
template_id | integer | The ID of the invoice template being used |
currency | string | Currency code (two character format) that this invoice is in |
tax_rate | decimal | The tax rate percent that was applied to this invoice |
created_id | integer | The unique ID of the person (user) who created this record |
created | integer | UNIX time of the creation time |
updated_id | integer | The unique ID of the last person (user) who updated this record |
updated | integer | UNIX time value of the last update to this record |
Item Attributes
Name | Type | Description |
---|---|---|
id | integer | Unique ID of this item |
object_type | string | Either resource or custom |
object_id | integer | The unique ID (if applicable) of the object defined in object_type |
booking_id | integer | The unique booking ID that this item relates to. Only applies if this invoice was 'prefilled' from a booking |
item | string | Item field |
type | string | Type field |
description | string | Description field |
order | integer | The order that this invoice item is in, relative to the other invoice items |
quantity | decimal | Number of unit field |
unit | string | Unit, eg hourly, daily |
cost | decimal | Cost applied |
tax | boolean | Is tax applied? |
discount | decimal | The amount of discount applied |
total | decimal | Total of this invoice item |
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,
"project_id": 0,
"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,project_id,total |
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": 14,
"prefix": "QU-",
"number": 11,
"date": 1481021579,
"due_date": 1483613579,
"client_person_id": 4,
"client_organization_id": 0,
"project_id": 0,
"status_id": 1,
"items": [
{
"id": 16,
"object_type": "resource",
"object_id": 1,
"booking_id": 102,
"item": "Edit Suite 1",
"type": "Booking (Base Rate)",
"description": "TEST (Mon 24th Oct 2016 5:30AM - Mon 24th Oct 2016 7:05PM)",
"order": 0,
"quantity": "13.58",
"unit": "hourly",
"cost": "15.00",
"tax": true,
"discount": "0.00",
"total": "203.70"
},
{
"id": 17,
"object_type": "resource",
"object_id": 2,
"booking_id": 102,
"item": "Edit Suite 2",
"type": "Booking (Base Rate)",
"description": "TEST (Mon 24th Oct 2016 5:30AM - Mon 24th Oct 2016 7:05PM)",
"order": 1,
"quantity": "13.58",
"unit": "hourly",
"cost": "15.00",
"tax": true,
"discount": "0.00",
"total": "203.70"
},
{
"id": 18,
"object_type": "resource",
"object_id": 1,
"booking_id": 107,
"item": "Edit Suite 1",
"type": "Booking (Base Rate)",
"description": "TEST (Tue 25th Oct 2016 5:30AM - Tue 25th Oct 2016 7:05PM)",
"order": 2,
"quantity": "13.58",
"unit": "hourly",
"cost": "15.00",
"tax": true,
"discount": "0.00",
"total": "203.70"
},
{
"id": 19,
"object_type": "resource",
"object_id": 2,
"booking_id": 107,
"item": "Edit Suite 2",
"type": "Booking (Base Rate)",
"description": "TEST (Tue 25th Oct 2016 5:30AM - Tue 25th Oct 2016 7:05PM)",
"order": 3,
"quantity": "13.58",
"unit": "hourly",
"cost": "15.00",
"tax": true,
"discount": "0.00",
"total": "203.70"
}
],
"custom_fields": [
{
"id": 9,
"name": "Quote Field",
"value": null,
"value_id": 0
},
{
"id": 4,
"name": "PO Field",
"value": null,
"value_id": 0
}
],
"sub_total": "814.80",
"discount_total": "0.00",
"tax_total": "0.00",
"total": "814.80",
"template_id": 0,
"currency": "AUD",
"tax_rate": "0.00",
"created_id": 1,
"created": 1481021592,
"updated_id": 1,
"updated": 1481021592
},
...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 |
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 | Description |
---|---|---|
id | integer | Unique ID of the quote |
prefix | string | Prefix to the quote number |
number | integer | Number of the quote |
date | integer | UNIX time of the date shown on the quote |
due_date | integer | UNIX time of the due date shown on the quote |
client_person_id | integer | Unique ID of the person selected as client |
client_organization_id | integer | Unique ID of the organization selected as a client |
project_id | integer | Unique ID of the project linked to this quote |
status_id | integer | Unique ID of the selected status |
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 | Total of all quote items before tax and discounts are applied |
discount_total | decimal | Total amount discounted from the quote |
tax_total | decimal | The amount of tax charged on the quote |
total | decimal | The final amount of this quote |
template_id | integer | The ID of the quote template being used |
currency | string | Currency code (two character format) that this quote is in |
tax_rate | decimal | The tax rate percent that was applied to this quote |
created_id | integer | The unique ID of the person (user) who created this record |
created | integer | UNIX time of the creation time |
updated_id | integer | The unique ID of the last person (user) who updated this record |
updated | integer | UNIX time value of the last update to this record |
Item Attributes
Name | Type | Description |
---|---|---|
id | integer | Unique ID of this item |
object_type | string | Either resource or custom |
object_id | integer | The unique ID (if applicable) of the object defined in object_type |
booking_id | integer | The unique booking ID that this item relates to. Only applies if this quote was 'prefilled' from a booking |
item | string | Item field |
type | string | Type field |
description | string | Description field |
order | integer | The order that this quote item is in, relative to the other quote items |
quantity | decimal | Number of unit field |
unit | string | Unit, eg hourly, daily |
cost | decimal | Cost applied |
tax | boolean | Is tax applied? |
discount | decimal | The amount of discount applied |
total | decimal | Total of this quote item |
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 |
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,
"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,
"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.fooxms.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 | Description |
---|---|---|
id | integer | Unique ID of the billable item |
name | string | Title of the billable item |
description | string | Description of the billable item |
unit_name | string | Name of the unit shown on the quote or invoice |
cost | decimal | Total cost of the billable item |
default_tax | boolean | Add tax to item by default |
order | integer | Value representing the order that this item will appear in the billable items admin section |
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 |
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>
Reorder Billable Items
To set the order of all the billable items, supply an array of ids as shown below.
curl "https://api.foxoms.com/v1/billableitem/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 billable items, you can do so in one request, by supplying the new order as an array in an object called "order" to the /billableitem/reorder
endpoint.
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 |
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 | Description |
---|---|---|
id | integer | Unique ID of the invoice template |
name | string | Name of the invoice template |
description | string | Desription of the invoice template |
type_id | integer | 1 = Invoice, 2 = Quote |
default | boolean | True means this invoice template will be selected by default on the creation of new invoice |
title | string | The title shown in the top left hand corner of the template, usually QUOTE or INVOICE |
logo | array of single object | Returns the logo image file of this invoice template |
top_left_container | string | Top left container of the invoice |
top_center_container | string | Top center container of the invoice |
top_right_container | string | Top right container of the invoice |
middle_left_container | string | Middle left container of the invoice |
middle_center_container | string | Middle center container of the invoice |
middle_right_container | string | Middle right container of the invoice |
bottom_left_container | string | Bottom left container of the invoice |
bottom_center_container | string | Bottom center container of the invoice |
bottom_right_container | string | Bottom right container of the invoice |
created_id | integer | The unique ID of the person (user) who created this record |
created | integer | UNIX time of the creation time |
updated_id | integer | The unique ID of the last person (user) who updated this record |
updated | integer | 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 |
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 resources that have a type id of 2 by adding the following query parameter
type_id=2
Attributes
Name | Type | Description |
---|---|---|
id | integer | Unique ID of the resource |
name | string | Title of the resource |
description | string | Description of the resource |
schedules | array of objects | Returns schedules that this resource has been added to |
type_id | integer | 1 = Room, 2 = Person, 3 = Equipment, 4 = Resource Group, 5 = Action |
type_person_id | integer | The unique ID of the person (only applies if this resource is a person) |
parent_id | integer | The unigue ID of the resource group that this resource is a child of |
order | integer | Value representing the order that this resource will appear in various parts of the application |
icon | array of single object | Returns the image file of this resource icon |
color_background | string | A hex color value of the background of this resource |
color_text | string | A hex color value of the text of this resource |
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 |
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 Background 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 |
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
},
{
"id": 2,
"name": "Edit Suite 2",
"description": "Avid Media Composer",
"type_id": 1,
"type_person_id": 0,
"parent_id": 0
},
{
"id": 7,
"name": "Joe Smith",
"description": "",
"type_id": 2,
"type_person_id": 15,
"parent_id": 9
},
{
"id": 9,
"name": "Staff",
"description": "",
"type_id": 4,
"type_person_id": 0,
"parent_id": 0
}
],
"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 |
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 |
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 | Description |
---|---|---|
id | integer | Unique ID of the schedule |
name | string | Title of the schedule |
description | string | 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 | The order that this schedule will appear in the returned results |
sunday_start | boolean | If the week starts with a Sunday (true) or on Monday (false) |
working_week | integer | The working week configuration for this schedule. 0 = Monday -> Friday, 1 = Monday -> Saturday, 2 = Saturday -> Thursday, 3 = Sunday -> Thursday |
first_hour | integer | The first hour shown on the schedule (0 - 23) |
last_hour | integer | The last hour shown on the schedule (1 - 24) |
scroll_hour | integer | The hour to scroll to on load (applies to daily and weekly calendar views only) (1 - 12) |
time_step_min | integer | The number of minutes between each ‘step’ on the schedule (5,10,15,30,60) |
fill_cell | boolean | 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) |
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 |
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
},
{
"id": 29,
"name": "Edit Action",
"description": "",
"type_id": 5,
"type_person_id": 0,
"parent_id": 0
}
]
}
],
"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 |
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 Somehwere",
"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 |
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 people that have been designated as users by adding the following query parameter
user_flag=1
Attributes
Name | Type | Description |
---|---|---|
id | integer | Unique ID of the person |
first_name | string | First name of the person |
last_name | string | Last name of the person |
username | string | Username that can be used to login |
primary_email | string | The main email of the person, also can be used to login |
user | boolean | Is the person selected as a user |
resource | boolean | Is the person selected as a resource |
client | boolean | Is the person selected as a client |
resource_id | integer | The unique ID of the resource that this person is linked to. Only applies if resource is set to TRUE |
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 | The unique ID of the group that this person (user) is added to |
organization_id | integer | The unique ID of the organization that this person is added to |
organization | array of objects | The organization that this person has been added to |
email_2 | string | Second email address |
email_3 | string | Third email address |
phone_1 | string | Phone 1 |
phone_2 | string | Phone 2 |
phone_3 | string | Phone 3 |
address_line_1 | string | Address Line 1 |
address_line_2 | string | Address Line 2 |
address_line_3 | string | Address Line 3 |
address_city | string | Address City |
address_state | string | Address State |
address_postcode | string | Address Postcode |
address_country | string | Address Country |
website | string | Website |
notes | string | Any notes on the person |
timezone | string | Timezone selected by the person (user) |
locale | string | Locale selected by the person (user) |
date_format | string | Date Format selected by the person (user) |
time_format | string | Time Format selected by the person (user) |
notifications | boolean | Does this person want to receive email notifications |
avatar_file_id | integer | Unique image file ID linked to this person |
expires | integer | Account expiry date in UNIX time |
schedule_view_mode | integer | Applies only to people with the User and Resource flags both set to True. 0 = Show all bookings, 1 = Anonymise other bookings, 2 = Hide other bookings |
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 | 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 last person (user) who updated this record |
updated | integer | The UNIX time value of when this record was last updated |
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 |
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
No URL Parameters are required for creating a person.
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 |
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 | Description |
---|---|---|
id | integer | Unique ID of the group |
name | string | Name of the group |
description | string | Desription of the group |
members | array of objects | Lists the members (currently only users) of this group |
acl_schedule | string | Level of access to the schedule module |
acl_project | string | Level of access to the project module |
acl_task | string | Level of access to the task module |
acl_finance | string | Level of access to the finance module |
acl_admin | string | Level of access to the admin module |
acl_account | string | Level of access to the account module (Reserved for future use) |
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 last person (user) who updated this record |
updated | integer | 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 |
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 | Description |
---|---|---|
id | integer | Unique ID of the organization |
name | string | Name of the organization |
client | boolean | Is the organization able to be selected as a client on bookings, projects etc. |
email_1 | string | First email address |
email_2 | string | Second email address |
phone_1 | string | First phone number |
phone_2 | string | Second phone number |
address_line_1 | string | Address Line 1 |
address_line_2 | string | Address Line 2 |
address_line_3 | string | Address Line 3 |
address_city | string | Address City |
address_state | string | Address State |
address_postcode | string | Address Postcode |
address_country | string | Address Country |
website | string | Website |
notes | string | 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 | 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 last person (user) who updated this record |
updated | integer | 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.fooxms.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 | Description |
---|---|---|
id | integer | Unique ID of the status |
name | string | Name of the status |
description | string | Description of what the status represents |
type_id | integer | 1 = Booking, 2 = Project (Future Use) |
notification | integer | Should booking notifications be sent for bookings that have this status set? Only applies for statuses with type_id of 1 |
order | integer | Value representing the order that this status will appear in various menus across the application |
color_background | string | A hex color value of the background of bookings with this status |
color_text | string | A hex color value of the text of bookings with this status |
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 |
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 | Description |
---|---|---|
id | integer | Unique ID of the custom field |
name | string | Name of the custom field |
description | string | Comments on the what information is tracked by the custom field |
type | string | Input type of field, eg text input, select menu or textarea |
options | array of objects | The available options for this field (if type is set to select) |
module | string | The module that this custom field is assigned to |
order | integer | The order in which the custom field appears |
required | boolean | Does this field need to be filled in or can it be left blank |
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 |
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
},
{
"id": 2,
"name": "Edit Suite 2",
"description": "Avid Media Composer",
"type_id": 1,
"type_user_id": 0,
"parent_id": 0
},
{
"id": 3,
"name": "Edit Suite 3",
"description": "Avid ProTools",
"type_id": 1,
"type_user_id": 0,
"parent_id": 0
}
],
"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 | Description |
---|---|---|
id | integer | Unique ID of the rate scheme |
name | string | Name of the Rate Scheme |
type_id | integer | 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 | A description on what this rate scheme is for. Could be customer facing if using in the booking description template |
booking_description_template | string | 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 | The hourly rate of all resources scoped to this rate scheme |
hour_rate_percent | boolean | If the hourly rate is actually a percentage (worked out from a base rate) |
day_rate | string | The daily rate of all resources scoped to this rate scheme |
day_rate_percent | boolean | If the daily rate is actually a percentage (worked out from a base rate) |
fixed_date | boolean | True if the rate scheme does not recur every year |
date_start | string | Date this rate scheme starts in SQL Date format |
date_end | string | Date this rate scheme ends in SQL Date format |
time_start | string | Time this rate scheme starts in SQL Time format |
time_end | string | Time this rate scheme ends in SQL Time format |
overtime_hours | string | Number of hours can elapse in a booking before it goes into overtime |
override_base | boolean | False = don't override any other base rates, True = Override other base rates and replace with this one |
default_unit | integer | 0 = Hourly, 1 = Daily |
default_tax | boolean | 0 = Dont Apply Tax, 1 = Apply Tax |
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 |
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 | Description |
---|---|---|
active | boolean | Whether this account is active or not |
package | array of objects | Details of the package in use |
total_users | integer | Total users in use |
total_resources | integer | Total resources in use |
total_schedules | integer | Total schedules in use |
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. |