Introduction

Let's make managing repair business more productive, together. For any suggestions, feedback, or bug reports please email support@fixably.com.

Base URL for all API calls:

https://[domain].fixably.com/api/

All request URLs start with the version number v3. For example:

https://demo.fixably.com/api/v3/orders

Schema

All request data is sent as JSON.
You can request a specific type by defining Accept http header. If Accept header is undefined, application/json will be assumed and used as content type.
Blank fields are included as null instead of being omitted.
All timestamps are returned in the following ISO 8601 format in UTC: YYYY-MM-DDTHH:MM:SSZ
Boolean fields can contain true, false and null for unknown value.

Limit and Offset

Request format

GET /{resource}?offset={offset}&limit={limit} HTTP/1.1

Requests that return multiple items will be limited to 25 items by default. You can change the default by adding a limit query parameter. This limits the response from 1 to 100 items.

Example request. Returns max 100 items but skips the first 100.

GET /orders?offset=100&limit=100 HTTP/1.1

The offset parameter is useful for skipping items from the start. For example, you can synchronize data in smaller batches by incrementing the offset after each request.

Request URL query parameters

Parameter	Type	Required	Description
limit	int	No	Max returned items
page	int	No	Select page number
offset	int	No	Ignore specified amount of items from the start. Can't be combined with `page`.

Example response body

{
    "limit": 3,
    "offset": 10,
    "totalItems": 115,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/orders/20000010"
        },
        {
            "href": "https://demo.fixably.com/api/v3/orders/20000011"
        },
        {
            "href": "https://demo.fixably.com/api/orders/20000012"
        }
    ]
}

Response body

Field	Type	Description
limit	int	Max returned items
offset	int	Item offset from start
totalItems	int	Total items available
items	array	Contains an expandable list of resources. See link expansion.

Pagination

Example pagination request. Returns second page of items using max 10 items per page limit.

GET /orders?page=2&limit=10 HTTP/1.1

Do you want to create a list of orders with "previous" and "next" buttons and display page numbers? Or implement an infinite scroll that loads more items as the user scrolls down?

Just include a page=1 query parameter, and the API returns fields for easy pagination.

Example pagination response body.

{
    "limit": 10,
    "page": 1,
    "totalPages": 2,
    "totalItems": 11,
    "first": 1,
    "last": 2,
    "before": null,
    "next": 2,
    "items": [
        {
            "href": "..."
        }
    ]
}

Pagination response fields

These additional fields are returned if page parameter is defined.

Field	Type	Description
page	int	Page number
totalPages	int	Total number of pages available
first	int	First page number
last	int	Last page number
before	int or null	Previous page number if available
next	int or null	Next page number if available

Link expansion

Request format

GET /{resource}?expand=items({subresource}) HTTP/1.1

When requesting a resource you might want the Fixably API server to return not only that resource, but also one or more of its linked resources.

Link expansion allows you to retrieve related resources in a single request to the server instead of having to issue multiple separate requests. Using the expand URL query parameter you can define which resources you want to expand.

Relations that have a href field are expandable. For example, both the order and the related customer can be loaded in a single request like GET /orders/20000000?expand=customer.

Example request that returns a list of orders and related order item lines (products & services).

GET /orders?expand=items(lines(items)) HTTP/1.1

Example response body. Unrelated fields are left out to keep the example short.

{
  "limit": 25,
  "offset": 0,
  "totalItems": 1,
  "items": [
    {
      "href": "https://demo.fixably.com/api/v3/orders/20000000",
      "id": 20000000,
      "lines": {
        "href": "https://demo.fixably.com/api/v3/orders/20000000/lines",
        "limit": 1,
        "offset": 0,
        "totalItems": 1,
        "items": [
          {
            "href": "https://demo.fixably.com/api/v3/orders/20000000/lines/21",
            "id": 21,
            "code": "EXAMPLE_PRODUCT",
            "name": "Example Product",
            "priceRange": "STOCK",
            "quantity": "2",
            "quantityCharged": "0",
            "quantityDispatched": "0",
            "price": "100.00",
            "vat": "6.00",
            "discount": "0.00",
            "notes": "",
            "isHidden": false,
            "serialNumber": null,
            "originalSerialNumber": null,
            "imeiNumber": null,
            "purchasePrice": "0.00",
            "total0": "200.00",
            "total": "212.00",
            "totalCharged0": "0.00",
            "totalCharged": "0.00",
            "totalRemaining0": "200.00",
            "totalRemaining": "212.00"
          }
        ]
      }
    }
  ]
}

Expand parameter examples

Example URL	Description
/orders/20000000?expand=customer	Expands the customer resource
/orders/20000000?expand=customer,device	Expands both customer and device
/orders/20000000?expand=lines	Displays links to each order line
/orders/20000000?expand=lines(items)	Expands each order line

Searching

Example request to search for closed orders

GET /orders?expand=items&q=isClosed:true HTTP/1.1

API endpoints can be searched using the q query parameter. The search queries have the following syntax:

?q=fieldName:searchTerm

You can specify multiple queries by separating them with a comma (,). For example, filtering customers by "firstName", "lastName" and "company" fields would look like:

/customers?q=firstName:John,lastName:Doe,company:Fixably

The query conditions are combined using AND operators, meaning that all filters need to match.

Note that the filter search queries cannot contain characters : or ,.

Wildcard search

Example wildcard search

GET /customers?expand=items&q=company:Appl* HTTP/1.1

You can use an asterisk (*) as a wildcard character to only search part of a word.

GET /users?q=firstName:Joh*,phones.number:(12345,67890),lastName:hancock! HTTP/1.1

GET /users?q=createdAt:[2010-12-24,2015-04-22] HTTP/1.1

Data contained within embedded document can be queried by separating parameter names with dots. For example, /users?q=credentials.username:john.

Each query parameter name is the same name of a searchable attribute on an instance in the resource.
If exclamation mark ! is defined at the end of a query, search is case-sensitive and gains performance boost.
Multiple values can be set for a single field using parenthesis and separating values with comma. OR operation is performed in case there are multiple values.
A query parameter value triggers one of four types of matching criteria:
- No asterisk at the beginning or end of the value indicates a direct case-insensitive match.
- An asterisk only at the beginning of the value indicates that the case-insensitive value is at the end.
- An asterisk only at the end of the value indicates that the case-insensitive value is at the beginning.
- An asterisk at the end AND at the beginning of the value indicates the value is contained in the string.

Wildcard attribute:

GET /users?q=company:*,lastName:* HTTP/1.1

Giving the whole attribute as a wildcard using asterisk results with non-empty items.

Empty attribute:

GET /users?q=company:,lastName: HTTP/1.1

Leaving the attribute in search empty results with items where the used attribute is empty.

Datetime search

Fixably stores date and time in ISO 8601 standard which is human readable and has common support across all languages.

The timezone is coordinated universal time (UTC). Parameters can be searched by defining date(s) inside parenthesis.

createdAt:[startDate,endDate]

One date can be omitted, but comma must be always present.
Date parameter existence triggers 3 types of matching criteria:
- Both start and end dates defined indicates timescale in which results must match.
- Start date defined indicates date must be newer or equal than startDate.
- End date defined indicates date must be older or equal than endDate.
- Parenthesis format can be used to find exact match for two or more datetime values
- Omitting parts of the datetime is permitted in order from right to left.
- Omitted parts are processed as lowest possible value. ie. for datetime value 2010, 2010-01-01 00.00.00 is used.

Example date queries

createdAt:[2015-04-22,]

find resources created on or after 22 day of April in 2015.

createdAt:[,2010-12-24]

find resources created on or before 24 day of December in 2010.

createdAt:[2010-12-24,2015-04-22]

find resources created between 24 day of December in 2010 and 22 day of April 2015 including specified dates.

createdAt:(2010,2015,2020)

find resources created on specified year.

Numeric range search

Parameters can be searched by defining the range inside parenthesis.

total:[start,end]

One range parameter can be omitted, but comma must be always present.
Range parameter existence triggers 3 types of matching criteria:
- Both start and end values defined indicates the range in which results must match.
- Start value defined indicates value must be equal or greater than start.
- End value defined indicates value must be less or equal than end.
- Parenthesis format can be used to find exact match for two or more numeric values.

Example numeric range queries

total:[0,]

find resources with value greater than or equal to 0.

total:[0,100]

find resources with value greater than or equal to 0 and less than or equal to 100.

total:(1,5,10)

find resources that have total value of 1, 5 or 10.

Custom Fields in the API

Custom Fields is supported via API endpoints and do not have a dedicated set of endpoints themselves but instead attaches themselves to existing ones.

Domains

Custom Fields supports a variety of domains, a domain means the area where a custom field belongs to. The supported domains are:

Domain	Canonical name
Devices	`devices`
Orders	`orders`
Order lines	`orderLines`
Products	`products`
Service Contracts	`serviceContracts`
Users	`users`

Visibility

Custom Fields operate on a principle of visibility. For a custom field to be present in the API, it must have the API visibility flag enabled. If the visibility flag is turned off, then the API will simply pretend a custom field doesn't exist.

It is therefore very important to only enable the API visibility flag with causion, especially if the data contained within it is very sensitive or otherwise not needed to be exposed.

Note, writing to a custom field without the API flag enabled will always result in an error.

Output

Custom Fields will automatically hydrate the type of the custom field to a native JSON type where possible:

Custom Fields type	JSON type	Notes
Yes / No	`bool`
Options	`string`
Multi-select options	`string[]`	The `Allow multi selections` option must be enabled
Numeric	`int`
Floating point numeric	`float`	The `Allow floating point numbers` option must be enabled
Text	`string`

Since the Yes / No type will always default to false if the record that the custom field value belongs to have been modified. This is because the type can only ever be true or false.

The structure will always be the same across every endpoint, regardless of the domain.

Input

Custom Fields will expect the same types as input as they were outputted as in the table above.

Every value will be validated in the same way as it is in the User Interface of Fixably. This means that if a field is for example marked as required in the System Settings, so will it be required when using the API.

Error handling

Custom Fields will integrate into the error mechanism for the endpoint in question for consistency and no further action is needed besides the existing error handling that may be present in your application.

Changelog

Recent changes and additions to Fixably API. Changes are backward compatible. Documented fields are not removed or changed.

2024-04-25

New field location for PATCH /orders/{id} endpoint
Updated GET /purchase-orders/{id}/lines/{id}

2024-04-05

New endpoint PATCH /service-contracts/{id}

2024-03-07

Added defaultPaymentTerm field for POST and PATCH /customers/{id} endpoint

2024-02-15

Customer role editing
New field insuranceCompany for /orders endpoint
New fields model and code for /devices endpoint

2023-11-23

Added custom field support for order lines and service contracts
Documented more error codes

2023-10-12

New fields invoiceFile and invoiceReceipt for /invoices endpoint
New searchable field order for /files endpoint
Updated list of file types

2023-09-19

New field allShippingAddresses for /customers endpoint
New field method for /invoices endpoint

2023-09-06

New field notes[*].notify for POST /orders endpoint
New field vatNumber for /customers endpoint

2023-08-03

New field parent for /customers endpoint
New webhook payload-type payment
New endpoint DELETE /orders/{order.id}/lines/{line.id}

2023-07-06

New update order line endpoint PATCH /orders/{order.id}/lines/{line.id}
New sticky option for timeline notes

2023-04-04

New isConsolidated field for order invoicing
New visibleOnPrintouts field for products
New /emails endpoints for sending emails
New internalReference field for /orders endpoint
Documented /customers endpoint character limit for shippingAddress.name

2023-01-12

New webhook payload-type stock_quantity

2022-11-11

New endpoint /files/upload
New webhook payload-type order_line.

2022-10-12

Timestamp fields createdAt and updatedAt for /products endpoint.
Customer firstName and lastName are now optional when adding a company in POST /customers
Multiple new fields for /service-contracts endpoint

2022-09-15

New endpoint /payment-terms
Order priority, tags and custom references are now editable
Order tracking identifier field magic is now available
POST /orders now additionally accepts device IMEI instead of just device.id reference
New fields for /invoices related to consolidated invoices

2022-06-08

New endpoints for stock management

2022-05-25

Added new endpoints for invoices

2022-05-12

Added product price markup field
New "customer" webhook type

2022-04-22

Added documentation for signing invoices

2022-04-08

Added documentation for show file and list files endpoints
Added documentation for list order files endpoint

2022-03-29

Added documentation for invoices charge endpoint
Added documentation for payment-types endpoint

2022-03-22

Added status to purchase order response body
Added serialNumber, imei and stock to purchase order line response body

2022-03-15

Changelog added for the documentation.

Authentication

Authenticated HTTP request example

GET /api/v3/locations HTTP/1.1
Host: demo.fixably.com
Accept: application/json
Authorization: pk_YOUR_API_KEY_HERE

Example cURL request

curl --location --request GET 'https://demo.fixably.com/api/v3/locations?expand=items' \
--header 'Authorization: pk_YOUR_API_KEY_HERE'

Authentication is easy using a Fixably API token.

Login to your Fixably instance as an admin user.
From top right menu select User Settings > Integrations > API.
Include your personal API Token in request Authorization header.
Send request to https://[domain].fixably.com/api/v3/[resource].

Token

Requests that require authentication will return 401 Unauthorized.

Customers

Get customer

GET /customers/{customer.id}

GET /customers/123 HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example get customer response

{
    "id": 123,
    "firstName": "John",
    "lastName": "Doe",
    "company": "Acme Ltd",
    "phone": "12345678",
    "email": "john.doe@example.com",
    "shippingAddress": {
        "id": 1,
        "name": null,
        "address1": "3 Abbey Rd",
        "address2": null,
        "address3": null,
        "zip": "NW8 9AY",
        "city": "London",
        "state": null,
        "country": "GB"
    },
    "allShippingAddresses": [
        {
            "id": 2,
            "name": null,
            "address1": "SE1 9AL",
            "address2": null,
            "address3": null,
            "zip": "NW8 9AY",
            "city": "London",
            "state": null,
            "country": "GB"
        }
    ],
    "billingAddress": null,
    "businessId": "01234567",
    "vatNumber": "8765432-1",
    "language": "en",
    "provider": "import",
    "identifier": "import_321",
    "parent": {
        "href": "https://demo.fixably.com/api/v3/customers/456"
    },
    "children": {
        "href": "https://demo.fixably.com/api/v3/customers/123/children"
    },
    "priority": 0,
    "notes": "Example note.",
    "tags": [
        "example"
    ],
    "roles": {
        "href": "https://demo.fixably.com/api/v3/customers/123/roles"
    },
    "allowShareEmail": true,
    "createdAt": "2021-10-14T08:38:46+0000",
    "updatedAt": "2021-10-14T08:38:46+0000",
    "defaultPaymentTerm": {
        "href": "https://demo.fixably.com/api/v3/payment-terms/3"
    }
}

Parameter	Type	Description
id	int	Unique resource id
firstName	string or null	First name
lastName	string or null	Last name
company	string or null	Company or organization name
phone	string or null	Phone number
email	string or null	Email address
shippingAddress	object or null	Customer's primary shipping address
allShippingAddresses	array	All customer's shipping addresses (primary shipping address excluded)
billingAddress	object or null	Billing address
businessId	string or null	Company VAT or tax ID
vatNumber	string	VAT number. Only for business customers (companies)
language	string	Two letter language code
provider	string or null	External provider or source
identifier	string or null	External provider/source identification
parent	object or null	See customer
children	object	List of child companies (subsidiaries or departments)
priority	int	Customer priority. Default value is `0`. Higher value means higher priority.
notes	string	Customer notes
tags	array	List of tags
roles	object	List of user roles
updatedAt	datetime	Timestamp of last update
createdAt	datetime	Customer creation timestamp
ssn	string	Social security number. Only available if the use of social security number is enabled in System Settings.
defaultPaymentTerm	object or null	Related payment terms object
allowShareEmail	boolean	Indicates if the customer email can be shared with Apple GSX when creating a repair or not

List customers

GET /customers HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example list customers response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 4,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/customers/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/customers/3"
        },
        {
            "href": "https://demo.fixably.com/api/v3/customers/4"
        },
        {
            "href": "https://demo.fixably.com/api/v3/customers/6"
        }
    ]
}

GET /customers

Lists all available customers.

Create customer

Example create customer request

POST /customers HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE

Example create customer request body

{
  "firstName": "Morty",
  "lastName": "Smith",
  "company": "Ricksy Business",
  "phone": "555-0100",
  "email": "morty@example.com",
  "businessId": "110",
  "vatNumber": "8765432-1",
  "language": "en",
  "provider": "import",
  "identifier": "C-132",
  "parent": {
    "id": 456
  },
  "priority": 10,
  "notes": "Inventor",
  "tags": [
    "example",
    "VIP"
  ],
  "roles": [],
  "shippingAddress": {
    "name": "HHHS",
    "address1": "Unknown",
    "address2": "",
    "address3": "",
    "city": "Seattle",
    "zip": "98101",
    "state": "WA",
    "country": "US"
  },
  "billingAddress": {
    "name": "Rick",
    "address1": "",
    "address2": "",
    "address3": "",
    "city": "Seattle",
    "zip": "98101",
    "state": "WA",
    "country": "US"
  },
  "allowShareEmail": false,
  "defaultPaymentTerm": {
    "id": 123
  }
}

Example create customer response body

{
    "id": 112812,
    "firstName": "Morty",
    "lastName": "Smith",
    "company": "Ricksy Business",
    "phone": "555-0100",
    "email": "morty@example.com",
    "shippingAddress": {
        "id": 21361,
        "name": "HHHS",
        "address1": "",
        "address2": "",
        "address3": "",
        "zip": "98101",
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "identifier": "123"
    },
    "billingAddress": {
        "id": 21362,
        "name": "Rick",
        "address1": "",
        "address2": "",
        "address3": "",
        "zip": "98101",
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "identifier": "124"
    },
    "allShippingAddresses": [],
    "businessId": "110",
    "vatNumber": "8765432-1",
    "group": null,
    "language": "en",
    "provider": "import",
    "identifier": "C-132",
    "parent": null,
    "children": {
        "href": "https://demo.fixably.com/api/v3/customers/112812/children"
    },
    "priority": 10,
    "notes": "Inventor",
    "tags": ["example"],
    "roles": {
        "href": "https://demo.fixably.com/api/v3/customers/roles"
    },
    "createdAt": "2023-09-26T07:25:51+0000",
    "updatedAt": "2023-09-26T11:28:00+0000",
    "customFields": [],
    "defaultPaymentTerm": {
        "href": "https://demo.fixably.com/api/v3/payment-terms/123"
    },
    "ssn": ""
}

POST /customers

Parameter	Type	Required	Description
firstName	string	Yes²	Customer first name
lastName	string	Yes²	Customer last name
company	string	No²	Company or organization name
phone	string	Yes¹	Phone number
email	string	Yes¹	Email address
businessId	string	No	Tax or other business ID
vatNumber	string	No	VAT number. Only for business customers (companies)
language	string	No	Two letter ISO 639-1 language code. For example "en" or "de".
provider	string	No	Integration name. For example "SAP".
identifier	string	No	External identifier for the integration.
parent	object	No	Customer's parent company or organization
parent.id	int	Yes	Parent ID
priority	int	No	Customer priority between 0-10
notes	string	No	Free text customer notes
tags	string[]	No	List of tags
roles	int[]	No	List of role IDs. See roles.
shippingAddress	object	No	Ship-to address
shippingAddress.name	string	No	Recipient name. Max length 100 characters.
shippingAddress.address1	string	No	Address line 1
shippingAddress.address2	string	No	Address line 2
shippingAddress.address3	string	No	Address line 3
shippingAddress.city	string	No	City or municipality
shippingAddress.zip	string	No	Postal code
shippingAddress.state	string	No	State
shippingAddress.country	string	No	Two letter country code
billingAddress	object	No	Separate billing address if it doesn't match `shippingAddress`
billingAddress.name	string	No	Payer name
billingAddress.address1	string	No	Address line 1
billingAddress.address2	string	No	Address line 2
billingAddress.address3	string	No	Address line 3
billingAddress.city	string	No	City or municipality
billingAddress.zip	string	No	Postal code
billingAddress.state	string	No	State
billingAddress.country	string	No	Two letter country code
allowShareEmail	bool	No	If false, the customer email won't be shared with Apple GSX when creating a repair. Default is `true`
defaultPaymentTerm	object	No	Customer's default payment term
defaultPaymentTerm.id	int	Yes	Payment term ID

¹ Either email or phone is required.

² firstName and lastName are required only if the company field is not provided.

The “HTTP 201 Created” response code signifies that a new customer has been successfully created. However, if the provider and identifier fields correspond to an existing record, a new customer will not be created. Instead, the existing customer’s details will be updated, and an “HTTP 200 Ok” response code will be returned.

Update customer

PATCH /customers/{customer.id}

PATCH /customers/{customer.id} HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example update customer request

{
  "firstName": "Steve",
  "lastName": "Wozniak",
  "company": "Woz U",
  "phone": "555-0100",
  "email": "steve@example.com",
  "businessId": "",
  "vatNumber": "8765432-1",
  "language": "en",
  "provider": "MY_INTEGRATION",
  "identifier": "my_id_123",
  "parent": {
    "id": 456
  },
  "priority": 5,
  "notes": "Nickname is Woz.",
  "tags": [
    "example"
  ],
  "roles": [123],
  "shippingAddress": {
    "name": "Woz U HQ",
    "address1": "Address 1",
    "address2": "Address 2",
    "address3": "Address 3",
    "city": "City",
    "zip": "Zip",
    "state": "AZ",
    "country": "US"
  },
  "billingAddress": {
    "name": "Woz U HQ",
    "address1": "Address 1",
    "address2": "Address 2",
    "address3": "Address 3",
    "city": "City",
    "zip": "Zip",
    "state": "AZ",
    "country": "US"
  },
  "allowShareEmail": false,
  "defaultPaymentTerm": {
    "id": 123
  }
}

Parameter	Type	Required	Description
firstName	string	No	Customer first name
lastName	string	No	Customer last name
company	string	No	Company or organization name
phone	string	No	Phone number
email	string	No	Email address
businessId	string	No	Tax or other business ID
vatNumber	string	No	VAT number. Only for business customers (companies)
language	string	No	Two letter ISO 639-1 language code. For example "en" or "de".
provider	string	No	Integration name. For example "SAP".
identifier	string	No	External identifier for the integration.
parent	object	No	Customer's parent company or organization
parent.id	int	Yes	Parent ID. Put 'null' to unset parent
priority	int	No	Customer priority between 0-10
notes	string	No	Free text customer notes
shippingAddress	object	No	Ship-to address
shippingAddress.name	string	No	Recipient name. Max length 100 characters.
shippingAddress.address1	string	No	Address line 1
shippingAddress.address2	string	No	Address line 2
shippingAddress.address3	string	No	Address line 3
shippingAddress.city	string	No	City or municipality
shippingAddress.zip	string	No	Postal code
shippingAddress.state	string	No	State or province
shippingAddress.country	string	No	Two letter country code
billingAddress	object	No	Separate billing address if it doesn't match `shippingAddress`
billingAddress.name	string	No	Payer name
billingAddress.address1	string	No	Address line 1
billingAddress.address2	string	No	Address line 2
billingAddress.address3	string	No	Address line 3
billingAddress.city	string	No	City or municipality
billingAddress.zip	string	No	Postal code
billingAddress.state	string	No	State or province
billingAddress.country	string	No	Two letter country code
ssn	string	No	Social security number. Only available if the use of social security number is enabled in System Settings.
tags	string[]	No	List of tags
roles	int[]	No	List of role IDs. See roles.
allowShareEmail	bool	No	If false, the customer email won't be shared with Apple GSX when creating a repair
defaultPaymentTerm	object	No	Customer's default payment term
defaultPaymentTerm.id	int or null	No	Payment term ID

Delete customer

Example delete customer request

DELETE /customers/{customer.id} HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example delete customer response with HTTP status code 204

204 No Content

If the customer has already been deleted or if there is an attempt to delete an employee, the endpoint will return a 400 Bad Request.

DELETE /customers/{customer.id}

Custom Fields

Custom Fields Configuration

GET /custom-fields

GET /custom-fields HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Configuration response

{
    "devices": {
        "domain": {
            "features": [
                "search",
                "orderEvents"
            ],
            "visibilityFields": [
                {
                    "id": 4,
                    "name": "Macros"
                },
                {
                    "id": 8,
                    "name": "Printouts"
                },
                {
                    "id": 16,
                    "name": "Device card"
                },
                {
                    "id": 32,
                    "name": "API"
                }
            ]
        },
        "fields": [
            {
                "name": "Color",
                "canonicalName": "color",
                "description": "Original manufacturer color of the device",
                "visibility": {
                    "4": true,
                    "8": true,
                    "16": true,
                    "32": false
                },
                "type": "text",
                "enabled": true,
                "options": [],
                "multiValues": [],
                "features": {
                    "search": true,
                    "orderEvents": false
                }
            },
            {
                "name": "Condition",
                "canonicalName": "condition",
                "description": "Condition of the device when we recieved it",
                "visibility": {
                    "4": true,
                    "8": false,
                    "16": true,
                    "32": true
                },
                "type": "options",
                "enabled": true,
                "options": [
                    {
                        "id": 1,
                        "name": "Required"
                    },
                    {
                        "id": 16,
                        "name": "Allow multiple selections"
                    }
                ],
                "multiValues": [
                    "Broken",
                    "Scratched",
                    "Mint"
                ],
                "features": {
                    "search": true,
                    "orderEvents": false
                }
            }
        ]
    },
    "orders": {
        "domain": {
            "features": [
                "search",
                "orderEvents",
                "orderIcon"
            ],
            "visibilityFields": [
                {
                    "id": 4,
                    "name": "Macros"
                },
                {
                    "id": 8,
                    "name": "Printouts"
                },
                {
                    "id": 32,
                    "name": "API"
                },
                {
                    "id": 64,
                    "name": "Order lists"
                }
            ]
        },
        "fields": []
    },
    "products": {
        "domain": {
            "features": [
                "search"
            ],
            "visibilityFields": [
                {
                    "id": 1,
                    "name": "Product card"
                },
                {
                    "id": 2,
                    "name": "Product order lines"
                },
                {
                    "id": 32,
                    "name": "API"
                }
            ]
        },
        "fields": []
    },
    "users": {
        "domain": {
            "features": [
                "search"
            ],
            "visibilityFields": [
                {
                    "id": 8,
                    "name": "Printouts"
                },
                {
                    "id": 32,
                    "name": "API"
                },
                {
                    "id": 128,
                    "name": "Order view"
                },
                {
                    "id": 256,
                    "name": "User card"
                }
            ]
        },
        "fields": []
    }
}

The configuration response is very large and descriptive. It is designed to represent the current state of how Custom Fields are configured so applications can apply checks to ensure that validation will pass when sending requests to the relevant Custom Fields domain.

Deliveries

Available delivery methods. For example, contract transport or pickup services.

Get delivery

GET /deliveries/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get delivery response

{
    "id": 123,
    "shortName": "Pickup",
    "name": "Courier pickup",
    "description": "Next day delivery."
}

GET /deliveries/{delivery.id}

Parameter	Type	Description
id	int	Unique resource id
name	string	Delivery method name
shortName	string	Short name for menu options
description	string	Optional description

List deliveries

GET /deliveries

GET /deliveries HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list deliveries response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 2,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/deliveries/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/deliveries/2"
        }
    ]
}

Devices

The device under repair.

Create device

POST /devices HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example device create request

{
  "serialNumber": "ABCDE123",
  "name": "iPhone X",
  "configuration": "IPHONE X,64GB,SILVER",
  "purchaseCountry": "USA",
  "brand": "APPLE",
  "model": "IPHONE",
  "code": "ZD661-03109",
  "purchaseDate": "2021-01-01"
}

POST /devices

Parameter	Type	Required	Description
serialNumber	string	Yes	Unique serial number
imeiNumber1	string	No	IMEI number
imeiNumber2	string	No	Secondary IMEI number
name	string	Yes	Device name
configuration	string	No	Specification e.g. color, memory, size...
brand	string	No	Brand identifier (APPLE, SAMSUNG, XIAOMI, ...)
model	string	No	Model name
code	string	No	Model code
purchaseCountry	string	No	Three letter ISO 3166-1 country code
purchaseDate	string	No	Estimated purchase date in "YYYY-MM-DD" format
customFields	object	Depends	Custom Fields relative to this device

Get device

GET /devices/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example device response

{
    "id": 123,
    "serialNumber": "ABCDEFA12345",
    "imeiNumber1": "",
    "imeiNumber2": "",
    "name": "Watch Sport 42MM (1st gen)",
    "configuration": "SPORT WATCH,GRAY ALUMINUM,42MM",
    "model": "WATCH",
    "family": null,
    "brand": "APPLE",
    "code": "",
    "distributor": null,
    "purchaseCountry": "USA",
    "purchaseDate": "2015-09-01T00:00:00+0000",
    "isActivationLocked": true,
    "isCarrierLocked": null,
    "isVintage": false,
    "isObsolete": false,
    "isLoaner": null,
    "tags": ["tag1"],
    "productImageUrl": "",
    "customFields": {}
}

GET /devices/{device.id}

Field	Type	Description
id	int	Unique resource id
name	string	Device description
configuration	string	Device configuration
serialNumber	string	Serial number
imeiNumber1	string	IMEI number
imeiNumber2	string	IMEI number 2 if applicable
brand	string	Brand identifier (e.g. APPLE, SAMSUNG, XIAOMI)
model	string	Model identifier if available
code	string	Model code
purchaseDate	datetime or null	Estimated purchase date
purchaseCountry	string	Three letter purchase country code
isObsolete	bool	Indicates if device is in obsolete status
isVintage	bool	Indicates if device is in vintage status
tags	array	List of custom device tags
productImageUrl	string	Url for a device image
customFields	object	Custom Fields specific to this device

List devices

GET /devices

GET /devices HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list devices response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/devices/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/devices/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/devices/3"
        }
    ]
}

Emails

These endpoints are for sending emails and serving all necessary things needed for it

Email templates

Email templates can be added and edited in the Fixably UI. The purpose of the emails/templates endpoint is to make it easier to check which template to use when sending an email. The email send request requires a template name and this is the way to find the proper one.

Get one template

GET /emails/templates/20 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get email templates response body

{
  "id": 20,
  "name": "inbound-shipping-instructions",
  "language": "en",
  "subject": "Shipment for tracking number {trackingNumber}",
  "body": "Hi, Please find Waybill with Order ID attached. Best regards."
}

GET /emails/templates/{template.id}

Parameter	Type	Description
id	int	Unique resource id
name	string	Name of the email template
language	string	Two character representation of the language of the template
subject	string	The template subject for the email
body	string	The template body for the email

List templates

GET /emails/templates HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list templates response body

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/emails/templates/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/emails/templates/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/emails/templates/3"
        }
    ]
}

GET /emails/templates

Email document types

Email document types are not dynamic. They are hard coded constants. This endpoint is only serving as an easy check list.

List document types

GET /emails/document-types HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example email document types response body

{
    "totalItems": 3,
    "items": [
      {
        "name": "Order confirmation",
        "code": "confirmation"
      },
      {
        "name": "Order confirmation with terms",
        "code": "confirmation-with-terms"
      },
      {
        "name": "Order confirmation with all prices",
        "code": "confirmation-all-prices"
      },
      {
        "name": "Order confirmation without prices",
        "code": "confirmation-no-prices"
      },
      {
        "name": "Specification",
        "code": "specs"
      }
    ]
}

GET /emails/document-types

Send email

POST /emails/send HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

This endpoint sends an email to the order contact or the order user.

Example send email request

{
  "template": "order-ready",
  "documentTypes": [
    "confirmation",
    "specs"
  ],
  "orderId": 20002436,
  "email": "tester@testing.com"
}

POST /emails/send

Parameter	Type	Required	Description
template	string	Yes	The name of the email template. The template must exist in the customer's language
documentTypes	array	Yes	An array of the names of the attachment files selected for the email
orderId	int	Yes	The order id
email	string	No	An email address that can override the order contact email and order user email
disableFileNotifications	bool	No	Disables notifications for technicians for all sent attachments that are added to order

Example send email response

{
  "success": true,
  "response": "Email was sent successfully"
}

Files

This endpoint lists all attachments uploaded to Fixably.

Get file

Example get file request

GET /files/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get file response headers

HTTP/1.1 200 OK
Content-Type: application/json

Example get file response body

{
  "href": "https://demo.fixably.com/api/v3/files/123",
  "id": 123,
  "name": "SomeImage",
  "size": 3000,
  "type": "IMAGE",
  "public": true,
  "createdAt": "2020-12-23T19:11:14+00:00",
  "createdBy": {
      "href": "https://demo.fixably.com/api/v3/users/1"
  },
  "url": "https://cdn.some-image-url.com/files/h23sg4yagj21h-image.png",
  "order": {
      "href": "https://demo.fixably.com/api/v3/orders/200001234"
  }
}

GET /files/{file.id}

Parameter	Type	Description
id	int	Unique resource id
name	string	File name
size	int	File size in bytes
type	string	File type. See File Types
public	bool	Is file visible to customer or not
createdAt	string	Date file was uploaded to Fixably
createdBy	object	The user who created the file user
url	string	Link to file.
order	object	Relation to an order if available

List files

GET /files HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list files response body

{
  "limit": 25,
  "offset": 0,
  "totalItems": 4,
  "items": [
    {
      "href": "https://demo.fixably.com/api/v3/files/1"
    },
    {
      "href": "https://demo.fixably.com/api/v3/files/2"
    },
    {
      "href": "https://demo.fixably.com/api/v3/files/3"
    },
    {
      "href": "https://demo.fixably.com/api/v3/files/4"
    }
  ]
}

GET /files

Upload file

This endpoint generates a presigned file upload URL. Files are uploaded to the given URL using a PUT request and are then attached to a service order.

The maximum file size is 5 GB.
The expiration time for the presigned upload link is one hour.

If the same upload link is used multiple times before the expiration time, the last upload will remain. If the same file name is used many times, there will be a date time included in the created key to avoid duplicates. It is recommended to use rather short filenames with a maximum of 64 characters. It is not limited, but the provided key length is limited to 128 characters and AWS S3 will not accept longer keys. The key will consist of the environment name, username, date and time and the full file name with extension. It is also recommended to use only url compatible characters in the file name, to avoid malfunctions. Special Latin characters from number 192 to 255 in ASCII table are accepted (except number 215 and 247). ASCII table

Example file upload request

POST /files/upload HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

{
  "filename": "test_file.jpg"
}

The filename must be the exact filename of the file to be uploaded, when requesting the presigned url.

Example file upload response body

{
    "url": "https://demo.s3.eu-west-1.amazonaws.com/demo/user1/test_file.png?x-amz-acl=public-read&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJRRGAOOHMI6GC2LQ%2F20221025%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20221025T090059Z&X-Amz-SignedHeaders=host%3Bx-amz-acl&X-Amz-Expires=3600&X-Amz-Signature=04e6045742bc9f43540e7b7585875742971c5220830920957816a6109ba13ebb",
    "key": "demo/user1/test_file.png"
}

The URL is used for a PUT request, where the file is attached to the body as binary.

Example cUrl of the PUT request to AWS S3

curl --location --request PUT 'https://demo.s3.eu-west-1.amazonaws.com/demo/user1/test_file.png?x-amz-acl=public-read&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJRRGAOOHMI6GC2LQ%2F20221025%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20221025T090059Z&X-Amz-SignedHeaders=host%3Bx-amz-acl&X-Amz-Expires=3600&X-Amz-Signature=04e6045742bc9f43540e7b7585875742971c5220830920957816a6109ba13ebb' \
--header 'Content-Type: image/png' \
--data-binary '@/User1/files/test_file.png'

If the PUT request is successful, AWS S3 returns true and the response code is 200 OK

After a successful upload, the file must be still attached to the order, using the attach a file to the order endpoint.

POST /files/upload

Allowed file types

File extension	Mime type
.gif	image/gif
.heic	image/heic
.heic	image/heic-sequence
.heif	image/heif
.heif	image/heif-sequence
.jpg	image/jpeg
.jpeg	image/jpeg
.mp4	video/mp4
.ogg	audio/ogg
.pdf	application/pdf
.png	image/png
.txt	text/plain
.tiff	image/tiff
.webm	video/webm

Invoices

The invoice endpoint represents invoices and receipts.

Get invoice

Example get invoice request

GET /invoices/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get invoice response

