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

Requests can search items by specifying search criteria in q parameter.

Queries are separated using comma character ,.

Queries without : character are recognised as "filter queries". See below for more information.

Example request to search for users named 'john'

GET /users?q=john HTTP/1.1

Example request to search for users containing john and duck and type USER

GET /users?q=john,duck,type:USER HTTP/1.1

Filter search is the easiest way to quickly filter resources by their most common fields.

Requesting users via filter search would look for given query from firstName, lastName and company fields.

You can specify multiple queries simply by separating them with comma.

Filter search queries cannot contain characters : or ,.

Filter search can be used together with attribute search.

Filter queries are combined using AND operator. No other operators are supported for filter searches.

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.

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.

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 403 Forbidden.

Customers

Get customer

GET /customers/{customer.id}

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

Example JSON 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"
    },
    "billingAddress": null,
    "businessId": "01234567",
    "group": null,
    "language": "en",
    "provider": "import",
    "identifier": "import_321",
    "children": {
        "href": "https://demo.fixably.com/api/v3/customers/123/children"
    }
}
Parameter Description
id int
Unique resource id
firstName string
First name
lastName string
Last name
company string
Company name
phone string
Phone number
email string
Email address
businessId string
Company VAT or tax ID
language string
Two letter language code
provider string
External provider or source
identifier string
External provider/source identification
shippingAddress object
billingAddress object
children array
List of child companies (subsidiaries or departments)

List customers

GET /customers

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

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

Create customer

POST /customers HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE

Example request body

{
  "firstName": "Morty",
  "lastName": "Smith",
  "company": "Ricksy Business",
  "phone": "555-0100",
  "email": "morty@example.com",
  "businessId": "110",
  "language": "en",
  "provider": "import",
  "identifier": "C-132",
  "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"
  }
}

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
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.
shippingAddress object No Ship-to address
shippingAddress.name string No Recipient name
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

¹ Either email or phone is required.

Update customer

PATCH /customers/{customer.id}

PATCH /customers/{customer.id} HTTP/1.1

Example JSON body

{
  "firstName": "Steve",
  "lastName": "Wozniak",
  "company": "Woz U",
  "phone": "555-0100",
  "email": "steve@example.com",
  "businessId": "",
  "language": "en",
  "provider": "MY_INTEGRATION",
  "identifier": "my_id_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"
  }
}

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 JSON response

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

GET /deliveries/{delivery.id}

Parameter Description
id int
Unique resource id
name string
shortName string
description string

List deliveries

GET /deliveries

GET /deliveries 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/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",
  "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, ...)
purchaseCountry string No Three letter ISO 3166-1 country code
purchaseDate string No Estimated purchase date in "YYYY-MM-DD" format

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",
    "distributor": null,
    "purchaseCountry": "USA",
    "purchaseDate": "2015-09-01T00:00:00+0000",
    "isActivationLocked": true,
    "isCarrierLocked": null,
    "isVintage": false,
    "isObsolete": false,
    "isLoaner": null,
    "tags": ["tag1"]
}

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

List devices

GET /devices

GET /devices 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/devices/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/devices/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/devices/3"
        }
    ]
}

Invoices

Get invoice

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

Example JSON response

{
    "id": 123,
    "name": "Acme Ltd",
    "type": "Invoice",
    "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",
    "order": {
        "href": "https://demo.fixably.com/api/v3/orders/1"
    },
    "customer": {
        "href": "https://demo.fixably.com/api/v3/customers/1"
    }
}

GET /invoices/{invoice.id}

Parameter Description
id int
Unique resource id
name string
Invoice payer name
type string
Receipt/Invoice/Cash/Online/Apple Reimbursement
created datetime
Invoice created at datetime
paidDate datetime
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)
order object
Related order object
customer object
Related customer object

List invoices

GET /invoices 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/invoices/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/invoices/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/invoices/3"
        }
    ]
}

GET /invoices

Locations

Repair service locations.

Get location

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

Example JSON 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 Description
id int
Unique resource id
name string
Service location name
email string
phone string
country string
Two letter country code
state string
State, province or region
city string
zip string
ZIP code
address string
tat string
Turnaround time (days)
openingHours object
Opening hour text in different languages
deliveries object
Available delivery methods
longitude string
GPS coordinate
latitude string
GPS coordinate

List locations

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

Example JSON response

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

GET /locations

Orders

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

Get order

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

Example JSON response

{
    "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",
    "customReference": null,
    "device": {
        "href": "https://demo.fixably.com/api/v3/devices/2397"
    },
    "customer": {
        "href": "https://demo.fixably.com/api/v3/customers/1234"
    },
    "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"
    },
    "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"
}

GET /orders/{order.id}

Parameter Description
id int
Order number
isClosed bool
Indicates if order is closed
isInside bool
Indicates if order is at 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
SERVICE, STORE or null
currentInsideTime int
Seconds in service
totalInsideTime int
Total time (seconds) in service
priority string
Order priority
See supported values
tags array
Order tags
createdAt datetime
updatedAt datetime
notes object
Order notes. Issue description, technician's diagnosis, resolution and other
orderedBy object
User who created the order
handledBy object
Assigned technician
reference string
Customer reference
customReference string
Additional reference defined by the repair business
device object
Original device. See devices
customer object
See customer
contact object
Primary contact information for the order
status object
Order status. See statuses
queue object
Service queue. See queues
location object
Repair service location. See locations
store object
Store location. See stores
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

List orders

GET /orders 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/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.

Create order

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

Example JSON request

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

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

Example JSON response

