NAV
HTTP

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

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

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 ,.

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.

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.

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]

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.

Parameters can be searched by defining the range inside parenthesis.

total:[start,end]

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-10-11

2024-08-02

2024-05-07

2024-05-02

2024-04-25

2024-04-05

2024-03-07

2024-02-15

2023-11-23

2023-10-12

2023-09-19

2023-09-06

2023-08-03

2023-07-06

2023-04-04

2023-01-12

2022-11-11

2022-10-12

2022-09-15

2022-06-08

2022-05-25

2022-05-12

2022-04-22

2022-04-08

2022-03-29

2022-03-22

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.

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

Token

Requests that require authentication will return 401 Unauthorized.

Cost Estimates

Customers can receive multiple cost estimate options via email and select their preferred option.

Get cost estimate

Example get cost estimate request

GET /cost-estimates/45 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get cost estimate response

{
    "href": "https://demo.fixably.com/api/v3/cost-estimates/45",
    "id": 45,
    "message": "Message to the customer.",
    "issue": "Device not booting.",
    "order": {
        "href": "https://demo.fixably.com/api/v3/orders/20000336"
    },
    "options": {
        "href": "https://demo.fixably.com/api/v3/cost-estimates/45/options"
    },
    "createdAt": "2024-10-10T06:30:20+00:00",
    "expiresAt": "2024-10-20T06:30:20+00:00",
    "selectedAt": null,
    "closedAt": null,
    "current": true,
    "portalLink": "https://example.com/estimate?key=6d744dc8e967873cc17a1425b1abc123"
}

GET /cost-estimates/{id}

Field Type Description
id int Unique resource id
message string Cost estimate message
issue string Issue description
order object Related order
options object Cost estimate options
createdAt datetime Cost estimate creation time
expiresAt datetime or null Cost estimate expiration time
selectedAt datetime or null Time when customer selected the cost estimate option
closedAt datetime or null Cost estimate closed at time
current bool If the cost estimate is currently active for the order
portalLink string or null Link to the cost estimate in Fixably portal

List cost estimates

Example list cost estimate request

GET /cost-estimates HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list cost estimates response

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

GET /cost-estimates

Lists all available cost estimates.

Select cost estimate option

Example select cost estimate option request

POST /cost-estimates/123/select HTTP/1.1
Accept: application/json
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh

Example select cost estimate option request body

{
    "option": {
        "id": 345
    }
}

POST /cost-estimates/{id}/select

Marks a cost estimate option as selected.

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": [
            {
                "id": 1,
                "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
                }
            },
            {
                "id": 2,
                "name": "Condition",
                "canonicalName": "condition",
                "description": "Condition of the device when we received 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.

Create custom field

POST /custom-fields

Example create custom field request

POST /custom-fields HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE

Example create custom field request body

{
    "name": "Foobar",
    "description": "Test custom field.",
    "type": "text",
    "model": "devices"
}

Example create custom field response

{
    "id": 201,
    "name": "Foobar",
    "canonicalName": "foobar",
    "description": "Test custom field.",
    "type": "text",
    "options": [],
    "model": "devices",
    "enabled": true
}
Parameter Type Required Description
name string Yes Custom field name
description string No Description
type string Yes Type of field: text, numeric, yesno, options
model string Yes Related resource: devices, orders, orderlines, products, servicecontracts, users
options string[] No¹ List of options. Only applicable when type is "options".

¹ Required when custom field type is "options".

Update custom field

PATCH /custom-fields/{id}

Example update custom field request

PATCH /custom-fields/123 HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE

Example update custom field request

{
    "name": "Color",
    "description": "Select color.",
    "options": ["foo", "bar"],
    "enabled": true
}

Example update custom field response

{
    "id": 123,
    "name": "Color",
    "canonicalName": "color",
    "description": "Select color.",
    "type": "options",
    "options": [
        "foo",
        "bar"
    ],
    "model": "device",
    "enabled": true
}
Parameter Type Required Description
name string No Custom field name
description string No Description
options string[] No List of options. Only applicable when type is "options".
enabled bool No Enable or disable the custom field

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"
        }
    ]
}

Update device

Example update device request

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

Example device update request body

{
  "serialNumber": "ABCDE123",
  "name": "iPhone X",
  "configuration": "IPHONE X,64GB,SILVER",
  "purchaseCountry": "USA",
  "brand": "APPLE",
  "model": "IPHONE",
  "code": "ZD661-03109",
  "purchaseDate": "2021-01-01",
  "tags": ["ABC"]
}
Parameter Type Required Description
serialNumber string No Unique serial number
imeiNumber1 string No IMEI number
imeiNumber2 string No Secondary IMEI number
name string No 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
source string No Device data source e.g. "GSX"
identifier string No Custom identifier
purchaseCountry string No Three letter ISO 3166-1 country code
purchaseDate string No Estimated purchase date in "YYYY-MM-DD" format
tags string[] No List of tags
customFields object No Custom Fields relative to this device

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.

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

