Articles in this section

API Keys

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.

  • In order to use an API key, the user must possess the Can Access API user permission from Left-hand Navigation: Reports and More Icon » Groups. 
     mceclip0.png

 

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
  3. optional parameters
    1. id (owner ID)
    2. animal_id (animal ID)
    3. reservation_id (reservation_id)
    4. phone (cell phone number)
    5. email
 
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)

 

Note: this API endpoint will only return POS Transactions before August 1, 2019.
  1. retrieve a list of transactions
  2. required parameters
    1. key
    2. from_date -- ISO 8601 date
    3. to_date -- ISO 8601 date

 

Note: this API endpoint will only return Invoices created on/after August 1, 2019.
  1. retrieve a list of transactions
  2. required parameters
    1. key
  3. optional parameters
    1. per_page -- integer; number of results to return (this + `page` param below enables pagination). defaults to null
    2. page -- integer; offset number of results to return. defaults to null.
    3. complete -- boolean (true or false); when set to true, will only return Invoices. When false, will only return Estimates. defaults to false.
    4. closed_only -- boolean (true or false); when set to true, will only return closed invoices. when set to false, will return open & closed invoices. defaults to false.
    5. from_date -- ISO 8601 date
    6. to_date -- ISO 8601 date 
 
HTTP GET https://{your_app}.gingrapp.com/api/v1/transaction
  1. retrieve a transaction and payment details
  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
 }, 
 ...
 ]
 }
}

 

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

  1. checks in pet(s) for an existing reservation, if one does not exist it will create one and check it in.
  2. required parameters
    1. key
  3. optional parameters
    1. animal_id
    2. owner_id
    3. type_id -- if set, system will use this reservation type id for new reservations. if not set, it will default to your system's quick type

 

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

  1. Notify Gingr of an incoming phone call. This will trigger an in-app alert in Gingr as well as record the call.
  2. required parameters
    1. key
    2. From (phone number making the call)
    3. Called (phone number receiving the call)CallStatus (one of: initiated, ringing, answered, completed, in-progress, no-answer)
    4. CallSid (unique identifier for the call in the source system)
  3. optional parameters
    1. CallDuration (length of call in seconds)
HTTP GET  https://{your_app}.gingrapp.com/api/v1/get_feeding_info
  1. Retrieve an animal's feeding information
  2. required parameters
    1. key
    2. animal_id
HTTP GET  https://{your_app}.gingrapp.com/api/v1/get_medication_info
  1. Retrieve an animal's medication information
  2. required parameters
    1. key
    2. animal_id
 
 

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.

 

 

Why do some Animals/Owners not have a "created_at" value? 

Anything without a "created_at" value means that the customer profile was imported. On the other hand, any customers who were not imported (created in Gingr) will have a "created_at" value associated with the account.

This can also happen with Lead Forms. When a lead form is submitted, it creates a placeholder owner record without a "created_at" value. This is because the client isn't considered a customer yet, but rather a lead. Once they convert to a customer, which is done by adding an animal to their record, the "owners.created_at" field will be set. At this point, they are considered a customer in your app.

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk