Getting Started ↑

All links below should be prefixed with api.goodcity.hk

Architecture / Diagrams ↑

Authentication ↑

See /api/docs/v1/authentication.html

Language ↑

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

English ↑

{
  territory: {
    id: 1,
    name: "New Territories"
  }
}

Traditional Chinese ↑

{
  territory: {
    id: 1,
    name: "新界"
  }
}

Permissions ↑

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 Error Handling ↑

Validation errors return status 422 Unprocessable Entity and will generally include a json errors attributes hash. For example:

{
  errors:
    {
      mobile: "is invalid"
    }
}

Server responses (non 2XX) ↑

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

Serialization ↑

API v1 ↑

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.

Side-loading ↑

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,
    ]
  }
}

API v2 ↑

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.

Resources

Access passes
Refresh and create access-passes

Resource Description
POST /api/v1/access_passes Create an access_pass

Addresses
List and create addresses for Contacts and Users

Resource Description
POST /api/v1/addresses Create an address
GET /api/v1/address/1 Show an address

Appointment slot presets
Manage a list of appointment slot templates for days of the week.

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

Appointment slots
Manage a list of appointment quotas for special days

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

Authentication
Handle user login and registration

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

Beneficiaries
Manage a list of beneficiaries.

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

Booking types
List Booking Type Options

Resource Description
GET /api/v1/booking_type List all Gogovan Tranports Options.

Boxes
List and create boxes

Resource Description
POST /api/v1/boxes Create an box

Canned responses

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

Companies
Create, update and show a company.

Resource Description
PUT /api/v1/companies/1 Update a company
GET /api/v1/companies/1 List a companies

Computer accessories
Create, update and show a computer_accessory.

Resource Description
PUT /api/v1/computers Create or Update a computer

Computers
Create, update and show a computer.

Resource Description
PUT /api/v1/computers Create or Update a computer

Contacts
Manage contact details for offer collection / delivery

Resource Description
POST /api/v1/contacts Create a new contact

Crossroads transports
List Crossroads Tranports Options

Resource Description
GET /api/v1/crossroads_transports List all Crossroads Tranports Options.

Deliveries
Get, create, and update deliveries.

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

Districts
Districts are sub-regions of Hong Kong territories

Resource Description
GET /api/v1/districts List all districts
GET /api/v1/district/1 List a district

Donor conditions
Categorise the state a donation item is in. E.g. New / Used / Broken

Resource Description
GET /api/v1/donor_conditions List all donor conditions.
GET /api/v1/donor_conditions/1 List a Donor-Condition

Electricals
Create, update and show an Electrical.

Resource Description
PUT /api/v1/electricals Create or Update an electrical

Gogovan orders
Gogovan: Calculate Price and Book Order

Resource Description
POST /api/v1/gogovan_orders/calculate_price Calculate Price

Gogovan transports
List Gogovan Tranports Options

Resource Description
GET /api/v1/gogovan_transports List all Gogovan Tranports Options.

Goodcity requests
List and create GoodcityRequest

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

Goodcity settings
List, create and update GoodcitySetting

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

Holidays
List next available dates (excluding holidays)

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

Identity types
Identity types are the different kind of travel documents a user can have (hkid, asrf, ...)

Resource Description
GET /api/v1/identity_types List all identity types
GET /api/v1/identity_type/1 Get a single identity type

Images
Manage images for items in an offer.

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

Inventory numbers

Resource Description
POST /api/v1/inventory_numbers Create inventory_number
PUT /api/v1/inventory_numbers Delete inventory_number

Items
Get, create, update and delete items.

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

Locations

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

Medicals
Create, update and show action to perform on Medical.

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

Messages
List, show, create and mark_read a message.

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

Offer responses

Resource Description
POST /api/v1/offer_responses Create a Offer Response
GET /api/v1/offer_responses
GET /api/v1/offer_responses/1

Offers
List, create, update and delete offers.

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

Offers packages

Resource Description
DELETE /api/v1/offers_package/1 Delete an offers_package

Orders
Retrieve a list of designations, information about stock items that have been designated to a group or person.

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

Orders packages

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

Organisations
list, show organisations

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

Organisations users
Get Organisations Users.

Resource Description
POST /api/v1/organisations_user Create an organisations_user
POST /api/v1/organisations_user/:id Update an organisations_user

Package categories
package_categories

Resource Description
GET /api/v1/package_categories List all Package Categories

Package sets
Get, create, update and delete package_sets.

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

Package types
Get package types.

Resource Description
GET /api/v1/package_types get all package_types

Packages
Create, update and delete a package.

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

Packages inventories

Resource Description
GET /api/v1/packages_inventories List all packages_inventories

Pallets
List and create pallets

Resource Description
POST /api/v1/pallets Create an pallet

Printers
List Printer Options

Resource Description
GET /api/v1/printer List all active printers

Printers users

Resource Description
POST /api/v1/printers_users Create an printers_user
PUT /api/v1/printers_users/1 Update printers_users

Process checklists
List Processing checklist items

Resource Description
GET /api/v1/process_checklists List all processing checklists options.

Processing destinations
List Processing Destination Items

Resource Description
GET /api/v1/processing_destinations List all Processing Destination Lookups.

Purposes
List all Purpose

Resource Description
GET /api/v1/purposes List all Purpose.

Rejection reasons

Resource Description
GET /api/v1/rejections_reasons List all rejection reasons.
GET /api/v1/rejection_reasons/1 List a Rejection Reason

Requested packages
Get requested packages.

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

Restrictions
List all Restriction

Resource Description
GET /api/v1/restrictions List all Restriction.

Schedules
Schedule will help donors to plan their donation pick up.

Resource Description
GET /api/v1/schedules List of available schedules for current week
POST /api/v1/schedules Make a booking for the pick up

Stockit activities

Resource Description
POST /api/v1/stockit_acitivites Create or Update a stockit_activity

Stockit contacts

Resource Description
POST /api/v1/stockit_contacts Create or Update a stockit_contact

Stockit local orders

Resource Description
POST /api/v1/stockit_local_orders Create or Update a stockit_local_order

Stockit organisations

Resource Description
POST /api/v1/stockit_organisations Create or Update a stockit_organisation

Stocktake revisions
Stocktake Revisions

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

Stocktakes
List Stocktake Options

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

Territories
Hong Kong is divided into territories which is further subdivided into districts.

Resource Description
GET /api/v1/territories List all territories
GET /api/v1/territory/1 List a territory

Timeslots
List all time-slots.

Resource Description
GET /api/v1/timeslots List all time-slots

Twilio inbound
Handle Twilio Inbound Voice Calls

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

Twilio outbound
Handle Twilio Outbound Calls

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.

User favourites

Resource Description
GET /api/v1/user_favourites Fetches user_favourites

User roles

Resource Description
POST /api/v1/user_roles Add an user_role

Users
List Users

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

Versions
List versions of items and related packages

Resource Description
GET /api/v1/versions List versions of items and related packages
GET /api/v1/versions/1 List a version