All links below should be prefixed with api.goodcity.hk
See /api/docs/v1/authentication.html
Some taxonomy lists such as ItemTypes, Districts and Territories have Traditional Chinese 中文 translations. When sending an API request, include the following header to set the language. This will return translated data (where applicable). If no language header is set or the language requested is not available, the API will default to English.
The Accept-Language headers allows the following options:
Accept-Language: en Accept-Language: zh-tw
{ territory: { id: 1, name: "New Territories" } }
{ territory: { id: 1, name: "新界" } }
The API will only provide access to objects the authenticated user has permission to see. For example: when a donor lists all offers, only offers they have created are returned. When a Reviewer views all offers, they will see everything.
Validation errors return status 422 Unprocessable Entity
and will generally include a json errors attributes hash. For example:
{ errors: { mobile: "is invalid" } }
If you send a request to the server without the correct parameters, the response will be 400 Bad Request
{ error: "Bad Request" }
401 Unauthorized
errors return the following format:
{ error: "Invalid token" }
If there is a 500 Server Error
, it will be returned in the following format:
{ error: "Internal Server Error" }
All responses are serialized in JSON format. Objects are serialized using ActiveModelSerializer.
Partial example:
{ "offer" : { "id" : 1731, "language" : "en", "state" : "draft", "origin" : "web", "stairs" : false, "parking" : false, "estimated_size" : "4" } }
Please refer to a specific controller for more detailed examples.
Objects that contain related data may also include those relationships to reduce the number of API requests required.
In the following example, an API call has been made to /api/v1/territories/306
. The response payload includes both the territory attributes and the related districts.
{ "districts" : [ { "id" : 118, "name" : "Shek Kong", "territory_id" : 306 }, { "id" : 119, "name" : "Tsz Wan Shan", "territory_id" : 306 }, ], "territory" : { "id" : 306, "name" : "New Territories", "district_ids" : [ 118, 119, ] } }
All responses are serialized in the JSON API format. Objects are serialized using JSON:API.
Example
{
"data": { "id": "3", "type": "movie", "attributes": { "name": "test movie", "year": null }, "relationships": { "actors": { "data": [ { "id": "1", "type": "actor" }, { "id": "2", "type": "actor" } ] }, "owner": { "data": { "id": "3", "type": "user" } } } }
}
Please refer to a specific controller for more detailed examples.
Resource | Description |
---|---|
POST /api/v1/access_passes | Create an access_pass |
Resource | Description |
---|---|
POST /api/v1/addresses | Create an address |
GET /api/v1/address/1 | Show an address |
Resource | Description |
---|---|
GET /api/v1/appointment_slot_presets | List all preset appointment slots |
POST /api/v1/appointment_slot_presets | Add a preset appointment slot |
PUT /api/v1/appointment_slot_presets/1 | Update a preset appointment slot |
DELETE /api/v1/appointment_slot_presets/1 | Delete a preset appointment slot |
Resource | Description |
---|---|
GET /api/v1/appointment_slots | List upcoming appointment slots |
GET /api/v1/appointment_slots/calendar | List upcoming appointment slots aggregated by dates |
POST /api/v1/appointment_slots | Add an appointment slot |
PUT /api/v1/appointment_slots/1 | Update an appointment slot |
DELETE /api/v1/appointment_slots/1 | Delete a preset appointment slot |
Resource | Description |
---|---|
POST /api/v1/auth/send_pin | Send SMS code to the registered mobile |
POST /api/v1/auth/signup_and_send_pin | Register a new user |
POST /api/v1/auth/signup | Register a new user |
POST /api/v1/auth/verify | Verify OTP code |
GET /api/v1/auth/current_user_profile | Retrieve current authenticated user profile details |
POST /api/v1/auth/register_device | Register a mobile device to receive notifications |
GET /api/v1/auth/current_user_rooms | Retrieve the list of socketio rooms the user can listen to |
Resource | Description |
---|---|
GET /api/v1/beneficiaries | List all beneficiaries |
GET /api/v1/beneficiaries/1 | Get one beneficiary |
POST /api/v1/beneficiaries | Create a beneficiary |
PUT /api/v1/beneficiaries/1 | Update user |
DELETE /api/v1/beneficiary/1 | Delete a beneficiary |
Resource | Description |
---|---|
GET /api/v1/booking_type | List all Gogovan Tranports Options. |
Resource | Description |
---|---|
POST /api/v1/boxes | Create an box |
Resource | Description |
---|---|
GET /api/v1/canned_responses | List all system / user canned_responses |
POST /api/v1/canned_responses | Creates user canned_responses |
PUT /api/v1/canned_responses/:id | Updates canned_responses for the id |
DELETE /api/v1/canned_responses/:id | Delete canned_responses by id |
SHOW /api/v1/canned_responses/:guid | Get canned_response identified by guid |
Resource | Description |
---|---|
PUT /api/v1/companies/1 | Update a company |
GET /api/v1/companies/1 | List a companies |
Resource | Description |
---|---|
PUT /api/v1/computers | Create or Update a computer |
Resource | Description |
---|---|
PUT /api/v1/computers | Create or Update a computer |
Resource | Description |
---|---|
POST /api/v1/contacts | Create a new contact |
Resource | Description |
---|---|
GET /api/v1/crossroads_transports | List all Crossroads Tranports Options. |
Resource | Description |
---|---|
POST /api/v1/deliveries | Create a delivery |
GET /api/v1/deliveries/1 | Get a delivery |
PUT /api/v1/deliveries/1 | Update a delivery |
DELETE /api/v1/deliveries/1 | Delete delivery |
POST /api/confirm_delivery | Confirm Delivery with address, contact and schedule details |
Resource | Description |
---|---|
GET /api/v1/districts | List all districts |
GET /api/v1/district/1 | List a district |
Resource | Description |
---|---|
GET /api/v1/donor_conditions | List all donor conditions. |
GET /api/v1/donor_conditions/1 | List a Donor-Condition |
Resource | Description |
---|---|
PUT /api/v1/electricals | Create or Update an electrical |
Resource | Description |
---|---|
POST /api/v1/gogovan_orders/calculate_price | Calculate Price |
Resource | Description |
---|---|
GET /api/v1/gogovan_transports | List all Gogovan Tranports Options. |
Resource | Description |
---|---|
GET /api/v1/goodcity_requests | List goodcity_requests |
POST /api/v1/goodcity_requests | Create goodcity_request |
PUT /api/v1/goodcity_requests/1 | Update a goodcity_request |
DELETE /api/v1/goodcity_requests/1 | Delete goodcity_request |
Resource | Description |
---|---|
GET /api/v1/goodcity_settings | List goodcity_settings |
POST /api/v1/goodcity_settings | Create goodcity_setting |
PUT /api/v1/goodcity_settings/1 | Update a goodcity_setting |
DELETE /api/v1/goodcity_settings/1 | Delete goodcity_setting |
Resource | Description |
---|---|
GET /api/v1/holidays/available_dates | List all available dates |
POST /api/v1/holidays | Create holiday |
GET /api/v1/holidays | List all holidays |
DELETE /api/v1/holidays/1 | Delete holiday |
PUT /api/v1/holidays/1 | Update holiday |
Resource | Description |
---|---|
GET /api/v1/identity_types | List all identity types |
GET /api/v1/identity_type/1 | Get a single identity type |
Resource | Description |
---|---|
GET /api/v1/images/generate_signature | Use this method to get an authentication signature in order to upload an image to the Cloudinary service. |
POST /api/v1/images | Create an image |
DELETE /api/v1/images/1 | Delete an image |
PUT /api/v1/images/1 | Update an image |
Resource | Description |
---|---|
POST /api/v1/inventory_numbers | Create inventory_number |
PUT /api/v1/inventory_numbers | Delete inventory_number |
Resource | Description |
---|---|
POST /api/v1/items | Create an item |
GET /api/v1/item/1 | Get an item |
DELETE /api/v1/items/1 | Delete an item |
PUT /api/v1/items/1 | Update an item |
Resource | Description |
---|---|
GET /api/v1/locations | List all locations |
POST /api/v1/locations | Create or Update a location |
DELETE /api/v1/locations/1 | Delete Location |
Resource | Description |
---|---|
GET /api/v1/medicals | Return all medical items |
SHOW /api/v1/medicals/1 | Return a medical item record |
UPDATE /api/v1/medicals/1 | Updates a medical item record |
DELETE /api/v1/medicals/1 | Deletes a medical item record |
Resource | Description |
---|---|
GET /api/v1/messages | List all messages |
GET /api/v1/messages/1 | Get a message |
POST /api/v1/messages | Create an message |
PUT /api/v1/messages/:id/mark_read | Mark message as read |
PUT /api/v1/messages/mark_all_read | Mark all messages as read |
GET /api/v1/messages/notifications | List all notifications for current user |
Resource | Description |
---|---|
POST /api/v1/offer_responses | Create a Offer Response |
GET /api/v1/offer_responses | |
GET /api/v1/offer_responses/1 |
Resource | Description |
---|---|
POST /api/v1/offers | Create an offer |
GET /api/v1/offers | List all offers |
GET /api/v1/offers/search?searchText=xyz | Search for offers |
GET /api/v1/offers/1 | List an offer |
PUT /api/v1/offers/1 | Update an offer |
DELETE /api/v1/offers/1 | Delete an offer |
PUT /api/v1/offers/1/review | Assign current_user as Offer reviewer. If two or more reviewers start review at the same time, assign offer to the first reviewer and return offer with reviewer details to other reviewer(s) |
PUT /api/v1/offers/1/complete_review | Mark review as completed |
PUT /api/v1/offers/1/close_offer | Mark Offer as closed. |
PUT /api/v1/offers/1/receive_offer | Mark Offer as received. |
PUT /api/v1/offers/1/mark_inactive | Mark offer as inactive |
PUT /api/v1/offers/1/reopen_offer | Reopen closed/cancelled offer |
PUT /api/v1/offers/1/resume_receiving | Change Offer to Receiving state |
GET /api/v1/offers/summary | Returns general stats on current offers |
PUT /api/v1/offers/1/merge_offer | Merges current offer into the base offer |
GET /api/v1/offers/1/mergeable_offers | Returns offers allowed to merge with |
Resource | Description |
---|---|
DELETE /api/v1/offers_package/1 | Delete an offers_package |
Resource | Description |
---|---|
POST /api/v1/orders | Create or Update a order |
GET /api/v1/orders | List all orders |
GET /api/v1/designations/1 | Get a order |
PUT /api/v1/orders/1 | Update an order |
Resource | Description |
---|---|
GET /api/v1/orders_packages | List all orders_packages |
DELETE /api/v1/orders_package/1 | Delete an orders_package |
PUT /api/v1/orders_packages/:id/actions/:action_name | Executes an action |
Resource | Description |
---|---|
POST /api/v1/organisation | Create Organisation |
PUT /api/v1/organisation/1 | Update Organisation |
GET /api/v1/organisations | List all organisations |
GET /api/v1/organisations/1 | Details of a package |
GET /api/v1/organisations/names | List all organisations names |
GET /api/v1/organisations/:id/orders | List all orders associated with organisation |
Resource | Description |
---|---|
POST /api/v1/organisations_user | Create an organisations_user |
POST /api/v1/organisations_user/:id | Update an organisations_user |
Resource | Description |
---|---|
GET /api/v1/package_categories | List all Package Categories |
Resource | Description |
---|---|
GET /api/v1/package_sets | Get a package set |
POST /api/v1/package_sets | Create a package set |
PUT /api/v1/package_sets/1 | Update an package_set_id |
DELETE /api/v1/package_sets/1 | Delete a package_set |
Resource | Description |
---|---|
GET /api/v1/package_types | get all package_types |
Resource | Description |
---|---|
GET /api/v1/packages | get all packages for the item |
GET /api/v1/packages/1 | Details of a package |
GET /api/v1/stockit_items/1 | Details of a stockit_item(package) |
POST /api/v1/packages | Create a package |
PUT /api/v1/packages/1 | Update a package |
DELETE /api/v1/packages/1 | Delete an package |
PUT /api/v1/packages/1 | Mark a package as missing |
POST /api/v1/packages/print_barcode | Print barcode |
GET /api/v1/packages/package_valuation | Get valuation of package based on its condition, grade and package type |
GET /api/v1/packages/search_stockit_items | Search packages (items for stock app) using inventory-number |
PUT /api/v1/packages/1/move | Move a package's quantity to an new location |
PUT /api/v1/packages/1/designate | Designate a package's quantity to an order |
PUT /api/v1/packages/1/actions/:action_name | Executes an action on a package |
GET /api/v1/packages/1/contained_packages | Returns the packages nested inside of current package |
GET /api/v1/packages/1/parent_containers | Returns the packages which contain current package |
GET /api/v1/packages/:id/versions | List all versions associated with package |
Resource | Description |
---|---|
GET /api/v1/packages_inventories | List all packages_inventories |
Resource | Description |
---|---|
POST /api/v1/pallets | Create an pallet |
Resource | Description |
---|---|
GET /api/v1/printer | List all active printers |
Resource | Description |
---|---|
POST /api/v1/printers_users | Create an printers_user |
PUT /api/v1/printers_users/1 | Update printers_users |
Resource | Description |
---|---|
GET /api/v1/process_checklists | List all processing checklists options. |
Resource | Description |
---|---|
GET /api/v1/processing_destinations | List all Processing Destination Lookups. |
Resource | Description |
---|---|
GET /api/v1/purposes | List all Purpose. |
Resource | Description |
---|---|
GET /api/v1/rejections_reasons | List all rejection reasons. |
GET /api/v1/rejection_reasons/1 | List a Rejection Reason |
Resource | Description |
---|---|
GET /api/v1/requested_packages | List the user's requested packages |
POST /api/v1/requested_packages | Create a cart item |
PUT /api/v1/requested_packages | Update a cart item |
POST /api/v1/requested_packages/checkout | Checkout and add all the packages to an order |
DELETE /api/v1/requested_packages/1 | Delete a cart item |
Resource | Description |
---|---|
GET /api/v1/restrictions | List all Restriction. |
Resource | Description |
---|---|
GET /api/v1/schedules | List of available schedules for current week |
POST /api/v1/schedules | Make a booking for the pick up |
Resource | Description |
---|---|
POST /api/v1/stockit_acitivites | Create or Update a stockit_activity |
Resource | Description |
---|---|
POST /api/v1/stockit_contacts | Create or Update a stockit_contact |
Resource | Description |
---|---|
POST /api/v1/stockit_local_orders | Create or Update a stockit_local_order |
Resource | Description |
---|---|
POST /api/v1/stockit_organisations | Create or Update a stockit_organisation |
Resource | Description |
---|---|
POST /api/v1/stocktake_revisions | Create a stocktake revision |
PUT /api/v1/stocktakes/:id | Updates a revision |
DELETE /api/v1/stocktakes/:id | Deletes a revision |
Resource | Description |
---|---|
GET /api/v1/stocktakes | List all stocktakes |
GET /api/v1/stocktakes/:id | Get a stocktake by id |
POST /api/v1/stocktakes | Create a stocktake |
PUT /api/v1/stocktakes/:id/commit | Processes a stocktake and tries to apply changes |
PUT /api/v1/stocktakes/:id/cancel | Cancels a stocktake |
DELETE /api/v1/stocktakes/:id | Deletes a stocktake and all its revisions |
Resource | Description |
---|---|
GET /api/v1/territories | List all territories |
GET /api/v1/territory/1 | List a territory |
Resource | Description |
---|---|
GET /api/v1/timeslots | List all time-slots |
Resource | Description |
---|---|
POST /api/v1/twilio_inbound/assignment | Called by Twilio when worker becomes Idle and Task is added to TaskQueue |
POST /api/v1/twilio_inbound/call_complete | This action will be called from twilio when call is completed |
POST /api/v1/twilio_inbound/call_fallback | On runtime exception, invalid response or timeout at api request from Twilio to our application(at 'api/v1/twilio_inbound/voice') |
POST /api/v1/twilio_inbound/voice | Called by Twilio when Donor calls to Goodcity Voice Number. |
POST /api/v1/twilio_inbound/hold_donor | Twilio Response to the caller waiting in queue |
POST /api/v1/accept_callback | Twilio response sent when user press 1 key |
POST /api/v1/send_voicemail | After voicemail, recording-Link sent to message thread and call is disconnected. |
GET /api/v1/twilio_inbound/accept_call | |
GET /api/v1/twilio_inbound/hold_music | Returns mp3 file played for user while waiting in queue. |
POST /api/v1/accept_offer_id | Twilio response sent when input offer ID |
Resource | Description |
---|---|
POST /api/v1/twilio_outbound/connect_call | When an Admin calls a donor from the application, Twilio will call this hook to determine what it should do (who to call etc...) |
POST /api/v1/twilio_outbound/completed_call | Outbound call from Admin to donor: Response sent to twilio when call fails, timeout or no response from Donor. |
POST /api/v1/twilio_outbound/call_status | Called from Twilio when outbound call between Admin and Donor is completed. |
GET /api/v1/twilio_outbound/generate_call_token | Generate Twilio Outgoing Call Capability Token. This allows clients to authenticate with Twilio and place calls etc. |
Resource | Description |
---|---|
GET /api/v1/user_favourites | Fetches user_favourites |
Resource | Description |
---|---|
POST /api/v1/user_roles | Add an user_role |
Resource | Description |
---|---|
GET /api/v1/users | List all users |
POST /api/v1/users | Create user |
GET /api/v1/users/1 | List a user |
PUT /api/v1/users/1 | Update user |
DELETE /api/v1/users/1 | Delete user |
GET /api/v1/users/mentionable_users | Get mentionable users based on messageable context and roles |
PUT /api/v1/users/merge_users | Merge one user details into another user |
PUT /apiv1/users/1/grant_access | Grant access to user using access-pass-key |
Resource | Description |
---|---|
GET /api/v1/versions | List versions of items and related packages |
GET /api/v1/versions/1 | List a version |