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 401 Unauthorized.

Customers

Get customer

GET /customers/{customer.id}

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

Example get customer response

{
    "id": 123,
    "firstName": "John",
    "lastName": "Doe",
    "company": "Acme Ltd",
    "phone": "12345678",
    "email": "john.doe@example.com",
    "shippingAddress": {
        "id": 1,
        "name": null,
        "address1": "3 Abbey Rd",
        "address2": null,
        "address3": null,
        "zip": "NW8 9AY",
        "city": "London",
        "state": null,
        "country": "GB"
    },
    "billingAddress": null,
    "businessId": "01234567",
    "language": "en",
    "provider": "import",
    "identifier": "import_321",
    "children": {
        "href": "https://demo.fixably.com/api/v3/customers/123/children"
    },
    "tags": [],
    "roles": {
        "href": "https://demo.fixably.com/api/v3/customers/123/roles"
    },
    "createdAt": "2021-10-14T08:38:46+0000",
    "updatedAt": "2021-10-14T08:38:46+0000"
}
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 Shipping address
billingAddress object or null Billing address
businessId string or null Company VAT or tax ID
language string Two letter language code
provider string or null External provider or source
identifier string or null External provider/source identification
children object List of child companies (subsidiaries or departments)
tags array List of tags
roles object List of user roles
updatedAt datetime Timestamp of last update
createdAt datetime Customer creation timestamp

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

POST /customers HTTP/1.1
Authorization: pk_YOUR_API_KEY_HERE

Example create customer request

{
  "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
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": "",
  "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"],
    "productImageUrl": ""
}

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
productImageUrl string Url for a device image

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. Counted from the moment device was received into service location.
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
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
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

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 order line response

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

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

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

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

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

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.

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

List order notes

Lists timeline notes of an order.

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

Adds 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

Changes the internal location of an order.

POST /orders/:id/internal_location

JSON body parameters

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

Update order

Update the order.

PATCH /orders/:id

JSON body parameters

Parameter Type Required Description
status object Yes Status Status object
status.id int Yes Status id. The new status has to belong to the order's queue.
store object Yes Store Store object
store.id int or null Yes Store id. Set to null to remove the store from order

Create order line

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

Example create order line request

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

POST /orders/: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 rangesPrice range for the order line
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

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

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.

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