Documentation
Getting Started
Base Url
https://api.packagex.app/v4/
Header
Key: x-api-key
Value: Available in the API section of the Web Dashboard (portal.packagex.app)
PackageX Portal
Member Expose API
Add New Member
Endpoint
/entity/exposed/member
Description
This endpoint adds a new member in the specified building.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the body of the request in a json format
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
building_key
UUID
Yes
Unique building id for building selection in which the recipient record has to be added. List of buildings along with their uuid are available in the API section of the web dashboard (link: portal.packagex.app).
recipient_name
String
Yes
Name of the recipient.
recipient_email
String
Yes
Email address of the recipient.
recipient_phone
String
No
Phone number of the recipient.
recipient_office_num
String
No
Unit number of the recipient in the building.
recipient_floor
String
No
Floor number of the recipient in the building.
recipient_permanent_address
String
No
Permanent address of recipient.
recipient_profile_picture
Text Base64 encoded
No
Profile picture.
recipient_note
String
No
A specific note for recipient.
recipient_alternate_name
String Array
No
Alternate names / Nick names of the recipient.
recipient_alternate_email
String Array
No
Alternate email addresses of the recipient.
recipient_alternate_phone
String Array
No
Alternate phone numbers of the recipient.
Response Example
{
"recipient_key": "a45d87a3-80fb-4a5e-84aa-98c265de14c8",
"messsage": "Recipient added successfully."
}Get All Members
Endpoint
/entity/exposed/member
Description
This endpoint retrieves all members within access limits of user role.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the query string of the request.
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
building_key
UUID
No
Unique building id for building selection. If set, the result will only contain the members of specific building. List of buildings along with their uuid are available in the API section of the web dashboard (link: portal.packagex.app).
group_key
UUID
No
If set, the result will only contain the recipients of a specific group.
recipient_key
String
No
Should contain comma separated UUID only. UUIDs of recipients for which records to show.
include_num_pending_items
Boolean
No
Default: false. If true, number of pending items associated with all the recipients will also be returned. Recipients with no items in the given time window will not be returned as a result.
item_activity_type
String
No
Default:’SCAN-IN’.Value will be one of ‘SCAN-IN’, ‘SCAN-OUT’, ‘ALL’, return member packages based on filter.
include_designated_recipients_only
Boolean
No
Default: false. If true, only designated No recipients of a group will be returned. Only compatible with group_key parameter.
include_group
Boolean
No
Default: false. if true, the response will contain an array of json group objects.
include_inactive
Boolean
No
Default: false. if true, the response will contain inactive recipients, otherwise only active recipients are returned.
pagination_limit
Integer
No
Default/Max:50, if set, the number of records returned will be equal to this number.
pagination_offset
Integer
No
If set, the result records would be offset-ed by this number.
order_by
String
No
Default created_at. One of the “recent_notified_first”, “email”, “phone”, “created_at”. If ‘recent_notified_first’ is specified, then members who have packages will appear at top and will be sorted according to the packages which have been recently notified.
Response Example
{
"pagination": {
"offset": 0,
"limit": 50,
"max_limit": 50
},
"data": [
{
"recipient_count": "312914",
"recipient_key": null,
"business_id": "8b3872b0-b4ea-aaa8-88e2-9b49432cd4ed",
"recipient_name": "John Smith",
"recipient_email": "john@packagex.xyz",
"recipient_phone": "7777777777",
"recipient_office_num": null,
"recipient_floor": null,
"recipient_permanent_address": null,
"recipient_note": null,
"building_key": "919c9872-6b7a-2f49-91f3-a09ea74cb123",
"building_name": "PackageX",
"recipient_is_hot_desk": false,
"recipient_is_active": true,
"recipient_is_manually_updated": true,
"recipient_is_signed_up": false,
"recipient_alternate_name": null,
"recipient_alternate_phone": null,
"recipient_updated_by": "db079995-978d-9993-9f25-acf5ef450123",
"current_timestamp_updated_at": "2018-11-06T17:46:29.000Z"
}
]
}Delete Member
Endpoint
/entity/exposed/member/{recipient_key}?client_id={client_id}
Description
This endpoint deletes member(s) within access limits of user role. A member cannot be deactivated if they have pending items to be picked.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the body of the request in a json format
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
recipient_key
String
No
Should contain comma seperated UUID only. UUIDs of recipients to delete.
Success Response
{
"message": "Recipient deleted successfully."
}Error Response
{
"message": {
"err_code": "NA02",
"message": "Not Acceptable: Member has pending packages to be picked up."
}
}Put Member
Endpoint
/entity/exposed/member
Description
This endpoint updates a member.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the body of the request in a json format
recipient_key
UUID
Yes
Unique recipient UUID
recipient_name
String
No
Name of the recipient which must be updated if not then same name has to be used.
recipient_email
String
yes
Email of the recipient which needs to be updated if not then same email will be used.
recipient_phone
String
No
Update recipient phone number.
recipient_office_num
String
No
Update office number for the recipient.
recipient_floor
String
No
Update floor for the recipient.
recipient_note
String
No
Update note for the recipient.
recipient_permanent_address
String
No
Update address for the recipient.
recipient_alternate_name
String Array
No
Update alternate names for the recipient.
recipient_alternate_email
String Array
No
Update alternate emails for the recipient.
recipient_alternate_phone
String Array
No
Update alternate phones for the recipient.
Response Example
{
"message": "Member Updated Successfully"
}Package Expose API
Get All Packages
Endpoint
/entity/exposed/package
Description
This endpoint retrieves all item records within access limits of user role.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the query string of the request.
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
building_key
String
No
Should contain comma separated UUID only. UUIDs of buildings for which items to show. List of buildings along with their uuid are available in the API section of the web dashboard (link: portal.packagex.app).
recipient_key
String
No
Should contain comma separated UUID only. UUIDs of recipients for which items to show.
group_key
String
No
Should contain comma separated UUID only. UUIDs of groups for which items to show.
include_image_links
Boolean
No
Default: false. If true, will include item image URLs and item thumbnail image URLs.
include_group_recipient_items
Boolean
No
Default: false. If true, will include group recipients items.
include_recipient_groups
Boolean
No
Default: false. If true, will include group of recipients.
graph_type_filter
Boolean
No
Default: false. If true, will return items based on graph filter dates.
from_date
Date
No
Date in iso 8601 format.
to_date
Date
No
Date in iso 8601 format.
pagination_offset
Integer
No
Default: 0. The pagination offset.
pagination_limit
Integer
No
Default/Max: 50. The pagination limit.
order_by
String
No
Default: created_at. One of the “created_at”, “updated_at”.
order_asc
Boolean
No
Default: false. true to sort packages in ascending order.
filter_option
String
No
Should contain comma separated strings only.One or Multiple the value 'outstanding', 'scanned', 'overdue', 'collected', 'deleted', 'hold', 'discarded', 'snapsend', 'destroy', 'request_forward', 'request_hold', 'forward', 'legacy'.
date_filtering
Boolean
No
Default: false. If true, will return packages based on filter dates.
filter_type
String
No
Default: SCAN-IN.One of the filter “SCAN_OUT”,”ALL”. returns packages based on filter.
Response Example
{
"pagination": {
"offset": 0,
"limit": 50,
"total": 22227,
"max_limit": 50
},
"data": [
{
"items_count": "22227",
"item_key": 1,
"item_recipient_key": null,
"item_uuid": "f933ea59-898b-425d-abcd-ef0f05e4aedc",
"item_act_type": "SCAN-IN",
"recipient_name": null,
"picked_by": 0,
"item_action_status": "FORWARD",
"item_to_address": {
"address": "testing",
"name": "testing",
"shipping_method": "Standard",
"action_label_id": 26,
"label_type": "cta_fwd"
},
"item_images": null,
"item_status_updated_at": "2020-11-04T04:37:52.000Z",
"is_designated": null,
"building_key": 1,
"building_country": "AF",
"item_status": "SCANNED",
"created_at": "2020-10-23T06:41:26.000Z",
"recipient_email": null,
"recipient_phone": null,
"recipient_office": null,
"group_name": null,
"item_group_key": null,
"mailroom_name": "Front Desk",
"item_ml_key": 1,
"building_name": "PackageX Mailroom",
"item_courier": "usps",
"item_tracking_no": "9101026837331000001016",
"item_category": null,
"scanned_by": "2fd9be8f-b412-4222-a197-1000067a3ed0",
"item_note": null,
"item_discard_reason": null,
"item_picked_reason": null,
"updated_at": null,
"item_image": "https://",
"item_image_thumbnail": "https://"
}
]
}Notes
updated_at indicates the picked timestamp of the item. In case of notified items, this field will be NULL.
Notification Webhooks
Notification Webhooks
Description
Mailroom by PackageX provides a capability to receive real-time triggers for all the events from the app and dashboard. The supported events include:
- Inbound:
- Notify (single and multiple)
- Pickup (single and multiple)
- Reminders (single and multiple)
- Reroute (single)
- Discard (single and multiple)
- Outbound:
- Accepted (single and multiple)
- Dispatched (single and multiple)
- Actions on items:
- Scanned & Sent
- Forwarded
- Held
- Destroyed
Webhook Security
Webhook can be secured using basic authentication. The client can choose to provide an x - api - key to secure their webhooks and all triggers to the webhook will contain this x-api-key in the header.
The payload pushed to the webhook is sent in the body of an HTTPS request. As a prevention against man-in-the-middle attacks, HTTP webhooks are NOT supported.
Webhook Registration
Webhooks can be registered in the system by initiating a request to support@packagex.io and providing the required details. You can request to use the same or different webhook URL for all types of notifications. You can also choose to turn ON triggers for only the selected notification types (e.g. Notify and Pickup, etc.) instead of all.
Details required for webhook registration:
- Webhook URL (required)
- api_key (optional – default is without basic authentication)
- Notification types (optional – default is ON for all types of notifications)
Response Example
{
"action": "NOTIFY, // NOTIFY, PICKED, REMIND, DISCARD, REROUTE",
"item_detail": [
{
"item_courier": "fedex",
"item_tracking_no": "70702030023",
"building_name": "City Hall",
"building_address": "123 Market Street",
"building_city": "New York",
"building_state": "NY",
"building_country": "US",
"building_key": "3f6c33eb-7bec-092c-9d9c-8c8857887e95",
"mailroom_code": "FD01",
"mailroom_name": "Front Desk",
"item_uuid": "33333333-7777-092c-abac-8c8b57af7115",
"item_act_type": "SCAN-IN, // SCAN-IN or SCAN-OUT",
"recipient_name": "John Smith",
"recipient_email": "john@email.com",
"sender_name": " // for outbound items",
"sender_email": "jane@email.com // for outbound items",
"item_picked_by": "Brad Stanley",
"picked_by_email": "brad@email.com",
"item_discard_reason": "XYZ",
"item_pickup_reason": "XYZ",
"item_image": "https://",
"picked_by_signature": "https://",
"item_note": "XYZ",
"item_forward_details": null,
"labels": [
"CONFIDENTIAL",
"FRAGILE"
],
"locations": [
"SHELF A",
"GROUND FLOOR"
],
"shipping_method": null
}
]
}Bulk Members
Bulk Members
Endpoint
/entity/exposed/csv/upload
Description
This endpoint add members to system from members CSV file.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the body of the request in a json format
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
building_key
String
Yes
Should contain comma seperated UUID only. UUIDs of buildings for which items to show. List of buildings along with their uuid are available in the API section of the web dashboard (link: portal.packagex.app).
Csv_file
String(base64)
Yes
Should contain base64 of csv file.
Response Example
{
"message": "Processing csv file ...",
"csv_status_key": "asdas-asdasd-asdasdsa-dasdas-dasdsad"
}Add Bulk Members
Endpoint
/entity/exposed/csv/upload
Description
This endpoint will return status of uploaded csv.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the query string of the request.
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
building_key
String
Yes
Should contain comma seperated UUID only. UUID of a building for which all upload logs to show. List of buildings along with their uuid are available in the API section of the web dashboard (link: portal.packagex.app).
csv_status_key
UUID
No
Uuid of specific uploaded record to check sync status.
pagination_offset
Integer
No
Default: 0. The pagination offset
pagination_limit
Integer
No
The pagination limit.
order_by
String
No
Default: created_at. One of the “created_at”, “updated_at”
order_asc
Boolean
No
Default: false. true to sort items in asending order
Response Example
[
{
"log_count": "35",
"csv_status_key": "743c80c2-746a-44d6-ae61-dff397524510",
"status": "SUCCESS",
"errors": null
},
{
"log_count": "35",
"csv_status_key": "eab7fa56-1cdc-45b5-b6de-8392e92c636d",
"status": "SUCCESS",
"errors": null
},
{
"log_count": "35",
"csv_status_key": "d03af7af-1977-4da8-99ef-9afbfc2ed3fd",
"status": "ERROR",
"error": {
"error_type": 1,
"message": "Missing required NAME columns: name"
}
}
]GET Labels
GET Labels
Endpoint
/entity/exposed/labels
Description
This endpoint retrieves all item records within access limits of user role.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the query string of the request.
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
building_key
UUID
No
UUID of building to get building labels
mailroom_key
UUID
No
UUID of mailroom to get labels for
Response Example
{
"cta-fwd": [
{
"key": "heee",
"value": "heee",
"label_key": 455,
"client_key": null,
"building_key": "8b3a7ed2-24ec-4876-b34b-5638c9d1be43",
"building_name": "Hogwarts",
"mailroom_key": null
},
{
"key": "kaka",
"value": "kaka",
"label_key": 454,
"client_key": null,
"building_key": "8b3a7ed2-24ec-4876-b34b-5638c9d1be43",
"building_name": "Hogwarts",
"mailroom_key": null
},
{
"key": "pop",
"value": "pop",
"label_key": 453,
"client_key": "f1590911-eb17-4b56-9974-27f46e0a2ff1",
"building_key": "8b3a7ed2-24ec-4876-b34b-5638c9d1be43",
"building_name": "Hogwarts",
"mailroom_key": "f6d9eda9-1453-4d0f-b7e1-2141ec896ed2"
},
{
"key": "hello",
"value": "hello",
"label_key": 452,
"client_key": null,
"building_key": "8b3a7ed2-24ec-4876-b34b-5638c9d1be43",
"building_name": "Hogwarts",
"mailroom_key": null
},
{
"key": "fore",
"value": "fore",
"label_key": 451,
"client_key": null,
"building_key": "8b3a7ed2-24ec-4876-b34b-5638c9d1be43",
"building_name": "Hogwarts",
"mailroom_key": null
}
]
}GET CTA Request
GET CTA Request
Endpoint
/entity/exposed/requestcta
Description
This endpoint retrieves all item records within access limits of user role.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the query string of the request.
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
building_key
UUID
No
UUID of building to get building labels
Item_uuid
UUID
No
UUID of item(package) to request cta for
Response Example
{
"item_details": [
{
"item_uuid": "b1c93b83-da73-48b2-90f8-2c5188802956",
"item_recipient_key": null,
"item_status": "SCANNED",
"item_act_type": "SCAN-IN",
"recipient_name": null,
"item_action_status": null,
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f",
"building_name": "Islamabad United",
"item_tracking_no": null,
"client_name": "Sherlock Holmes",
"item_image_thumbnail": "https://s3.amazonaws.com/packagex-imgdata-dev/PK/15/B1C93B83-DA73-48B2-90F8-2C5188802956.png"
}
],
"action_items": {},
"action_label": {
"cta-fwd": [
{
"label_key": "172",
"value": "Next Day",
"type": "cta-fwd",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
},
{
"label_key": "173",
"value": "Next Next Day",
"type": "cta-fwd",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
}
],
"cta-hold": [
{
"label_key": "242",
"value": "Hold it",
"type": "cta-hold",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
},
{
"label_key": "244",
"value": "Pending",
"type": "cta-hold",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
},
{
"label_key": "340",
"value": "Global Hold",
"type": "cta-hold",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
}
],
"cta-snapsend": [
{
"label_key": "243",
"value": "Scan and Send to user",
"type": "cta-snapsend",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
},
{
"label_key": "245",
"value": "Not send",
"type": "cta-snapsend",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
}
],
"cta-destroy": [
{
"label_key": "247",
"value": "Defected",
"type": "cta-destroy",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
},
{
"label_key": "246",
"value": "Not relevant",
"type": "cta-destroy",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
},
{
"label_key": "248",
"value": "Destroy",
"type": "cta-destroy",
"client_id": "abb1e889-b809-4b11-b140-e4bfc3d4032b",
"building_key": "c7b774b0-8ed4-4bfa-9784-b8674031240f"
}
]
}
}CTA action on item
CTA action on item
Endpoint
/entity/exposed/ctaaction
Description
This endpoint retrieves all item records within access limits of user role.
Content-Type
application/json
Query Parameters
The following parameters are accepted in the body of the request in a json format
client_id
UUID
Yes
Unique client id for user access verification. Available in the API section of the web dashboard (link: portal.packagex.app).
item_action
String
yes
One of the given action (SNAPSEND,NOTMYPKG FORWARD,DESTROY,)
Item_uuid
UUID
yes
UUID of item(package) to request cta for
address
object
No
{ "name": "Hamid", "address": "Sector E-11, Islamabad", "shipping_method": "cta-fwd" }
label_key
Integer
yes
Key of label
use_existing_address
boolean
No
By default true. Accept Boolean value true/false
Response Example
{
"message": "Status successfully updated."
}