{
    "id": 123,
    "name": "Acme Ltd",
    "type": "Invoice",
    "method": "POST",
    "created": "2020-09-20T00:00:00+00:00",
    "paidDate": null,
    "reference": "",
    "total0": "4472.00",
    "total": "5590.00",
    "totalPaid": "0.00",
    "totalPaid0": "0.00",
    "totalOutstanding": "5590.00",
    "totalOutstanding0": "4472.00",
    "isConsolidated": false,
    "lines": {
        "href": "https://demo.fixably.com/api/v3/invoices/123/lines"
    },
    "payments": {
        "href": "https://demo.fixably.com/api/v3/invoices/123/payments"
    },
    "paymentTerms": {
        "href": "https://demo.fixably.com/api/v3/invoices/123/payment-terms/3"
    },
    "order": {
        "href": "https://demo.fixably.com/api/v3/orders/1"
    },
    "customer": {
        "href": "https://demo.fixably.com/api/v3/customers/1"
    },
    "invoiceFile": {
        "href": "https://demo.fixably.com/api/v3/files/35"
    },
    "receiptFile": {
        "href": "https://demo.fixably.com/api/v3/files/63"
    }
}

Example get invoice response when invoice is consolidated

{
    "id": 123,
    "name": "Acme Ltd",
    "type": "Invoice",
    "method": "PAYPAL",
    "created": "2020-09-20T00:00:00+00:00",
    "paidDate": null,
    "reference": "",
    "total0": "4472.00",
    "total": "5590.00",
    "totalPaid": "0.00",
    "totalPaid0": "0.00",
    "totalOutstanding": "5590.00",
    "totalOutstanding0": "4472.00",
    "isConsolidated": true,
    "consolidatedTo": "https://demo.fixably.com/api/v3/invoices/122",
    "consolidatedInvoices": {
        "href": "https://demo.fixably.com/api/v3/invoices/123/consolidated"
    },
    "lines": {
        "href": "https://demo.fixably.com/api/v3/invoices/123/lines"
    },
    "payments": {
        "href": "https://demo.fixably.com/api/v3/invoices/123/payments"
    },
    "order": {
        "href": "https://demo.fixably.com/api/v3/orders/1"
    },
    "customer": {
        "href": "https://demo.fixably.com/api/v3/customers/1"
    },
    "invoiceFile": {
        "href": "https://demo.fixably.com/api/v3/files/123"
    },
    "receiptFile": {
        "href": "https://demo.fixably.com/api/v3/files/124"
    }
}

GET /invoices/{invoice.id}

Parameter	Type	Description
id	int	Unique resource id
name	string	Invoice payer name
type	string	Receipt/Invoice/Cash/Online/Apple Reimbursement
method	string	Invoicing method: EMAIL/POST/ONLINE/PORTAL/PAYPAL/BUCKAROO/WSPOS/UNKNOWN
created	datetime	Invoice created at datetime
paidDate	datetime or null	Invoice paid at datetime
reference	string	Custom invoice reference
total0	string	Invoice total (excluding tax)
total	string	Invoice total (including tax)
totalPaid	string	Total paid (including tax)
totalPaid0	string	Total paid (excluding tax)
totalOutstanding	string	Total to be paid (including tax)
totalOutstanding0	string	Total paid (excluding tax)
isConsolidated	bool	Consolidated invoice
consolidatedTo	string	Url to the main invoice where others are consolidated
consolidatedInvoices	object	List of related consolidated invoices
lines	object	List of related invoice lines
payments	object	List of related payments
paymentTerms	object	Related payment_terms object
order	object	Related order object
customer	object	Related customer object
invoiceFile	object	Relation to invoice PDF file
invoiceReceipt	object	Relation to receipt PDF file

List invoices

Example list invoices request

GET /invoices HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list invoices response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/invoices/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/invoices/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/invoices/3"
        }
    ]
}

GET /invoices

Lists all invoices and receipts in the system. Results can be filtered using the q query parameter.

For example, filter by the creation date:

/invoices?q=created:[2023-10-01,2023-10-31]&expand=items

Display only consolidated invoices:

/invoices?q=consolidated:true&expand=items

Other searchable fields: type, reference, consolidatedId, order.id and paidDate

Get invoice line

Example get invoice line request

GET /invoices/1001/lines/123 HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example get invoice line response body

{
    "id": 123,
    "code": "TEST_SERVICE",
    "name": "Test service",
    "quantity": "1",
    "price": "64.59",
    "vat": "15.00",
    "notes": "",
    "isHidden": false,
    "serialNumber": "ABCD123456",
    "originalSerialNumber": "XYZ1234567",
    "imeiNumber": "",
    "product": {
        "href": "https://demo.fixably.com/api/v3/products/1"
    },
    "orderLine": {
        "href": "https://demo.fixably.com/orders/20001234/lines/1234"
    }
}

Retrieve an invoice line item.

GET /invoices/{invoice.id}/lines/{line.id}

Parameter	Type	Description
id	int	Unique resource id
code	string	Product code
name	string	Invoice line item name
quantity	string	Quantity
price	string	Price per item
vat	string	VAT or sales tax percentage
notes	string	Free text notes
isHidden	bool	Hidden line item
serialNumber	string	Part serial number if available
originalSerialNumber	string	Original part serial number if available
imeiNumber	string	IMEI number if available
product	object	Reference to the invoiced product
orderLine	object	Reference to the corresponding order line

List invoice lines

Example list invoice lines request

GET /invoices/1001/lines HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example list invoice lines response body

{
    "limit": 25,
    "offset": 0,
    "totalItems": 1,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/invoices/1001/lines/1"
        }
    ]
}

Lists all line items of an invoice.

GET /invoices/{invoice.id}/lines

Charge invoices

POST /invoices/123/charge HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

This endpoint marks the given Fixably invoice as paid. Please note that this endpoint doesn't create any financial transactions and is only used to indicate that the invoice has been paid in a third-party system.

Example charge invoice request

{
  "amount": "96.770",
  "paymentType": {
    "id": 1
  },
  "reference": "12345678"
}

POST /invoices/{invoice.id}/charge

Parameter	Type	Required	Description
amount	string	Yes	A numeric float as a string
paymentType	object	Yes	Payment type
paymentType.id	int	Yes	A valid payment type id
reference	string	No	The invoice reference number as a string

Example charge invoice response

{
  "href": "https://demo.fixably.com/api/v3/payments/1"
}

Sign invoice

POST /invoices/123/sign HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

This endpoint sets the secure string for the given Fixably invoice. Secure string is used for the invoice's QR code signature. Countries like Germany and Austria require it by law.

Example sign invoice request

{
  "qrCode": "secure_string",
}

POST /invoices/{invoice.id}/sign

Parameter	Type	Required	Description
qrCode	string	Yes	A secure string to be displayed as QR code

Example sign invoice response

{
  "result": "success"
}

Get consolidated invoices

Example get consolidated invoices request

GET /invoices/122/consolidated HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get consolidated invoices response body

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
      {
        "href": "https://demo.fixably.com/api/v3/invoices/122"
      },
      {
        "href": "https://demo.fixably.com/api/v3/invoices/123"
      },
      {
        "href": "https://demo.fixably.com/api/v3/invoices/124"
      }
    ]
}

Lists all consolidated invoices.

GET /invoices/{invoice.id}/consolidated

Locations

Repair service locations.

Get location

GET /locations/1 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get location response

{
    "id": 1,
    "name": "New York",
    "email": "info@example.com",
    "phone": "012345678",
    "country": "US",
    "address": "123 Street",
    "zip": "10001",
    "state": "NY",
    "city": "New York",
    "tat": 3,
    "openingHours": {
        "en": "Monday - Friday 10AM - 8PM, Saturday 10AM - 9PM, Sunday 12PM - 5PM"
    },
    "deliveries": {
        "href": "https://demo.fixably.com/api/v3/deliveries"
    },
    "longitude": null,
    "latitude": null
}

GET /locations/{location.id}

Parameter	Type	Description
id	int	Unique resource id
name	string	Service location name
email	string	Email address
phone	string	Phone number
country	string	Two letter country code
state	string	State, province or region
city	string	City name
zip	string	ZIP code
address	string	Street address
tat	string	Turnaround time (days)
openingHours	object	Opening hour text in different languages
deliveries	object	Available delivery methods
longitude	string	GPS coordinate
latitude	string	GPS coordinate

List locations

GET /locations HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 2,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/locations/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/locations/2"
        }
    ]
}

GET /locations

Orders

Orders are the heart of the system and represent service or sales orders. Many things are based on orders and what they contain.

Get order

Example get order request

GET /orders/20001234 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get order response body

{
    "id": 20001234,
    "isClosed": true,
    "isInside": true,
    "isDraft": false,
    "internalLocation": "STORE",
    "transitOrigin": null,
    "currentInsideTime": 33319923,
    "totalInsideTime": 33319923,
    "priority": "HIGH",
    "tags": ["vip"],
    "createdAt": "2020-12-23T19:11:14+00:00",
    "updatedAt": "2021-03-16T12:34:11+00:00",
    "notes": {
        "href": "https://demo.fixably.com/api/v3/orders/20001234/notes"
    },
    "orderedBy": {
        "href": "https://demo.fixably.com/api/v3/users/1234"
    },
    "handledBy": {
        "href": "https://demo.fixably.com/api/v3/users/4321"
    },
    "reference": "ABCD123",
    "internalReference": "Internal reference",
    "magic": "87c116c976438e6aeef3d8f12ee12ee8",
    "customReference": null,
    "device": {
        "href": "https://demo.fixably.com/api/v3/devices/2397"
    },
    "customer": {
        "href": "https://demo.fixably.com/api/v3/customers/1234"
    },
    "insuranceCompany": {
        "href": "https://demo.fixably.com/api/v3/customers/5678"
    },
    "contact": {
        "fullName": "Rick Sanchez",
        "company": null,
        "phoneNumber": "+15552368",
        "emailAddress": "rick.sanchez@fixably.com"
    },
    "status": {
        "href": "https://demo.fixably.com/api/v3/statuses/149"
    },
    "queue": {
        "href": "https://demo.fixably.com/api/v3/queues/4"
    },
    "location": {
        "href": "https://demo.fixably.com/api/v3/locations/1"
    },
    "store": {
        "href": "https://demo.fixably.com/api/v3/stores/7"
    },
    "shipments": {
        "href": "https://demo.fixably.com/api/v3/orders/20001234/shipments"
    },
    "lines": {
        "href": "https://demo.fixably.com/api/v3/orders/20001234/lines"
    },
    "tasks": {
        "href": "https://demo.fixably.com/api/v3/orders/20001234/tasks"
    },
    "total": "0.00",
    "total0": "0.00",
    "totalCharged": "0.00",
    "totalRemaining": "0.00",
    "provider": "SAP",
    "identifier": "ABC123",
    "customFields": {}
}

GET /orders/{order.id}

Parameter	Type	Description
id	int	Unique order number
isClosed	bool	Indicates if order is closed
isInside	bool	Indicates if order is at the service location
isDraft	bool	Order creation is unfinished. E.g. missing customer info or issue description.
internalLocation	string	Device location. CUSTOMER, SERVICE, STORE, IN_TRANSIT or UNKNOWN
transitOrigin	string or null	SERVICE, STORE or null
currentInsideTime	int	Seconds in service
totalInsideTime	int	Total time (seconds) in service. Counted from the moment device was received into service location.
priority	string	Order priority. See supported values
tags	string[]	Order tags
createdAt	datetime	Order created at date and time
updatedAt	datetime	Order updated at date and time
notes	object	Order notes. Issue description, technician's diagnosis, resolution and other. References order notes.
orderedBy	object	Reference to the user who created the order
handledBy	object or null	Reference to the assigned technician
reference	string or null	Customer reference number
internalReference	string or null	Service Providers internal reference
magic	string or null	Token that can be used for order tracking at `<tenant>.fixably.com/public/status`
customReference	string or null	Additional reference defined by the repair business in System Settings.
device	object or null	Device under repair. See devices
customer	object or null	See customer
insuranceCompany	object or null	See customer
contact	object	Primary contact information for the order
status	object	Order status. See statuses
queue	object or null	Service queue. See queues
location	object or null	Repair service location. See locations
store	object or null	Store location. See stores
shipments	object	Order's shipments. See shipments
lines	object	Order's products and services. See order lines
tasks	object	Custom order fields. See tasks
total	string	Order total with tax
total0	string	Order total without tax
totalCharged	string	Total amount marked as charged or invoiced
totalRemaining	string	Total amount left to be paid
provider	string	Order provider name
identifier	string	An identifier in the provider's system
customFields	object	Custom Fields specific to this order