Manifests

Get manifest

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

Example get manifest response body

{
    "id": 1,
    "number": "987654321",
    "reference": "Ref1",
    "trackingNumber": "_123245678",
    "comments": "Is a comment",
    "customer": {
      "href": "https://demo.fixably.com/api/v3/customers/1"
    },
    "location": {
      "href": "https://demo.fixably.com/api/v3/locations/1"
    },
    "lines": {
      "href": "https://demo.fixably.com/api/v3/manifests/1/lines"
    }
}

GET /manifests/{id}

Parameter Type Description
id int Unique resource id
number string Manifest number
reference string Manifest reference.
trackingNumber string Manifest tracking number
comments string Comments
location object Service location
customer object Customer
lines object Manifest lines

List manifests

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

Example list manifests response body

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

Get manifest line

GET /manifests/1/lines/1 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example get manifest response body

{
    "id": 1,
    "brand": "SAMSUNG",
    "model": "SM-G950F",
    "serial": "",
    "imei": "",
    "quantity": 5,
    "comments": "Some comments"
}

GET /manifests/{manifestId}/lines/{id}

Parameter Type Description
id int Unique resource id
brand string or null Manifest item's brand
model string or null Manifest item's model
serial string or null Manifest item's serial number
imei string or null Manifest item's imei number
quantity int Manifest item's quantity
comments string Manifest item's comments

List manifest lines

GET /manifests/123/lines HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json

Example list manifest lines response body

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

GET /manifests/{id}/lines

Create manifest

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

Example create manifest request body

{
    "number": "987654321",
    "reference": "Ref1",
    "trackingNumber": "_123245678",
    "comments": "Is a comment",
    "customer": {
      "id": 1
    },
    "location": {
      "id": 1
    },
    "lines": [
      {
        "brand": "APPLE",
        "serial": "MQFW9X6GWZKJ",
        "imei": "912144393499275",
        "quantity": 1,
        "comments": "A comment"
      }
    ]
}

Example create manifest response body

{
    "id": 1,
    "number": "987654321",
    "reference": "Ref1",
    "trackingNumber": "_123245678",
    "comments": "Is a comment",
    "customer": {
      "href": "https://demo.fixably.com/api/v3/customers/1"
    },
    "location": {
      "href": "https://demo.fixably.com/api/v3/locations/1"
    },
    "lines": {
      "href": "https://demo.fixably.com/api/v3/manifests/1/lines"
    }
}

POST /manifests

Parameter Type Required Description
number string No Manifest number
reference string No Manifest reference.
trackingNumber string No Manifest tracking number
comments string No Comments
location object Yes Service location
location.id int Yes Location id for manifest
customer object Yes Customer
customer.id int Yes Customer id for manifest
lines array Yes Manifest item lines
lines[*].brand string No¹ Manifest line brand
lines[*].serial string No² Manifest line serial number
lines[*].imei string No² Manifest line imei number
lines[*].model string No² Manifest line model
lines[*].quantity int Yes Manifest line quantity. Should be 1 if serial or imei is used

¹ Brand is required with lines[*].serial

