Articles in this section

API

Avatar
Alex L.
  • Updated
Follow

Overview: What are we talking about?

This functionality is offered by Gingr, but requires the help of a 3rd party web developer hired by your business. Our support and development teams are not able to provide guidance for implementing the following instructions. For your convenience, Gingr does have an API. Requests are performed with HTTP over TLS (HTTPS) and returns a JSON object as a result. All endpoints are read only.

This article includes:

 

Helpful Hints: Before you begin.

  • All requests must present an authorization key. The parameter name is key. If no API key is presented, a JSON object with a status of error is returned. API Keys are per-user and inherit that user's permissions. You can locate a user's API key from the Edit User page.

 

 

How to: Use Gingr's API Keys.

API Keys are found in Left-hand Navigation: Reports & More » Users »  Edit User » API Keys.

 

HTTP POST https://{your_app}.gingrapp.com/api/v1/reservations

 

  1. retrieve a list of reservations within a given date range, or all currently checked in reservations
  2. required parameters
    1. key: 'user_specific_api_key',
  3. optional parameters
    1. location_id: 1 -- either the ID of a location in Gingr, or null - if null, all reservations from all locations are returned
    2. start_date: '2015-06-04T00:00:00+00:00',
    3. end_date: '2015-06-05T00:00:00+00:00' Important Note: the maximum range is 30 days
    4. OR checked_in: true (ignores start/end date)

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/reservation_widget_data

 

  1. retrieve a summary of reservations for a given date, including # of check ins, outs and overnights.
  2. This is the API that powers the widget in the top-center of your Gingr Dashboard. 
  3. required parameters
    1. key: 'user_specific_api_key',
    2. timestamp: a unix timestamp representing a date

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/reservations_by_animal

 

  1. retrieve a list of reservations for a given animal
  2. required parameters
    1. key: - user's API Key
    2. id: 23 - an animal's ID
  3. optional parameters
    1. restrict_to: choose "pending_requests", "currently_checked_in", "future", "past", "wait_listed"
    2. params: an array of
      1. fromDate - ISO 8601 date format
      2. toDate - ISO 8601 date format
      3. reservationTypeIds - an array of reservation type IDs
      4. animalIds - an array of animal IDs
      5. cancelledOnly - boolean
      6. confirmedOnly - boolean
      7. completedOnly - boolean
      8. limit - number, only return these number of records

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/reservations_by_owner

 

  1. retrieve a list of reservations for a given owner
  2. required parameters
    1. key: - user's API Key
    2. id: 23 - an owner's ID
  3. optional parameters
    1. restrict_to: choose "pending_requests", "currently_checked_in", "future", "past", "wait_listed"
    2. params: an array of
      1. fromDate - ISO 8601 date format
      2. toDate - ISO 8601 date format
      3. reservationTypeIds - an array of reservation type IDs
      4. animalIds - an array of animal IDs
      5. cancelledOnly - boolean
      6. confirmedOnly - boolean
      7. completedOnly - boolean
      8. limit - number, only return these number of records

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/reservation_types
  1. retrieve a list of reservation types
  2. required parameters
    1. key: 'user_specific_api_key',
  3. Optional Parameters
    1. id (reservation type id)
    2. active_only true/false
 
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/get_services_by_type
  1. retrieve a list of allowable additional services for a given reservation type
  2. Required Parameters
    1. key (same as other calls)
    2. type_id (reservation type id, integer)
  3. Optional parameters
    1. location_id (location id, integer, probably 1)
 
 
 
HTTP POST https://{your_app}.gingrapp.com/api/v1/authorize_owner
  1. authorize that an owner account exists and a provided password matches what we have on file
  2. Required Parameters
    1. email (customer email address)
    2. password (customers password in gingr)
    3. key (same as other calls)
 
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/report_card_files
  1. retrieve a list of recently uploaded report card files
  2. required fields
    1. key (same as other calls)
  3. optional fields
    1. number days - integer - (today - X days)
    2. limit - integer
    3. location_id

 

 
 
