Guides

Order Management Guide

This guide is designed to help you understand how orders can be created and linked with either an existing patient or an existing site, and the required as well as optional attributes for order creation.

Understanding Patients and Sites

Before we dive into the order creation process, it’s important to understand the entities associated with an order:

  • Patient: A patient profile is stored within Impilo and is managed by the customer. These profiles are essential for personalizing and managing patient-related orders.

  • Site: A site represents a customer-managed location that engages with Impilo’s services. Patients can be associated with a site for the purpose of orders and inventory management. The customer is responsible for managing the set of sites within their account, which can interact with Impilo’s services.

Create Order Endpoint

To create an order, you’ll interact with a specific endpoint designed for this purpose. This endpoint allows you to initiate and configure orders based on your requirements.

Required Attributes

For a successful order creation, you must ensure the following required attributes are correctly provided:

  • Association: Your order must be associated with either an existing patient or an site. It is crucial that exactly one of these is specified for an order, and only the id property of the patient or site is required.

  • Order Content: Your order must include at least one of the following:

  • orderItems: A list of items to be ordered. You must provide at least one item with only the id property required.

  • orderKits: A list of kits to be ordered. Similar to order items, at least one kit must be specified with only the id property required.

Create Patient Order Example

The following request contains the bare minimum for creating an order for an existing patient.

POST
1curl -X POST https://app.impiloplatform.com/api/v3/order \
2     -H "Impilo-API-Key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "externalOrderIds": [
6    "xyz_123_0",
7    "xyz_123_1",
8    "xyz_123_2",
9    "xyz_123_3"
10  ],
11  "patient": {
12    "id": 1234,
13    "sex": "unknown"
14  },
15  "orderItems": [
16    {
17      "item": {
18        "id": 1000
19      },
20      "count": 10
21    },
22    {
23      "item": {
24        "id": 1001
25      },
26      "count": 10
27    },
28    {
29      "item": {
30        "id": 1002
31      },
32      "count": 10
33    },
34    {
35      "item": {
36        "id": 1003
37      },
38      "count": 10
39    }
40  ],
41  "orderKits": [
42    {
43      "kit": {
44        "id": 1000
45      },
46      "count": 10
47    },
48    {
49      "kit": {
50        "id": 1001
51      },
52      "count": 10
53    },
54    {
55      "kit": {
56        "id": 1002
57      },
58      "count": 10
59    },
60    {
61      "kit": {
62        "id": 1003
63      },
64      "count": 10
65    }
66  ]
67}'

Below is an example response containing sample data.

Response
1{
2  "id": 1,
3  "externalOrderIds": [
4    "externalOrderIds"
5  ],
6  "patient": {
7    "id": 1,
8    "externalIdentifier": "1234abcd",
9    "firstName": "John",
10    "lastName": "Doe",
11    "dateOfBirth": "1980-01-01T00:00:00Z",
12    "email": "john.doe@example.com",
13    "phoneNumber": "+1234567890",
14    "archived": true,
15    "address": {
16      "lineOne": "lineOne",
17      "lineTwo": "lineTwo",
18      "lineThree": "lineThree",
19      "city": "city",
20      "state": "state",
21      "zipCode": "zipCode",
22      "country": "country",
23      "note": "note"
24    },
25    "site": {
26      "id": 1,
27      "name": "name",
28      "active": true
29    },
30    "enrolled": true,
31    "sex": "female"
32  },
33  "site": {
34    "id": 1,
35    "name": "name",
36    "active": true,
37    "address": {
38      "lineOne": "lineOne",
39      "lineTwo": "lineTwo",
40      "lineThree": "lineThree",
41      "city": "city",
42      "state": "state",
43      "zipCode": "zipCode",
44      "country": "country",
45      "note": "note"
46    }
47  },
48  "currentStatus": "reconfirmAddress",
49  "orderItems": [
50    {
51      "item": {
52        "id": 1
53      },
54      "count": 1
55    }
56  ],
57  "orderKits": [
58    {
59      "count": 1
60    }
61  ],
62  "orderEvents": [
63    {
64      "name": "name",
65      "eventTimestamp": "eventTimestamp"
66    }
67  ],
68  "trackingNumbers": [
69    {
70      "carrier": "carrier",
71      "value": "value"
72    }
73  ],
74  "devices": [
75    {
76      "id": 1,
77      "item": {
78        "id": 1
79      },
80      "currentStatus": "currentStatus",
81      "used": true,
82      "currentPatient": {
83        "id": 1,
84        "externalIdentifier": "1234abcd",
85        "firstName": "John",
86        "lastName": "Doe",
87        "dateOfBirth": "1980-01-01T00:00:00Z",
88        "email": "john.doe@example.com",
89        "phoneNumber": "+1234567890",
90        "archived": true,
91        "sex": "female"
92      },
93      "site": {
94        "id": 1
95      },
96      "lastHealthCheck": "lastHealthCheck",
97      "deviceIdentifiers": [
98        {}
99      ],
100      "deviceEvents": [
101        {}
102      ],
103      "externalIdentifier": "externalIdentifier"
104    }
105  ],
106  "packedKits": [
107    {
108      "devices": [
109        {
110          "id": 1
111        }
112      ]
113    }
114  ]
115}

Create Site Order Example

The following request contains the bare minimum for creating an order for an existing site.

POST
1curl -X POST https://app.impiloplatform.com/api/v3/order \
2     -H "Impilo-API-Key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "externalOrderIds": [
6    "xyz_123_0",
7    "xyz_123_1",
8    "xyz_123_2",
9    "xyz_123_3"
10  ],
11  "site": {
12    "id": 1234
13  },
14  "orderItems": [
15    {
16      "item": {
17        "id": 1000
18      },
19      "count": 10
20    },
21    {
22      "item": {
23        "id": 1001
24      },
25      "count": 10
26    },
27    {
28      "item": {
29        "id": 1002
30      },
31      "count": 10
32    },
33    {
34      "item": {
35        "id": 1003
36      },
37      "count": 10
38    }
39  ],
40  "orderKits": [
41    {
42      "kit": {
43        "id": 1000
44      },
45      "count": 10
46    },
47    {
48      "kit": {
49        "id": 1001
50      },
51      "count": 10
52    },
53    {
54      "kit": {
55        "id": 1002
56      },
57      "count": 10
58    },
59    {
60      "kit": {
61        "id": 1003
62      },
63      "count": 10
64    }
65  ]
66}'

Below is an example response containing sample data.

Response
1{
2  "id": 1,
3  "externalOrderIds": [
4    "externalOrderIds"
5  ],
6  "patient": {
7    "id": 1,
8    "externalIdentifier": "1234abcd",
9    "firstName": "John",
10    "lastName": "Doe",
11    "dateOfBirth": "1980-01-01T00:00:00Z",
12    "email": "john.doe@example.com",
13    "phoneNumber": "+1234567890",
14    "archived": true,
15    "address": {
16      "lineOne": "lineOne",
17      "lineTwo": "lineTwo",
18      "lineThree": "lineThree",
19      "city": "city",
20      "state": "state",
21      "zipCode": "zipCode",
22      "country": "country",
23      "note": "note"
24    },
25    "site": {
26      "id": 1,
27      "name": "name",
28      "active": true
29    },
30    "enrolled": true,
31    "sex": "female"
32  },
33  "site": {
34    "id": 1,
35    "name": "name",
36    "active": true,
37    "address": {
38      "lineOne": "lineOne",
39      "lineTwo": "lineTwo",
40      "lineThree": "lineThree",
41      "city": "city",
42      "state": "state",
43      "zipCode": "zipCode",
44      "country": "country",
45      "note": "note"
46    }
47  },
48  "currentStatus": "reconfirmAddress",
49  "orderItems": [
50    {
51      "item": {
52        "id": 1
53      },
54      "count": 1
55    }
56  ],
57  "orderKits": [
58    {
59      "count": 1
60    }
61  ],
62  "orderEvents": [
63    {
64      "name": "name",
65      "eventTimestamp": "eventTimestamp"
66    }
67  ],
68  "trackingNumbers": [
69    {
70      "carrier": "carrier",
71      "value": "value"
72    }
73  ],
74  "devices": [
75    {
76      "id": 1,
77      "item": {
78        "id": 1
79      },
80      "currentStatus": "currentStatus",
81      "used": true,
82      "currentPatient": {
83        "id": 1,
84        "externalIdentifier": "1234abcd",
85        "firstName": "John",
86        "lastName": "Doe",
87        "dateOfBirth": "1980-01-01T00:00:00Z",
88        "email": "john.doe@example.com",
89        "phoneNumber": "+1234567890",
90        "archived": true,
91        "sex": "female"
92      },
93      "site": {
94        "id": 1
95      },
96      "lastHealthCheck": "lastHealthCheck",
97      "deviceIdentifiers": [
98        {}
99      ],
100      "deviceEvents": [
101        {}
102      ],
103      "externalIdentifier": "externalIdentifier"
104    }
105  ],
106  "packedKits": [
107    {
108      "devices": [
109        {
110          "id": 1
111        }
112      ]
113    }
114  ]
115}

Optional Attributes

In addition to the required attributes, the following optional attributes can be specified to further customize your order:

  • External Order IDs (externalOrderIds): An array of strings allowing the client to associate one or more of their own order IDs with the Impilo order record. This is particularly useful for tracking and management purposes on the client’s end.

Listing Orders

This functionality allows you to retrieve a list of orders made within the system. It supports pagination to help manage and navigate through large sets of orders effectively. This endpoint is particularly useful for overviewing all orders and analyzing order trends or statuses within a specific timeframe or criteria.

GET
1curl https://app.impiloplatform.com/api/v3/order \
2     -H "Impilo-API-Key: <apiKey>"
Response
1{
2  "content": [
3    {
4      "id": 1,
5      "externalOrderIds": [
6        "externalOrderIds"
7      ],
8      "patient": {
9        "id": 1,
10        "externalIdentifier": "1234abcd",
11        "firstName": "John",
12        "lastName": "Doe",
13        "dateOfBirth": "1980-01-01T00:00:00Z",
14        "email": "john.doe@example.com",
15        "phoneNumber": "+1234567890",
16        "archived": true,
17        "sex": "female"
18      },
19      "site": {
20        "id": 1
21      },
22      "currentStatus": "reconfirmAddress",
23      "orderItems": [
24        {}
25      ],
26      "orderKits": [
27        {}
28      ],
29      "orderEvents": [
30        {}
31      ],
32      "trackingNumbers": [
33        {}
34      ],
35      "devices": [
36        {
37          "id": 1
38        }
39      ],
40      "packedKits": [
41        {}
42      ]
43    }
44  ],
45  "page": 1,
46  "size": 1,
47  "total": 1,
48  "first": true,
49  "last": true
50}

Fetching a Single Order

For detailed analysis or management of a specific order, the system provides an endpoint to fetch the details of a single order using its unique identifier.

GET
1curl https://app.impiloplatform.com/api/v3/order/1 \
2     -H "Impilo-API-Key: <apiKey>"
Response
1{
2  "id": 1,
3  "externalOrderIds": [
4    "externalOrderIds"
5  ],
6  "patient": {
7    "id": 1,
8    "externalIdentifier": "1234abcd",
9    "firstName": "John",
10    "lastName": "Doe",
11    "dateOfBirth": "1980-01-01T00:00:00Z",
12    "email": "john.doe@example.com",
13    "phoneNumber": "+1234567890",
14    "archived": true,
15    "address": {
16      "lineOne": "lineOne",
17      "lineTwo": "lineTwo",
18      "lineThree": "lineThree",
19      "city": "city",
20      "state": "state",
21      "zipCode": "zipCode",
22      "country": "country",
23      "note": "note"
24    },
25    "site": {
26      "id": 1,
27      "name": "name",
28      "active": true
29    },
30    "enrolled": true,
31    "sex": "female"
32  },
33  "site": {
34    "id": 1,
35    "name": "name",
36    "active": true,
37    "address": {
38      "lineOne": "lineOne",
39      "lineTwo": "lineTwo",
40      "lineThree": "lineThree",
41      "city": "city",
42      "state": "state",
43      "zipCode": "zipCode",
44      "country": "country",
45      "note": "note"
46    }
47  },
48  "currentStatus": "reconfirmAddress",
49  "orderItems": [
50    {
51      "item": {
52        "id": 1
53      },
54      "count": 1
55    }
56  ],
57  "orderKits": [
58    {
59      "count": 1
60    }
61  ],
62  "orderEvents": [
63    {
64      "name": "name",
65      "eventTimestamp": "eventTimestamp"
66    }
67  ],
68  "trackingNumbers": [
69    {
70      "carrier": "carrier",
71      "value": "value"
72    }
73  ],
74  "devices": [
75    {
76      "id": 1,
77      "item": {
78        "id": 1
79      },
80      "currentStatus": "currentStatus",
81      "used": true,
82      "currentPatient": {
83        "id": 1,
84        "externalIdentifier": "1234abcd",
85        "firstName": "John",
86        "lastName": "Doe",
87        "dateOfBirth": "1980-01-01T00:00:00Z",
88        "email": "john.doe@example.com",
89        "phoneNumber": "+1234567890",
90        "archived": true,
91        "sex": "female"
92      },
93      "site": {
94        "id": 1
95      },
96      "lastHealthCheck": "lastHealthCheck",
97      "deviceIdentifiers": [
98        {}
99      ],
100      "deviceEvents": [
101        {}
102      ],
103      "externalIdentifier": "externalIdentifier"
104    }
105  ],
106  "packedKits": [
107    {
108      "devices": [
109        {
110          "id": 1
111        }
112      ]
113    }
114  ]
115}

More

Create Order API Reference
Print
Built with