² lines[*].serial, lines[*].imei or lines[*].model is required ```

Update manifest

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

Example update manifest request body

{
    "customer":{
      "id": 2
    },
    "reference": "New reference",
    "trackingNumber": "TRACKNO_123"
}

PATCH /manifests

Parameter Type Required Description
reference string No Manifest reference.
trackingNumber string No Manifest tracking number¹
comments string No Comments
location object No Service location
location.id int Yes Location id for manifest¹
customer object No Customer
customer.id int Yes Customer id for manifest¹
lines array No Manifest item lines ²
lines[*].id int No Manifest line id
lines[*].brand string No Manifest line brand
lines[*].serial string No Manifest line serial number
lines[*].imei string No Manifest line imei number
lines[*].model string No Manifest line model
lines[*].quantity int No Manifest line quantity. Should be 1 if serial or imei is used

¹ Tracking number, customer and location may only be updated if no manifest lines have been processed yet ² Only unprocessed manifest lines may be updated

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
  },
  "queue": {
    "id": 4
  },
  "tags": ["example"],
  "provider": "SAP",
  "identifier": "REF123"
}

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
queue object No Queue Queue object
queue.id int Yes Service queue id
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",
    "status": "DRAFT"
}

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
status string Order line's status. See Order line status

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 invoiced or 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

View payments of invoices.

Get payment

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

Example get payment response body

{
    "id": 123,
    "created": "2020-09-23T10:14:49+00:00",
    "reference": "abc123",
    "amount": "99.99",
    "type": {
        "href": "https://demo.fixably.com/api/v3/payment-types/1"
    },
    "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 string Amount paid
type object Payment type related to the payment
invoice object Invoice related to the payment

List payments

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

Example list payments response body

{
    "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

Example get queue request

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

Example get queue response headers

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

Example get queue response body

{
    "href": "https://demo.fixably.com/api/v3/queues/123",
    "id": 123,
    "name": "Mac",
    "description": "Service queue for Apple Mac product line.",
    "enabled": true,
    "statuses": {
        "href": "https://demo.fixably.com/api/v3/queues/123/statuses"
    }
}

GET /queues/{queue.id}

Parameter Type Description
id int Unique resource id
name string Queue name
description string Queue description
enabled bool Queue is enabled or disabled
statuses object List of available order statuses

List queues

Example list queues request

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

Example list queues response body

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

GET /queues

Lists all available service 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.

Legacy Service Contracts

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

Get legacy service contract

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

Example legacy service contract response body

{
    "id": 123,
    "name": "Local School contract",
    "description": "The Local School has a legacy 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 /legacy-service-contracts/{legacyServiceContract.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 legacy service contract notifications
customFields object Custom Fields specific to this legacy service contract
terminatedAt datetime Termination date if available (UTC)
terminatedReason string Termination reason if available

List legacy service contracts

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

Example list legacy service contracts response

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

GET /legacy-service-contracts

Create legacy service contract

Example create legacy service contract request

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

Example create legacy 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 legacy service contract.

POST /legacy-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 legacy service contract notifications
customFields object Depends Custom Fields specific to this legacy service contract

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

Update legacy service contract

Example update legacy service contract request

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

Example update legacy service contract request body

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

Updates legacy service contract id 123.

PATCH /legacy-service-contracts/{legacyServiceContract.id}

Parameter Type Required Description
tags array No List of alphanumeric tags
notificationEmail string No Email address for legacy service contract notifications
customFields object No Custom Fields specific to this legacy service contract
priority string No NORMAL, HIGH or HIGHEST

Terminate legacy service contract

Example terminate legacy service contract request

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

Example terminate legacy service contract request body

{
  "reason": "By request of the customer"
}

Terminate legacy service contract id 123.

POST /legacy-service-contracts/{legacyServiceContract.id}/terminate

Parameter Type Required Description
reason string Yes Free text

Extend legacy service contract

Example extend legacy service contract request

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

Example terminate legacy service contract request body

{
  "extendTo": "2026-01-01"
}

Extend legacy service contract id 123

Parameter Type Required Description
extendTo date Yes YYYY-MM-DD

Example extend legacy service contract response body

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

POST /legacy-service-contracts/{serviceContract.id}/extend

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 legacy service contract notifications
customFields object Custom Fields specific to this legacy service contract
terminatedAt datetime Termination date if available (UTC)
terminatedReason string Termination reason if available

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.

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
product Product When an product is created or edited

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:

  1. Secret: Fixably sets the secret to the header Token.
  2. 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
REPLACEMENT 2 Replacement part
MODULE 3 Module
OTHER 4 Products that do not fit into any other type
TRANSPORT 5 Freight and transport
LOANER 6 Loaner device
EXCESS 7
BUYBACK 8 Buyback product
SERVICE_CONTRACT 9 Service contract
BUNDLE 99 Product bundle

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

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

Order line status

Value Description
DRAFT Order line is a draft
CONFIRMED OUT OF STOCK Part use confirmed, order line's parts are not available in stock
CONFIRMED IN STOCK Part use confirmed, order line's parts are available in stock
PARTS ORDERED A purchase order containing the parts for the order line has been created
PARTS ARRIVED Purchase order containing order line's parts has been received
PARTS COLLECTED Order line's parts have been collected by technician
PARTS DRAFT ORDERED Order line's parts have been added to a draft purchase order
LOANER RESERVED Loaner part reserved
LOANED Loaner part loaned
LOANER RETURNED Loaner part returned
READY FOR COLLECTION Order line's parts are ready for the technician to collect
PENDING RETURN TO STOCK Order line's parts await return to their original stock
RETURNED TO STOCK Order line's parts have been returned to their original stock
PART ORDER IN PROGRESS Someone is currently ordering the parts for this order line

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

HTTP