List orders

Example list orders request

GET /orders HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list orders response body

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/orders/20000033"
        },
        {
            "href": "https://demo.fixably.com/api/v3/orders/20000034"
        },
        {
            "href": "https://demo.fixably.com/api/v3/orders/20000035"
        }
    ]
}

GET /orders

Lists all service orders. See available options for searching and expanding the returned fields.

Create order

Example create order request

POST /orders HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example create order request body

{
    "reference": "X1ASDGF",
    "device": {
        "id": 1
    },
    "location": {
        "id": 1
    },
    "notes": [
        {
            "title": "This can be left empty",
            "text": "This is an issue description.",
            "type": "ISSUE"
        },
        {
            "text": "Technician's diagnosis note.",
            "type": "DIAGNOSIS"
        },
        {
            "text": "Resolution note.",
            "type": "RESOLUTION"
        }
    ],
    "tasks": [
        {
            "id": 1,
            "value": "Max cost $200"
        }
    ],
    "queue": {
        "id": 1
    },
    "priority": 5,
    "customReference": "X5-789",
    "customReference2": "HELSINKI123",
    "internalReference": "ABC123",
    "tags": [
      "Tag1",
      "Tag2"
    ],
    "provider": "SAP",
    "identifier": "ABC123",
}

Example create order response body

{
    "id": 20000313,
    "isClosed": false,
    "isInside": true,
    "isDraft": false,
    "internalLocation": "SERVICE",
    "transitOrigin": null,
    "currentInsideTime": 1,
    "totalInsideTime": 1,
    "priority": "NORMAL",
    "tags": [
      "Tag1",
      "tag2"
    ],
    "createdAt": "2021-03-25T10:45:58+00:00",
    "updatedAt": "2021-03-25T10:45:58+00:00",
    "notes": {
        "href": "https://demo.fixably.com/api/v3/orders/notes"
    },
    "orderedBy": null,
    "handledBy": null,
    "reference": "f5ogzg",
    "magic": "87c116c976438e6aeef3d8f12ee12ee8",
    "customReference": null,
    "customReference2": "Helsinki-123",
    "device": {
        "href": "https://demo.fixably.com/api/v3/devices/1"
    },
    "customer": null,
    "contact": {
        "fullName": null,
        "company": null,
        "phoneNumber": null,
        "emailAddress": null
    },
    "status": null,
    "queue": null,
    "location": {
        "href": "https://demo.fixably.com/api/v3/locations/1"
    },
    "store": null,
    "lines": {
        "href": "https://demo.fixably.com/api/v3/orders/lines"
    },
    "tasks": {
        "href": "https://demo.fixably.com/api/v3/orders/tasks"
    },
    "total": "0.00",
    "total0": "0.00",
    "totalCharged": "0.00",
    "totalRemaining": "0.00",
    "provider": "SAP",
    "identifier": "ABC123",
    "customFields": {}
}

Create a new service order.

POST /orders

Parameter	Type	Required	Description
reference	string	No	Customer reference
device	object	No	Device under repair
device.id	int	Yes¹	Device id
device.imeiNumber	string	Yes¹	Device IMEI
device.serialNumber	string	Depends²	Device serial number
delivery	object	No	Delivery method
delivery.id	int	Yes	Delivery method id
location	object	No	Service location
location.id	int	Yes	Location id
customer	object	No	Customer
customer.id	int	Yes	Customer id
notes	array	No	Notes shown on the order timeline
notes[*].title	string	No	Optional title for timeline note
notes[*].text	string	Yes	Note text
notes[*].type	string	Yes	ISSUE, DIAGNOSIS, RESOLUTION or OTHER
notes[*].sticky	bool	No	Make the note stick to the top of the timeline
notes[*].notify	bool	No	Define if a notification for the order's technician is created or not. If not set the creation will be automatically determined
tasks	array	No	Order tasks
tasks[*].id	int	Yes	Task id
tasks[*].value	mixed	Yes	Selected value for the task. Type varies depending on the task's type.
isDraft	bool	No	Marks the order as an unfinished draft. Default is `false`.
internalLocation	string	No	internal location CUSTOMER, SERVICE, STORE, IN_TRANSIT or DEALER_SHOP
queue	object	No	Queues Service queue is assigned automatically if left empty.
queue.id	int	Yes	Queue id
contactName	string	No	End customer name
contactCompany	string	No	End customer company name
contactEmail	string	No	End customer email
contactPhone	string	No	End customer phone
contactAddress	object	No	End customer address
contactAddress.address1	string	No	End customer address line 1
contactAddress.address2	string	No	End customer address line 2
contactAddress.address3	string	No	End customer address line 3
contactAddress.name	string	No	End customer address name
contactAddress.city	string	No	End customer city or municipality
contactAddress.zip	string	No	End customer postal code
contactAddress.state	string	No	State or province abbreviation e.g. "NY" for "New York".
contactAddress.country	string	No	End customer two letter country code
customFields	object	Depends	Custom Fields specific to this order
priority	int	No	0, 5 or 10
customReference	string	No	Custom reference text
customReference2	string	No	Custom reference 2 text
internalReference	string	No	Service Providers internal reference
tags	string[]	No	An array of tags as strings
provider	string	No	Order provider name
identifier	string	No	An identifier in the provider's system

¹ Either device.id, device.imeiNumber or device.serialNumber is required ² device.serialNumber can be blank, if the option is enabled via System Settings > API inside Fixably Repair

Update order

Example update order request headers

PATCH /orders/20001234 HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE

Example update order request body

{
  "status": {
    "id": 123
  }
}

Update an order.

PATCH /orders/{order.id}

JSON body parameters

Parameter	Type	Required	Description
status	object	No	Status Status object
status.id	int	Yes	Status id. The new status has to belong to the order's queue.
store	object	No	Store Store object
store.id	int or null	Yes	Store id. Set to null to remove the store from order
location	object	No	Location Location object
location.id	int or null	Yes	Location id. Set to null to remove the location from order
priority	int	No	0, 5 or 10
customReference	string	No	Custom reference text
customReference2	string	No	Custom reference 2 text
internalReference	string	No	Service Providers internal reference
tags	string[]	No	An array of tags as strings
provider	string	No	Order provider name
identifier	string	No	An identifier in the provider's system

Only changed fields are required.

Get order line

Example get order line request

GET /orders/20001234/lines/1234 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get order line response body

{
    "id": 1234,
    "code": "ZD661-10906",
    "name": "64GB, Black, ROW, iPhone XR, CI/AR-ZDD",
    "product": {
        "href": "https://demo.fixably.com/api/v3/products/234"
    },
    "priceRange": "WARRANTY",
    "quantity": "1",
    "quantityCharged": "0",
    "quantityDispatched": "0",
    "price": "0.00",
    "vat": "21.00",
    "discount": "0.00",
    "notes": null,
    "isHidden": false,
    "serialNumber": "ABCDE1234",
    "originalSerialNumber": null,
    "imeiNumber": null,
    "purchasePrice": "0.00",
    "total0": "0.00",
    "total": "0.00",
    "totalCharged0": "0.00",
    "totalCharged": "0.00",
    "totalRemaining0": "0.00",
    "totalRemaining": "0.00"
}

Retrieve an order line item. These are products and services attached to an order.

GET /orders/{order.id}/lines/{line.id}

Parameter	Type	Description
id	int	Unique identifier
code	string	Product code
name	string	Product name
product	object	Reference to the Product
priceRange	string	STOCK, EXCHANGE, WARRANTY or CUSTOM
quantity	string	Quantity of items
quantityCharged	string	Quantity marked as charged or invoiced
quantityDispatched	string	Quantity dispatched (to customer)
price	string	Price
vat	string	Value-added tax or sales tax percentage
discount	string	Discount percentage
notes	string	Free text notes
isHidden	bool	Hidden line item not displayed to customers. For example, a DOA part.
serialNumber	string	Serial number if available
originalSerialNumber	string	Original serial number if available
imeiNumber	string	IMEI number if available
purchasePrice	string	Cost paid by the repair service
total0	string	Total price without tax
total	string	Total price with tax
totalCharged0	string	Total charged and invoiced without tax
totalCharged	string	Total charged and invoiced with tax
totalRemaining0	string	Total amount left to be paid without tax
totalRemaining	string	Total amount left to be paid with tax
customFields	object	Custom Fields specific to this order line

List order lines

List an order's products and services.

GET /orders/{order.id}/lines

Create order line

Example create order line request

POST /orders/20001234/lines HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example create order line request body

{
  "product": {
    "id": 1000
  },
  "priceRange": "WARRANTY",
  "price": "0.0",
  "quantity": "1",
  "vat": "25.00"
}

POST /orders/{order.id}/lines

JSON body parameters

Parameter	Type	Required	Description
product	object	Yes	Products Product object
product.id	int	Yes	Product id
quantity	string	Yes	Amount of products for the line. A whole number is required for physical products.
priceRange	string	Yes	Price ranges Price type
price	string	Yes	Price of the order line without VAT or tax
vat	string	Yes	Tax percentage of the order line
imei	string	No	IMEI number for the order line. Has to be a valid IMEI.
serial	string	No	Serial number for the order line
customFields	object	Depends	Custom Fields specific to this order line

Update order line

Example create order line request

PATCH /orders/20001234/lines/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example update order line request body

{
  "priceRange": "WARRANTY",
  "price": "10.0",
  "quantity": "2",
  "vat": "25.00"
}

PATCH /orders/{order.id}/lines/{line.id}

JSON body parameters

Parameter	Type	Required	Description
quantity	string	Yes	Amount of products for the line. A whole number is required for physical products. Cannot be updated for invoiced or dispatched order lines
priceRange	string	Yes	Price ranges Price type. Cannot be updated for invoiced or dispatched order lines
price	string	Yes	Price of the order line without VAT or tax. Cannot be updated for invoiced or dispatched order lines
vat	string	Yes	Tax percentage of the order line. Cannot be updated for invoiced or dispatched order lines
imei	string	No	IMEI number for the order line. Has to be a valid IMEI.
serial	string	No	Serial number for the order line
customFields	object	Depends	Custom Fields specific to this order line

Delete order line

Example delete order line request

DELETE /orders/20001234/lines/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example delete order line response with HTTP status code 204

204 No Content

If the order line has already been invoiced, the endpoint responds with 400, Bad Request.

DELETE /orders/{order.id}/lines/{line.id}

Get order note

Example get order note request

GET /orders/20001234/notes/4667 HTTP/1.1

Example get order note response

{
    "id": 4667,
    "type": "ISSUE",
    "title": "Issue Description",
    "text": "The customer has cracked the display.",
    "visibility": "VISIBLE",
    "createdAt": "2020-11-06T14:01:42+00:00",
    "createdBy": {
        "href": "https://demo.fixably.com/api/v3/users/3210"
    }
}

Retrieve an order note. Notes are issue descriptions, technician diagnoses, repair resolutions or other details related to the order or repair process.

GET /orders/{order.id}/notes/{note.id}

Parameter	Type	Description
id	int	Unique note identifier
type	string	Note type: ISSUE, DIAGNOSIS, RESOLUTION, SMS, EMAIL, ALARM or OTHER¹
title	string	Optional title text for the note
text	string	Note text
visibility	string	Visibility to customer: VISIBLE, HIDDEN or DELETED
createdAt	datetime	Note creation timestamp
createdBy	object	Link to user that created the note

¹ This list is not complete. Integration specific notes may have a custom type.

List order notes

Lists timeline notes of an order.

GET /orders/{order.id}/notes

Add order notes

Example add order notes request

POST /orders/20001234/notes HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

POST /orders/{order.id}/notes

Example add order notes request body

{
    "notes": [
        {
            "text": "Device not booting up.",
            "type": "ISSUE",
            "createdBy": 5
        }
    ]
}

Example add order notes response body

{
    "notes": [
        {
            "id": 123
        }
    ]
}

Adds timeline notes for the specified order.

JSON body parameters

Parameter	Type	Required	Description
notes	array	Yes	Array of notes
notes[*].text	string	Yes	Body text of the note
notes[*].type	string	Yes	See the table below for available types
notes[*].title	string	No	Optional title for the note
notes[*].createdBy	int	No	Optional user ID for impersonation¹
notes[*].report	bool	No	Display note on reports. The default value is false.
notes[*].sticky	bool	No	Make the note stick to the top of the timeline
notes[*].notify	bool	No	Define if a notification for the order's technician is created or not. If not set the creation will be automatically determined

¹ createdBy requires Allow Impersonation to be enabled in System Settings --> API.

Note Types

Type	Description
INTERNAL	Internal note
ISSUE	Issue description
DIAGNOSIS	Technician's diagnosis
RESOLUTION	Repair resolution
OTHER	Detail note

Get order task

Example get order task request

GET /orders/20001234/tasks/2 HTTP/1.1

Example get order task response body

{
    "id": 2,
    "value": "charger,case",
    "task": {
      "href": "https://demo.fixably.com/api/v3/tasks/2"
    },
    "createdBy": {
        "href": "https://demo.fixably.com/api/v3/users/3210"
    }
}

See Tasks documentation.

Retrieve an order task item. These are tasks that are attached to an order.

GET /orders/{order.id}/tasks/{task.id}

Parameter	Type	Description
id	int	Unique identifier
value	bool, string, int or null	Value of the order task depends on the task type
task	object	Task related to the order task
createdBy	object	User who filled in the order task

List order tasks

Example list order tasks request

GET /orders/20001234/tasks HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list order tasks response body

{
  "limit": 25,
  "offset": 0,
  "totalItems": 4,
  "items": [
    {
      "href": "https://demo.fixably.com/api/v3/orders/20001234/tasks/1"
    },
    {
      "href": "https://demo.fixably.com/api/v3/orders/20001234/tasks/2"
    },
    {
      "href": "https://demo.fixably.com/api/v3/orders/20001234/tasks/3"
    },
    {
      "href": "https://demo.fixably.com/api/v3/orders/20001234/tasks/4"
    }
  ]
}

GET /orders/{order.id}/tasks

Lists all order tasks. See available options for searching.

Create order task

Example create order task request

POST /orders/20001234/tasks/2 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example create order task request body

{
  "value": 3
}

Example create order task response

{
    "id": 2,
    "value": 3,
    "task": {
      "href": "https://demo.fixably.com/api/v3/tasks/2"
    },
    "createdBy": {
        "href": "https://demo.fixably.com/api/v3/users/3210"
    }
}

Fill in a specific order task.

POST /orders/{order.id}/tasks/{task.id}

Creates an order task with the value for the order tasks

JSON body parameters

Parameter	Type	Required	Description
value	bool, string or int	Yes	Value of the order task depends on the task type

The type of the value depends on the type of the task.

Type of the task	Type of the value
BOOL	bool
TEXT	string
SELECT	int
PASSWORD	string

Update order task

Example update order task request

PATCH /orders/20001234/tasks/2 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example update order task request body

{
  "value": 3
}

Example update order task response

{
    "id": 2,
    "value": 3,
    "task": {
      "href": "https://demo.fixably.com/api/v3/tasks/2"
    },
    "createdBy": {
        "href": "https://demo.fixably.com/api/v3/users/3210"
    }
}

Fill in a specific order task.

PATCH /orders/{order.id}/tasks/{ordertask.id}

Updates the value for the order tasks

JSON body parameters

Parameter	Type	Required	Description
value	bool, string or int	Yes	Value of the order task depends on the task type

The type of the value depends on the type of the task.

Type of the task	Type of the value
BOOL	bool
TEXT	string
SELECT	int
PASSWORD	string

Invoice order

Example invoice order request

POST /orders/20000001/invoice HTTP/1.1
Accept: application/json
Authorization: pk_YOUR_API_KEY_HERE

Example invoice order request body

{
  "user": {
    "id": 1001
  },
  "reference": "invoice-10001",
  "contactName": "Jane Doe",
  "lines": [
    {
      "id": 70803
    }
  ],
  "address": {
    "name": "Customer Ltd",
    "address1": "Street",
    "city": "City",
    "zip": "010000",
    "state": "NY",
    "country": "US"
  },
  "isConsolidated": false
}

Example invoice order response body

{
    "id": 123
}

Mark the order as invoiced.

POST /orders/{order.id}/invoice

Parameter	Type	Required	Description
user	object	No¹	Invoice payer. Default is the order's customer.
user.id	int	Yes	Invoice payer ID. See users.
reference	string	No	Invoice reference number
contactName	string	No	Contact name
lines	array	Yes	Invoice lines
lines[*].id	int	Yes	Order line item to invoice
address	object	No	Invoicing address
address.name	string	No	Payer name
address.address1	string	No	Address line 1
address.address2	string	No	Address line 2
address.address3	string	No	Address line 3
address.city	string	No	City or municipality
address.zip	string	No	Postal code
address.state	string	No	State
address.country	string	No	Two letter country code
isConsolidated	bool	No	Consolidates the payer's invoices. Defaults to the "Consolidated" option in customer billing settings.

¹ Required if order has no customer.

Returns HTTP 201 Created after the invoice is created. The response body contains the id of the created invoice.

Returns HTTP 400 Bad Request if support for consolidated invoices is disabled. Please contact support for more details.

Close order

Attempts to close an order if possible.

POST /orders/{order.id}/close

Returns HTTP 200 on success and 4XX if the order can't be closed. Orders that haven't been marked as paid can't be closed.

Dispatch order

Attempts to dispatch order lines. The line items are moved from stock.

POST /orders/{order.id}/dispatch

Returns HTTP 200 on success and 400 if there are no order lines to dispatch.

Change order internal location

Changes the internal location of an order.

POST /orders/{order.id}/internal_location

JSON body parameters

Parameter	Type	Required	Description
internalLocation	string	Yes	Internal location. See the available values below.

Internal location

internalLocation	description
CUSTOMER	device is with customer
SERVICE	device is in service location
STORE	device is in store
IN_TRANSIT	device is in transit
DEALER_SHOP	device is with dealer shop

List order files

List of files related to the order. See files.

Example list order files request

GET /orders/20000002/files HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list files response body

{
  "limit": 25,
  "offset": 0,
  "totalItems": 2,
  "items": [
    {
      "href": "https://demo.fixably.com/api/v3/files/1"
    },
    {
      "href": "https://demo.fixably.com/api/v3/files/2"
    }
  ]
}

GET /orders/{order.id}/files

Attach a file to an order

Example attach file to an order request

POST /orders/20000002/files/attach HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

{
  "key": "demo/user1/test_file.png"
}

The key parameter is the key received from the file upload endpoint

Example file attach response body

{
  "limit": 25,
  "offset": 0,
  "totalItems": 2,
  "items": [
    {
      "href": "https://demo.fixably.com/api/v3/files/476"
    },
    {
      "href": "https://demo.fixably.com/api/v3/files/477",
    }
  ]
}

POST /orders/{order.id}/files/attach

Parameter	Type	Required	Description
key	string	Yes	File key

List shipments

GET /orders/20000002/shipments HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 2,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/shipments/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/shipments/2"
        }
    ]
}

GET /orders/{order.id}/shipments

Payments

Get payment

GET /payments/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON response

{
    "id": 123,
    "created": "2020-09-23T10:14:49+00:00",
    "reference": "abc123",
    "amount": "99.99",
    "type": "Cash",
    "invoice": {
        "href": "https://demo.fixably.com/api/v3/invoices/1"
    }
}

GET /payments/{payment.id}

Parameter	Type	Description
id	int	Unique resource id
created	datetime	Payment made
reference	string	Custom payment reference
amount	float	Amount paid
type	string	Cash/Credit Card/Bank Transfer/Cash on Delivery/Online payment. If payment method is unknown the value is `null`.
invoice	object	Invoice related to the payment

List payments

GET /payments HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/payments/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/payments/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/payments/3"
        }
    ]
}

GET /payments

Payment terms

Payment terms can be defined in Fixably system settings.

Get payment term

GET /payment-terms/1 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

GET /payment-terms/{paymentTerm.id}

Example payment term response

{
  "id": 1,
  "name": "14 days",
  "days": 14
}

Parameter	Type	Description
id	int	Unique identifier
name	string	Name of the payment term
days	int	How many days the payment term allows

List payment terms

GET /payment-terms HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

GET /payment-terms

Example payment terms response

{
  "limit": 25,
  "offset": 0,
  "totalItems": 10,
  "items": [
    {
      "href": "https://demo.fixably.com/api/v3/payment-terms/1"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-terms/2"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-terms/3"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-terms/4"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-terms/5"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-terms/6"
    }
  ]
}

Payment types

Get payment type

GET /payment-types/1 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

GET /payment-types/{paymentType.id}

Example payment type response

{
  "id": 1,
  "name": "Cash",
  "enabled": true
}

Parameter	Type	Description
id	int	Unique identifier
name	string	Name of the payment type
enabled	bool	Enabled/Disabled

List payment types

GET /payment-types HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

GET /payment-types

Example payment types response

{
  "limit": 25,
  "offset": 0,
  "totalItems": 10,
  "items": [
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/0"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/1"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/2"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/3"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/4"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/5"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/6"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/10"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/30"
    },
    {
      "href": "https://demo.fixably.com/api/v3/payment-types/99"
    }
  ]
}

Products

Products include services, parts, and fees that can be added to an order as a line item.

Get product

GET /products/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get product response

{
  "href": "https://demo.fixably.com/api/v3/products/123",
  "id": 123,
  "code": "LOGIC",
  "partNumber": "LGC-123",
  "name": "Logic Board",
  "description": null,
  "ean": null,
  "family": null,
  "line": null,
  "version": null,
  "type": 3,
  "typeString": "Module",
  "category": 4,
  "categoryString": "Input",
  "vat": "20.00",
  "web": null,
  "purchaseStockPrice": "200.00",
  "purchaseExchangePrice": "100.00",
  "stockPrice": "250.00",
  "exchangePrice": "150.00",
  "manufacturer": "Company inc",
  "markup": "0.00",
  "serialized": true,
  "fixed": false,
  "tags": "ABC1, ABC2",
  "eeeCode": null,
  "provider": null,
  "identifier": null,
  "customFields": {},
  "createdAt": "2022-09-07T15:29:25+00:00",
  "updatedAt": "2022-10-04T12:09:29+00:00",
  "visibleOnPrintouts": true
}

Retrieve a single product by its identifier.

GET /products/{product.id}

Parameter	Type	Description
id	int	Unique resource id
code	string	Product code
partNumber	string or null	Manufacturer part number
name	string	Product name
description	string or null	Product description
ean	string or null	Product EAN code
line	string or null	Product line
family	string or null	Product family
type	int	See product types
typeString	string	Product type readable name
version	string or null	Product version
vat	float	Product default VAT
web	int or null	Legacy - Kept for backward compatibility with old clients. Product web link
category	int	Product category
categoryString	string	Product category friendly name
purchaseStockPrice	string	Product purchase price
purchaseExchangePrice	string	Product purchase price for exchange service
stockPrice	string	Product selling price (stock price)
exchangePrice	string	Product exchange price
manufacturer	string	Product manufacturer
markup	string	A fixed price markup added on top of the purchase price
serialized	bool	Is product identifiable with a serial number
fixed	bool	Fixed price (automatic profit margins are not applied)
tags	string or null	Product tags separated by comma
eeeCode	string or null	Product EEE code
provider	string or null	Product provider ie. external source
identifier	string or null	Product identifier for the provider
customFields	object	Custom Fields specific to this product
createdAt	datetime	Created at timestamp
updatedAt	datetime	Updated at timestamp
visibleOnPrintouts	bool	Whether this product is visible on printout order lines

List products

GET /products HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list products response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/products/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/products/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/products/3"
        }
    ]
}

Lists all available products in the system. Results can be filtered using the q query parameter.

GET /products

Get product availability

GET /products/123/availability HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON response

{
  "href": "https://demo.fixably.com/api/v3/products/123/availability",
  "quantity": 2,
  "available": 1
}

Returns stock quantity and availability for a given product. Note that this endpoint requires that the stock module is enabled.

GET /products/{product.id}/availability

Parameter	Type	Description
quantity	int	Total in stocks available to user
available	int	Total available to user minus quantity attached to orders

Create product

POST /products HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example create product request body

{
    "code": "LOGIC",
    "name": "Logic board",
    "description": "Logic Board, 2.8GHz, 16GB",
    "line": "MacBook",
    "type": 3,
    "category": 4,
    "vat": "20.00",
    "purchaseStockPrice": "200.00",
    "purchaseExchangePrice": "100.00",
    "stockPrice": "250.00",
    "exchangePrice": "250.00",
    "manufacturer": "Company inc",
    "serialized": true,
    "fixed": true,
    "visibleOnPrintouts": false
}

Example create product response body

{
  "id": 1234,
  "code": "LOGIC",
  "partNumber": "LOGIC",
  "ean": null,
  "name": "Logic board",
  "description": "Logic Board, 2.8GHz, 16GB",
  "family": null,
  "line": "MacBook",
  "version": null,
  "type": 3,
  "typeString": "Module",
  "category": 4,
  "categoryString": "Input",
  "vat": "20.00",
  "web": null,
  "purchaseStockPrice": "200.00",
  "purchaseExchangePrice": "100.00",
  "stockPrice": "250.00",
  "exchangePrice": "150.00",
  "manufacturer": "Company inc",
  "serialized": true,
  "fixed": true,
  "tags": null,
  "eeeCode": null,
  "provider": null,
  "identifier": null,
  "customFields": {},
  "visibleOnPrintouts": false
}

Creates a new product that can be attached to an order.

POST /products

Parameter	Type	Required	Description
code	string	Yes	Product code
name	string	Yes	Product name
description	string or null	No	Product description
ean	string	No	Product EAN code
line	string	No	Product line
family	string	No	Product family
type	int	No	Product type. See Product types
version	string	No	Product version
vat	string	No	Product default VAT or sales tax percentage
purchaseStockPrice	string	Yes	Product purchase price
purchaseExchangePrice	string	No	Product purchase price for exchange service
stockPrice	string	Yes	Product stock price. For example, "110.55"
exchangePrice	string	No	Product exchange price
markup	string	No	A fixed price markup added on top of the purchase price. For example, "100.00"
manufacturer	string	No	Product manufacturer. See Product manufactures for common manufacturers
serialized	bool	No	Is product identifiable with a serial number
fixed	bool	No	Fixed price (automatic profit margins are not applied)
tags	string	No	Product tags separated by comma
eeeCode	string	No	Product EEE code
provider	string	No	Product provider ie. external source
identifier	string	No	Product identifier in an external system
visibleOnPrintouts	bool	No	Whether this product is visible on printout order lines

Update product

PATCH /products/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example update product request body

{
    "name": "Logic board 2"
}

Example update product response body

{
  "id": 123,
  "code": "LOGIC",
  "partNumber": "LOGIC",
  "ean": "",
  "name": "Logic board 2",
  "description": "Logic Board, 2.8GHz, 16GB",
  "family": null,
  "line": "MacBook",
  "version": null,
  "type": 3,
  "typeString": "Module",
  "category": 4,
  "categoryString": "Input",
  "vat": "20.00",
  "web": null,
  "purchaseStockPrice": "200.00",
  "purchaseExchangePrice": "100.00",
  "stockPrice": "250.00",
  "exchangePrice": "150.00",
  "manufacturer": "",
  "markup": "0.00",
  "serialized": false,
  "fixed": false,
  "tags": "",
  "eeeCode": "",
  "provider": null,
  "identifier": null,
  "customFields": {},
  "visibleOnPrintouts": true
}

Edit an existing product.

PATCH /products/{product.id}

Purchase Invoices

Get purchase invoice

GET /purchase-invoices/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example purchase invoice response body

{
    "id": 123,
    "invoiceId": "AA1111111",
    "date": "2022-01-01",
    "type": "Invoice",
    "purchaseOrder": "1011010",
    "shipTo": "0001217747",
    "serialNumber": "ABC123",
    "invoiceAmount": "23.18",
    "total": "23.18",
    "total0": "23.18",
    "order": {
      "href": "https://demo.fixably.com/api/v3/orders/1"
    }
}

GET /purchase-invoices/{purchaseInvoice.id}

Parameter	Type	Description
id	int	Unique identifier
invoiceId	string	Invoice identifier
date	string	Purchase invoice date in YYYY-MM-DD format
type	string	Purchase invoice type
purchaseOrder	string	Purchase order number
shipTo	string	Ship to identifier
serialNumber	string	Serial number
invoiceAmount	string	Purchase invoice amount
total	string	Purchase invoice total (including tax)
total0	string	Purchase invoice total (excluding tax)
order	object	Order related to the purchase invoice

List purchase invoices

GET /purchase-invoices HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list purchase invoices response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/purchase-invoices/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/purchase-invoices/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/purchase-invoices/3"
        }
    ]
}

GET /purchase-invoices

Purchase Orders

Manage purchase orders directed to external suppliers for products and services.

Get purchase order

Example get purchase order request

GET /purchase-orders/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example purchase order response body

{
    "href": "https://demo.fixably.com/api/v3/purchase-orders/123",
    "id": 123,
    "createdAt": "2021-10-14T08:38:46+0000",
    "number": "20002467/Stock",
    "reference": "G383477574",
    "lines": {
      "href": "https://demo.fixably.com/api/v3/purchase-orders/123/lines"
    },
    "order": {
      "href": "https://demo.fixably.com/api/v3/orders/1"
    },
    "repair": {
      "href": "https://demo.fixably.com/api/v3/repairs/gsx/151"
    },
    "invoice": {
      "href": "https://demo.fixably.com/api/v3/invoices/1"
    }
}

Returns a single purchase order.

GET /purchase-orders/{purchaseOrder.id}

Parameter	Type	Description
id	int	Unique identifier
createdAt	datetime	Purchase order creation date and time
number	string	Purchase order number
reference	string	Purchase order reference
status	string	Purchase order status, See Purchase order status
lines	object	Purchase order lines
order	object or null	Order related to the purchase order
repair	object or null	Repair related to the purchase order
invoice	object or null	Invoice related to the purchase order

List purchase orders

Example list purchase orders request

GET /purchase-orders HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list purchase orders response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/purchase-orders/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/purchase-orders/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/purchase-orders/3"
        }
    ]
}

Lists all purchase orders. See available options for searching and expanding the returned fields.

GET /purchase-orders

Create purchase order

Example create purchase order request

POST /purchase-orders HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example create purchase order request body

{
  "reference": "G383477574",
  "number": "20000067/Stock",
  "products": [
    {
      "id": 15,
      "quantity": "3",
      "price": "100.00"
    },
    {
      "id": 22,
      "quantity": "1",
      "price": "120.50"
    }
  ],
  "vendor": {
    "id": 123
  },
  "stock": {
    "id": 123
  },
  "order": {
    "id": 2000100
  }
}

Creates a new purchase order.

POST /purchase-orders

Parameter	Type	Required	Description
reference	string	No	Purchase order reference
number	string	No	Purchase order number
products	array	Yes	Purchase order products
products[*].id	int	Yes	Product id
products[*].quantity	string	Yes	Product quantity
products[*].price	string	Yes	Product price (including tax)
vendor	object	No	Vendor related to the purchase order
vendor.id	int	Yes	Vendor id
stock	object	No	Stock related to the purchase order
stock.id	int	Yes	Stock id
order	object	No	Order related to the purchase order
order.id	int	Yes	Order id

Get purchase order line

Returns an individual purchase order line item.

Example get purchase order line request

GET /purchase-orders/123/lines/1 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example purchase order line response body

{
    "href": "https://demo.fixably.com/api/v3/purchase-orders/123/lines/1",
    "id": 1,
    "name": "SVC,PKG,BATTERY",
    "mpn": "AA123-03454",
    "quantity": "1.00",
    "price": "120.00",
    "serialNumber": "ABC1234",
    "imei": "",
    "stock": {
      "href": "https://demo.fixably.com/api/v3/stocks/1"
    },
    "receivedAmount": "1.00",
    "receivedAt": "2024-01-01T12:00:00+00:00"
}

GET /purchase-orders/{purchaseOrder.id}/lines/{purchaseOrderLine.id}

Parameter	Type	Description
id	int	Unique identifier
name	string	Product name
mpn	string	Manufacturer part number (MPN)
quantity	string	Quantity of items
price	string	Price
serialNumber	string	Product serial number
imei	string	Product imei
stock	object or null	Stock related to the line
receivedAmount	string	The amount of items received
receivedAt	datetime or null	Time of receiving the product(s)

List purchase order lines

Example list purchase order lines request

GET /purchase-orders/123/lines HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list purchase order lines response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/purchase-orders/123/lines/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/purchase-orders/123/lines/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/purchase-orders/123/lines/3"
        }
    ]
}

Lists all line items related to a given purchase order.

GET /purchase-orders/{purchaseOrder.id}/lines

Queues

Repair service queues.

Get queue

GET /queues/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

Example JSON body

{
    "href": "https://demo.fixably.com/api/v3/queues/123",
    "id": 123,
    "name": "Mac"
}

GET /queues/{queue.id}

Parameter	Description
id	int Unique resource id
name	string Queue name

List queues

GET /queues HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON body

{
    "limit": 25,
    "offset": 0,
    "totalItems": 4,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/queues/1/statuses"
        },
        {
            "href": "https://demo.fixably.com/api/v3/queues/2/statuses"
        },
        {
            "href": "https://demo.fixably.com/api/v3/queues/3/statuses"
        },
        {
            "href": "https://demo.fixably.com/api/v3/queues/4/statuses"
        }
    ]
}

GET /queues

Roles

User and customer roles.

Get role

GET /roles/{role.id}

GET /roles/123 HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example get role response

{
    "id": 123,
    "name": "invoicing",
    "displayName": "Invoicing"
}

Parameter	Type	Description
id	int	Unique identifier
name	string	Role name
displayName	string	Display name

List roles

GET /roles/123 HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example list roles response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 2,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/roles/1",
            "id": 1,
            "name": "reseller",
            "displayName": "Reseller"
        },
        {
            "href": "https://demo.fixably.com/api/v3/roles/2",
            "id": 2,
            "name": "insurance_company",
            "displayName": "Insurance Company"
        }
    ]
}

GET /roles

Lists all available roles.

Service Contracts

Service contracts can be defined for a specific customer or device. Any related service order will display the contract on the order view.

Get service contract

GET /service-contracts/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example service contract response body

{
    "id": 123,
    "name": "Local School contract",
    "description": "The Local School has a service contract with us. Buyer ID: 0001",
    "billingReference": "ABC123",
    "startDate": "2022-01-01",
    "endDate": "2022-01-30",
    "serial": "ABC123",
    "imei": "",
    "customer": {
      "href": "https://demo.fixably.com/api/v3/users/1"
    }
}

GET /service-contracts/{serviceContract.id}

Parameter	Type	Description
id	int	Unique identifier
name	string	Contract name
description	string	Contract description if available
billingReference	string	Contract billing reference if available
startDate	datetime	Contract start date if available
endDate	datetime	Contract end date if available
serial	string	Serial number if available
imei	string	IMEI number if available
customer	object	User related to the contract
priority	string	NORMAL, HIGH or HIGHEST
tags	array	List of user defined tags
type	string	Either "device" or "customer"
contactName	string	End customer contact name
notificationEmail	string	Email address for service contract notifications
customFields	object	Custom Fields specific to this service contract

List service contracts

GET /service-contracts HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list service contracts response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/service-contracts/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/service-contracts/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/service-contracts/3"
        }
    ]
}

GET /service-contracts

Create service contract

Example create service contract request

POST /service-contracts HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example create service contract request body

{
  "name": "Contract name",
  "description": "Description",
  "billingReference": "ABC123",
  "startDate": "2022-01-01",
  "endDate": "2022-01-30",
  "serial": "",
  "imei": "",
  "customer": {
    "id": 123
  }
}

Creates a new service contract.

POST /service-contracts

Parameter	Type	Required	Description
name	string	Yes	Contract name
description	string	No	Contract description
billingReference	string	No	Contract billing reference
startDate	datetime	No	Contract start date
endDate	datetime	No	Contract end date
serial	string	Yes¹	Serial number
imei	string	Yes¹	IMEI number
customer	object	Yes¹	User related to the contract
customer.id	int	Yes	User id
priority	string	No	NORMAL, HIGH or HIGHEST
tags	array	No	List of alphanumeric tags
contactName	string	No	End customer contact name
notificationEmail	string	No	Email address for service contract notifications
customFields	object	Depends	Custom Fields specific to this service contract