{
    "id": 20000313,
    "isClosed": false,
    "isInside": true,
    "isDraft": false,
    "internalLocation": "SERVICE",
    "transitOrigin": null,
    "currentInsideTime": 1,
    "totalInsideTime": 1,
    "priority": "NORMAL",
    "tags": [],
    "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",
    "customReference": null,
    "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"
}

Get order line

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

Example JSON response

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

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

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

Parameter Description
id int
Unique identifier
code string
Product code
name string
Product name
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
discount string
notes string
Free text notes
isHidden bool
Hidden line not displayed to customer
serialNumber string
Serial number if available
originalSerialNumber string
Original serial number if available
imeiNumber string
IMEI number if available
purchasePrice string
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

List order lines

List an order's products and services.

GET /orders/{order.id}/lines

Get order note

GET /orders/20001234/notes/4667 HTTP/1.1
Parameter Type Description
id int Unique note identifier
title string or null Optional title text for the note
text string Note text
createdAt datetime Note creation timestamp
createdBy object Link to user that created the note

Example order note response

{
    "id": 4667,
    "title": null,
    "text": "The customer has cracked the display.",
    "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}

List order notes

GET /orders/{order.id}/notes

Add order notes

Add notes request example

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

Add timeline notes for the specified order

POST /orders/:id/notes

Example note request body

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

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
Note Types
Type Description
INTERNAL Internal note
ISSUE Issue description
DIAGNOSIS Technician's diagnosis
RESOLUTION Repair resolution

Get order task

See an explanation on what Tasks are.

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

Example JSON response

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

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

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

Example JSON response

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

Update order task

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

Example update order task request body

{
  "value": 3
}

Example JSON 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/{task.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

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

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

¹ Required if order has no customer.

Close order

Attempts to close an order if possible.

POST /orders/{order.id}/close

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

Dispatch order

Attempts to dispatch order lines from order

POST /orders/{order.id}/dispatch

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

Change Order internal location

change the internal location of an order

POST /orders/:id/internal_location

JSON body parameters

Parameter Type Required Description
internalLocation string Required internal location
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

Payments

Get payment

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

Example JSON response

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

GET /payments/{payment.id}

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

List payments

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

Example JSON response

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

GET /payments

Products

Get product

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

Example JSON response

{
  "href": "https://demo.fixably.com/api/v3/products/123",
  "id": 123,
  "code": "LOGIC",
  "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",
  "serialized": true,
  "fixed": false,
  "tags": "ABC1, ABC2",
  "eeeCode": null,
  "provider": null,
  "identifier": null
}

GET /products/{product.id}

Parameter Description
id int
Unique resource id
code string
Product code
name string
Product name
description string
Product description
ean string
Product EAN code
line string
Product line
family string
Product family
type int
Product type
typeString string
Product type readable name
version string
Product version
vat float
Product default VAT
web string
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 stock price
exchangePrice string
Product exchange price
manufacturer string
Product manufacturer
serialized bool
Is product identifiable with a serial number
fixed bool
Fixed price (automatic profit margins are not applied)
tags string
Product tags separated by comma
eeeCode string
Product EEE code
provider string
Product provider ie. external source
identifier string
Product identifier for the provider

List products

GET /products 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/products/1"
        },
        {
            "href": "https://demo.fixably.com/api/v3/products/2"
        },
        {
            "href": "https://demo.fixably.com/api/v3/products/3"
        }
    ]
}

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
}

GET /products/{product.id}/availability

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

Create product

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

POST /products

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

Example JSON body

{
  "code": "LOGIC",
  "name": "Logic Board",
  "description": null,
  "ean": null,
  "family": null,
  "line": null,
  "version": null,
  "type": 3,
  "typeString": "Module",
  "category": 4,
  "categoryString": "Input",
  "vat": 20,
  "web": null,
  "purchaseStockPrice": 100.00,
  "purchaseExchangePrice": 200.00,
  "stockPrice": 150.00,
  "exchangePrice": 250.00,
  "manufacturer": "Company inc",
  "serialized": true,
  "fixed": false,
  "tags": "",
  "eeeCode": "",
  "provider": null,
  "identifier": null
}

Update product

Edit an existing product.

PATCH /products/{product.id}

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

Example JSON body

{
  "code": "LOGIC",
  "name": "Logic Board",
  "description": null,
  "ean": null,
  "family": null,
  "line": null,
  "version": null,
  "type": 3,
  "typeString": "Module",
  "category": 4,
  "categoryString": "Input",
  "vat": 20,
  "web": null,
  "purchaseStockPrice": 100.00,
  "purchaseExchangePrice": 200.00,
  "stockPrice": 150.00,
  "exchangePrice": 250.00,
  "manufacturer": "Company inc",
  "serialized": true,
  "fixed": false,
  "tags": "",
  "eeeCode": "",
  "provider": null,
  "identifier": null
}

Queues

Repair service queues.

Get queue

GET /queues/123 HTTP/1.1
Authorization: pk_4gYSh2fm34IxxzGFaqizzRLh4EqpbUYcgmqOXRZsNw67fkh
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

Example JSON body

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

GET /queues/{queue.id}

Parameter Description
id int
Unique resource id
name string
Queue name

List queues

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

Example JSON body

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

GET /queues

Shipments

Get shipment

GET /shipments/{shipment.id}

Parameter 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

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

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 Description
PRODUCT Products with stock value
SERVICE Services like Work fee
OTHER Other type of products that do not fit into any other type

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
POP Proof of purchase
CLC Consumer law claim
IMAGE Image
DOCUMENT Important document
OTHER Other

Errors

E40101

Invalid or missing API token

E40401

Requested resource does not exist