HTTP POST https://{your_app}.gingrapp.com/api/v1/new_modified_owners
  1. customers that were created or modified within the given date range
  2. required parameters
    1. key: 'user_specific_api_key'
    2. start_date: '2015-06-04T00:00:00+00:00',
    3. end_date: '2015-06-05T00:00:00+00:00'
  3. optional parameters
    1. location_id --  if set, filters down to owners of the specified home location
 
 
 
HTTP POST https://{your_app}.gingrapp.com/api/v1/recently_cancelled_reservations
  1. reservations that were cancelled within a given date range
  2. required parameters
    1. key: 'user_specific_api_key'
    2. start_date: '2015-06-04T00:00:00+00:00',
    3. end_date: '2015-06-05T00:00:00+00:00'
  3. optional parameters
    1. location_id --  if set, filters down to owners of the specified home location
 
 
 
HTTP GET https://{your_app}.gingrapp.com/forms/get_form
  1. returns the form's data structure for a type of record
  2. required parameters
    1. form -- either "owner_form" or "animal_form"
 
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/owner
  1. Retrieve information about a specific owner record
  2. required parameters
    1. key
    2. id - A gingr owner id
 
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/get_locations
  1. retrieve a list of locations for this app
  2. required parameters
    1. key
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/get_species
  1. retrieve a list of species for this app
  2. required parameters
    1. key
 

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/get_breeds

  1. retrieve a list of breeds for this app
  2. required parameters
    1. key

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/get_vets

  1. retrieve a list of vets for this app
  2. required parameters
    1. key

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/get_temperaments

  1. retrieve a list of temperaments for this app
  2. required parameters
    1. key
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/get_immunization_types
  1. retrieve a list of immunizations for a given species
  2. required parameters
    1. key
    2. species_id
 
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/get_animal_immunizations
  1. retrieve a list of immunization records for a given animal
  2. required parameters
    1. key
    2. animal_id
 
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/get_all_retail_items
  1. retrieve a list of all retail items for sale
  2. required parameters
    1. key
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/existing_reservation_estimate
  1. retrieve an estimated cost for a future reservation
  2. required parameters
    1. key
    2. id (for a reservation)

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/list_transactions
  1. retrieve a list of transactions
  2. required parameters
    1. key
    2. from_date -- ISO 8601 date
    3. to_date -- ISO 8601 date
 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/transaction
  1. retrieve a transaction
  2. required parameters
    1. key
    2. id -- POS Transaction ID
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/timeclock_report
  1. retrieve a list of timeclock records
  2. required parameters
    1. key
    2. start_date -- ISO 8601 date
    3. end_date -- ISO 8601 date
    4. location_id -- integer
  3. optional parameters
    1. include_deleted -- boolean
    2. include_clocked_in -- boolean
    3. user_ids -- array of user IDs
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/owners
  1. retrieve a list of owners
  2. required parameters
    1. key
  3. optional parameters
    1. params: a key-value array of where clauses for the query
  4. Example cURL call that returns owners with a Zip code of 80302
curl "https://{your-subdomain-here}.gingrapp.com/api/v1/owners" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "key={your-key-here}" \
     --data-urlencode "params[zip]=80302"

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/animals
  1. retrieve a list of animals
  2. required parameters
    1. key
  3. optional parameters
    1. params: a key-value array of where clauses for the query
  4. Example cURL call that returns animals with a birthday in November (using MySQL functions)
HTML
curl "https://{your-subdomain-here}.gingrapp.com/api/v1/animals" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "params[month(from_unixtime(birthday))]=11" \
     --data-urlencode "key={your-key-here}"

 

 
HTTP GET https://{your_app}.gingrapp.com/api/v1/get_subscription
  1. retrieve a single subscription by its ID
  2. required parameters
    1. key
    2. id -- ID of a subscription

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/get_subscriptions

  1. retrieve a list of subscriptions
  2. required parameters
    1. key
  3. optional parameters
    1. include_deleted -- true/false, whether canceled/deleted subscriptions should be returned in the response
    2. bill_day_of_month -- retrieve subscriptions set to renew on a specific day of the month
    3. owner_id -- an owner id, if set the response will be limited to subscriptions of that owner
    4. limit -- how many results to return in this response
    5. offset -- can be used in conjunction with limit to paginate the response
    6. location_id -- if set, response will be limited to a specific location
    7. package_id -- the ID of a particular package
 