¹ Either imei or serial or customer.id is required.

Update service contract

Example update service contract request

PATCH /service-contracts/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example update service contract request body

{
  "notificationEmail": "test@example.com",
  "tags": ["A", "B"],
  "customFields": {
    "test": 123
  }
}

Updates service contract id 123.

PATCH /service-contracts/{serviceContract.id}

Parameter	Type	Required	Description
tags	array	No	List of alphanumeric tags
notificationEmail	string	No	Email address for service contract notifications
customFields	object	no	Custom Fields specific to this service contract

Shipments

Get shipment

GET /shipments/{shipment.id}

Parameter	Type	Description
id	int	Unique resource id
trackingNumber	string	Shipment tracking number
carrier	string	Carrier identifier
reference	string
sender	string
senderAddress	object
recipient	object	Reference to customer
recipientAddress	object
senderLocation	object	Reference to service location
senderStore	object	Reference to store
recipientStore	object	Reference to store
serviceCode	string	Service code from carrier
pickupRequestNumber	string
status	string	Current shipment status if available
packages	array
createdAt	datetime	Shipment creation date and time

List shipments

GET /shipments

Statuses

Service order status. Each service queue can have a specific set of possible order statuses.

Get status

GET /statuses/123 HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example order status response

{
    "href": "https://demo.fixably.com/api/v3/statuses/123",
    "id": 123,
    "name": "In handling",
    "description": "Order is in processing.",
    "type": "IN_DIAGNOSIS",
    "liable": "SERVICE_PROVIDER",
    "isEnabled": true,
    "isDefault": false,
    "queue": {
        "href": "https://demo.fixably.com/api/v3/queues/1"
    },
    "custom": {
        "description": "Integration status"
    }
}

GET /statuses/{status.id}

Parameter	Type	Description
id	int	Unique resource id
name	string	Status name
description	string or null	Optional description
type	string	Status type. See supported values
liable	string	Liable party. See supported values
isEnabled	bool	Indicates if status is enabled
isDefault	bool	Default status that can be assigned automatically based on specific order events.
queue	object	Related service queue. See queues.
custom	object	Integration specific custom fields

List statuses

GET /statuses HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE
Accept: application/json

Example JSON response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 2,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/statuses/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/statuses/2"
        }
    ]
}

GET /statuses

Stocks

Get stock

GET /stocks/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example stock response body

{
    "id": 123,
    "createdAt": "2021-10-14T08:38:46+0000",
    "name": "Repair Products",
    "description": "These are parts used for repairs",
    "location": {
      "href": "https://demo.fixably.com/api/v3/locations/1"
    },
    "store": {
      "href": "https://demo.fixably.com/api/v3/stores/1"
    },
    "isDefault": false
}

GET /stocks/{stock.id}

Parameter	Type	Description
id	int	Unique identifier
createdAt	datetime	Stock creation date and time
name	string	Stock name
description	string	Stock description
location	object	Location related to the stock
store	object	Store related to the stock
isDefault	bool	Stock default status

List stocks

GET /stocks HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list stocks response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/stocks/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/stocks/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/stocks/3"
        }
    ]
}

GET /stocks

List stock products

GET /stocks/123/products HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list stock products response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/stocks/123/products/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/stocks/123/products/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/stocks/123/products/3"
        }
    ]
}

GET /stocks/{stock.id}/products

Update product quantity in stock

PUT /stocks/12/products/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON body

{
  "quantity": 2,
  "info": "Some Comments"
}

PUT /stocks/{stock.id}/products/{product.id}

Parameter	Type	Required	Description
quantity	int	Yes	Product quantity
info	string	No	Info about the quantity update

Create stock

Creates a new warehouse stock.

POST /stocks HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example create stock request JSON body

{
  "name": "Stock A",
  "description": "Repair stock.",
  "location": 1,
  "store": 1,
  "consignment": false
}

POST /stocks

Parameter	Type	Required	Description
name	string	Yes	Stock's name.
description	string	No	Stock's description.
location	int	Yes	Location identifier (See locations).
store	int	Yes/No	Store identifier (See stores). Required if 'stores' are enabled.
consignment	bool	No	A flag to set the stock as a consignment stock.

Example create stock success response JSON body

{
    "id": 10135,
    "name": "Stock A",
    "description": "Repair stock.",
    "location": {
        "href": "https://sample.fixably.com/api/v3/locations/1"
    },
    "store": {
        "href": "https://sample.fixably.com/api/v3/stores/1"
    },
    "isDefault": false,
    "createdAt": "2022-06-22T23:52:23+00:00"
}

Update stock

PUT /stocks/1 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example update stock request body

{
  "name": "Stock A",
  "description": "Repair stock.",
  "location": 1,
  "store": 1,
  "consignment": false
}

PUT /stocks/{stock.id}

Parameter	Type	Required	Description
name	string	Yes	Stock's name.
description	string	No	Stock's description.
location	int	Yes	Location identifier (See locations.)
store	int	No	Store identifier (See stores.)
consignment	bool	No	A flag to set the stock as a consignment stock.

Delete stock

DELETE /stocks/{stock.id} HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example delete stock response with HTTP status code 204

204 No Content

DELETE /stocks/{stock.id}

Add new product to stock

POST /stocks/{stock.id}/products HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example add new product to stock request body

{
  "product": 1,
  "quantity": 1,
  "serialNumber": "ABCD1234",
  "imei": "912144393499275",
  "physicalLocation": "Shelf A12"
}

POST /stocks/{stock.id}/products

Parameter	Type	Required	Description
product	int	Yes	Product's id.
quantity	int	Yes	Product quantity.
serialNumber	string	Yes*	Product's serial number.
imei	string	Yes*	Product's imei number.
physicalLocation	string	No	Product's physical location in the stock.

Either serial number or IMEI number is required

Example of Success Response JSON body with Https Status Code 201

{
    "status": "CREATED"
}

Remove product from stock

DELETE /stocks/{stock.id}/products/{product.id} HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

DELETE /stocks/{stock.id}/products/{product.id}

Stores

Stores are similar to service locations, but they don't make repairs.

Get store

GET /stores/{store.id}

Parameter	Type	Description
id	int	Unique resource id
name	string	Store name

List stores

GET /stores

Tasks

Tasks are custom fields that are displayed on the order view. Admin users can define tasks in System Settings.

Get task

GET /tasks/1 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON response

{
    "id": 1,
    "name": "What accessories are included?",
    "internalName": "Accessories",
    "type": "TEXT"
}

GET /tasks/{task.id}

Parameter	Type	Description
id	int	Unique resource id.
name	string	Public name displayed to customer (e.g. printouts and customer portal).
internalName	string	Internal name.
type	string	Field type TEXT/PASSWORD/BOOL/SELECT.

List tasks

GET /tasks HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example JSON response

{
    "limit": 25,
    "offset": 0,
    "totalItems": 3,
    "items": [
        {
            "href": "https://demo.fixably.com/api/v3/tasks/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/tasks/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/tasks/3"
        }
    ]
}

GET /tasks

Webhooks

Example webhook headers sent by Fixably

POST /webhook HTTP/1.1
Host: example.com
Content-Type: application/json
Token: your-secret-here
Payload-Type: payload-type-here

Example invoice webhook body sent by Fixably

{
  "id": 1234,
  "type": "Invoice",
  "action": "created",
  "orderId": 20000692
}

Example payment webhook body sent by Fixably

{
  "id": 37,
  "invoiceId": 79,
  "action": "created",
  "orderId": 20000002,
  "amount": "114.99"
}

Webhooks can be used to notify external systems about Fixably events. For example, you can automatically notify billing after a new invoice is created in Fixably.

Token

Admin users can configure webhooks in System Settings --> Webhooks.

Webhook request

The POST request sent by Fixably contains the following headers.

Header	Description
Token	A secret token defined in System Settings. You can use this to verify the sender. This is set in case Secret is used as the Authentication method.
Payload-Type	Event type. See the following table for possible values.

The webhook request contains a Payload-Type header that indicates the event type. Webhooks can be created for the following events:

Payload-Type	Name	Description
note	Order notes	When a new order note is created
order	Orders	When a new order is created, edited or updated
invoice	Invoices	When a new invoice is created or voided
appointment	Appointments	When an appointment is created or changed
customer	Customer	When a customer is created, edited or deleted
order_line	Order line	When an order line is created, edited or deleted
stock_quantity	Stock quantity	When a stock quantity is edited
payment	Payment	When a payment is created

Request body

The webhook request JSON body contains the following fields.

Field	Description
id	Reference to the related resource. For example, `/orders/{id}` or `/invoices/{id}`.
action	`created`, `edited`, `voided`, `changed`, `deleted`

Authentication methods

For each webhook in System Settings --> Webhooks an authentication method can be selected from two options:

Secret: Fixably sets the secret to the header Token.
Basic Authentication: Fixably adds the given username and password as query parameters to the request.

Reference

User roles

Value	Description
SERVICE_TECHNICIAN	User working as service technician
RECEPTIONIST	User working in store as receptionist
LOGISTICS	User working in logistics

Priorities

Value	Description
NORMAL
HIGH
HIGHER

Price ranges

Value	Description
STOCK
EXCHANGE
WARRANTY

Product types

Value	Int value	Description
SERVICE	0	Services like `Work fee`
PRODUCT	1	Products with stock value
OTHER	4	Products that do not fit into any other type
TRANSPORT	5	Freight and transport

Product manufacturers

Manufacturer	String
Apple	Apple
Samsung	Samsung
OnePlus	OnePlus
Nokia	Nokia
Huawei	Huawei
Xiaomi	Xiaomi

Week days

Value	Description
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY
WEEKDAY	Weekdays from monday to friday

Liabilities

Liability defines who is responsible

Value	Description
SERVICE_PROVIDER	Service provider
CUSTOMER	Customer
THIRD_PARTY	3rd party

Status types

Value	Description
IN_QUEUE	Order is in queue and waiting for processing
PROCESSING
AWAITING_PARTS	Order is waiting for replacement parts
AWAITING_CUSTOMER
AWAITING_PROCESSING
AWAITING_SHIPPING
READY_FOR_PICKUP	Order is ready for pickup
PICKED_UP	Order has been picked up

File types

Value	Description
THUMBNAIL	Thumbnail
VENDOR INVOICE	Vendor invoice
POP	Proof of purchase
CLC	Consumer law claim
IMAGE	Image
DEVICE IMAGE	Device image (VMI)
VMI IMAGE	Visual Mechanical Inspection image
VIDEO	Video
DOCUMENT	Important document
GSX CLC	GSX Consumer law claim
DEVICE IMAGE	Image of a device
COST ESTIMATE	Cost estimate
COST ESTIMATE XML	Cost estimate XML
GSX OTHER	Other GSX files
GSX FMI	GSX Find my iPhone document
GSX WCR	GSX WCR
BARCODE	Barcode
PROCOUNTOR	Procountor file
IGSPN EWP	IGSPN EWP file
IGSPN OFFICIAL DOCUMENT	IGSPN official document
IGSPN SERIAL NUMBER LABEL	IGSPN Serial number label
TOVACOM UNDEFINED	Undefined Tovacom file
TOVACOM PHOTO	Tovacom photo
TOVACOM POLICE STATEMENT	Tovacom police statement
TOVACOM PURCHASE INVOICE	Tovacom purchase invoice
INVOICE	Invoice
VOID INVOIDE	Voided invoice
RECEIPT	Receipt
VOID RECEIPT	Voided invoice receipt
SHIPMENT	Shipment manifest file
OTHER	Other

Purchase order status

Value	Description
OPEN	We are still awaiting parts to arrive
CLOSED	The shipment(s) have arrived and been received
DELETED	The purchase order was cancelled (from open state)
DRAFT

Errors

E2005

Missing required permissions

E4095

Invalid search query

E4098

Searching the specified query field is not allowed

E4099

Wildcard search not allowed for the field

E4101

Invalid date format

E5002

Unknown error

E10002

Requested resource does not exist

E40000

Invalid JSON structure for custom fields

E40100

Invalid token, username or password

E40105

The fields you specified cannot be searched.

E40401

Requested resource was not found

E40900

Authentication error

E50010

Internal error

E50101

Requested route is not implemented