API questions and answers

Short answers to the questions integrators ask most, each with the call that does it. For a whole job in order, see how to schedule an order.

https://{host}/{companyKey}/rest

Every request is HTTP Basic: the user's access key as the username and secret access key as the password, generated in ISN under Settings → My Access Keys. Examples use the domain 4isn.com and the company key yourcompany, with the keys in $ACCESS_KEY and $SECRET_ACCESS_KEY. Identifiers are UUIDs and are shortened here.

Orders

How do I set or update an order's report number?

Send the new number to the order's report-number endpoint. The path takes the order's UUID, not its numeric id. This works whether the order has no number yet or already has one.

Request

curl -u "$ACCESS_KEY:$SECRET_ACCESS_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"reportnumber":"HMS-0001"}' \
  https://4isn.com/yourcompany/rest/order/reportnumber/3f9c…

Response

{ "status": "ok", "message": "", "reportnumber": "HMS-0001" }

Where the UUID comes from: The id on each order from GET /orders or GET /orders/search. GET /order/{id} returns the order's current reportnumber.
Read status, not the HTTP code: An unknown UUID is a 200 with "status":"error" and the message could not locate order with provided uuid.
JSON needs the content type: Without Content-Type: application/json the body is read as form fields (reportnumber=HMS-0001). A JSON body sent as a form arrives as nothing at all, and the number is cleared.
Limits: Up to 50 characters. ISN does not check that report numbers are unique, so a system that generates its own numbers has to guarantee that itself.
It sticks: Setting a number marks it as set by hand, so ISN's own report-number generation never overwrites it, even for a company that has a numbering template.
Empty clears it: An empty or missing reportnumber blanks the field and still answers "status":"ok". Check the value before you send it.
Other places it is accepted: reportnumber is also a field on POST /order when you create an order and on POST /order/{id} when you update one.

Reference: POST /order/reportnumber/{id}

How do I find orders that have no report number?

There is no filter for a blank number. Page through GET /orders, read reportnumber on each order, and treat an empty string as missing. To find one order by its number, use GET /orders/search?reportnumber=…. It matches a substring, not the whole value, so check what comes back.

Request

curl -u "$ACCESS_KEY:$SECRET_ACCESS_KEY" \
  "https://4isn.com/yourcompany/rest/orders/search?reportnumber=HMS-0001"

Reference: GET /orders · GET /orders/search