HTTP GET https://{your_app}.gingrapp.com/api/v1/custom_field_search

  1. retrieve custom field information for an owner/animal
  2. parameters:
    1. key: your api key
    2. form_id: id of the form you wish to search (owner_form = 1 animal_form = 2)
    3. field_name: technical name of field you wish to search
    4. search: the search term you are looking for on that field_name and form_id
results:
{
 "success": true,
 "error": false,
 "data": [{
 "system_id": "1694",
 "first_name": "Alexandra",
 "last_name": "Smith",
 "home_phone": "(555) 555-5555",
 "cell_phone": "(343) 444-4444",
 "emergency_contact_name": "Melissa Salminen",
 "emergency_contact_phone": "(222) 222-2222",
 "notes": "<b>Authorized Persons<\/b> Melissa Salminen<br>",
 "home_location": "1",
 "password": "adsfadsfasdfasfadsf",
 "stripe_default_card": null,
 "payment_processor_id": "1",
 "allow_online_login": "1",
 "opt_out_email": "0",
 "opt_out_sms": "0",
 "opt_out_marketing_email": "0",
 "opt_out_marketing_sms": "1",
 "opt_out_photo_sharing": "0",
 "opt_out_reminder_email": "0",
 "opt_out_reminder_sms": "0",
 "barcode": null,
 "submission_id": "10904",
 .....
 },
 ....
 ]
}
 

HTTP GET https://{your_app}.gingrapp.com/api/v1/back_of_house (AKA Digital Whiteboard)

  1. retrieve data used to power Gingr's digital whiteboard.
  2. parameters:
    1. key: your api key
    2. location_id (required)
    3. type_ids (required, an array of reservation_type_ids)
    4. mins_future (optional, if set, restricts to the next/last X minutes)
    5. full_day (optional, if set, mins_future field is ignored and system will include all reservations checking in/out today)

Example request

curl 'https://{subdomain}.gingrapp.com/api/v1/back_of_house?key={my_key}&location_id=1&full_day=true'

 Example response

{
 "success": true,
 "error": false,
 "data": {
 "checking_in": [
 {
 "id": "953",
 "owner_id": "94",
 "animal_id": "115",
 "o_last": "Holbrook",
 "a_first": "Maggie",
 "type_id": "1",
 "type": "Daycare | Full Day ",
 "check_in_stamp": null,
 "check_out_stamp": null,
 "start_date": "1559696400",
 "end_date": "1559703600",
 "run_name": null,
 "area_name": null,
 "belonging_count": "0",
 "belonging_area": null,
 "status_id": 2,
 "status_string": "Checking In Soon",
 "event_time": 1559696400
 }, 
 ...
 ],
 "checking_out": [
 {
 "id": "646",
 "owner_id": "8",
 "animal_id": "12",
 "o_last": "Douris",
 "a_first": "Sugar",
 "type_id": "5",
 "type": "Grooming Services",
 "check_in_stamp": "1559657671",
 "check_out_stamp": null,
 "start_date": "1559656800",
 "end_date": "1559664000",
 "run_name": null,
 "area_name": null,
 "belonging_count": "0",
 "belonging_area": null,
 "status_id": 2,
 "status_string": "Checking Out Soon",
 "event_time": 1559664000
 }, 
 ...
 ]
 }
}

FAQ: Check this out! 

 

Is there a daily API limit?

Nope, there is not!

 

Can we create custom queries based off the Gingr data points, or are we only allowed to use the ones in your documentation?

Only the documented API endpoints are currently available for public consumption, though we frequently add to our API!

 

 

Are the calls restricted for data for individual users? 

Each API request must have an API key passed. API keys are issued per user. This key inherits all of that users permissions. Gingr has many types of permissions which can restrict data coming out of the API.



Can we generate lists of users and their contact information, most importantly email, to leverage for marketing automation? 

Yes. Best route for this would be to use Gingr’s webhooks to listen for new/changed owner records.

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk