API

Kathryn H.
Kathryn H.
  • Updated

Overview: What are we talking about?

Gingr offers a publicly available API (Application Programming Interface) to allow you to extract data and build additional functionality around our core product. 

 

If you need data pulled from Gingr in a way that the core product will not support, then you can consult and hire a 3rd-party developer to help determine if and how  Gingr's API will work for you.

 

Our support and development teams are not able to provide guidance for implementing the following instructions. 

 

This article includes:

 

Helpful Hints: Before you begin.

  • Requests are performed with HTTP over TLS (HTTPS) and will return a JSON object as a result. All endpoints are read-only.
  • Important! Never share your API keys with any party that should not be able to access your Gingr data. If you are using an employee's API key and they are no longer with the company, or if you think your API key has been exposed, you can delete and re-create a new key for a user account.

 

How to: Access and Use API Keys.

Before you can start using our API, you must first have a key. All API requests require a key that is based on a user account. You can choose to use your own user account's API key or create a new user account for the purposes of accessing the API. 

 

To access a user's API key to make requests:

  1. To retrieve a user's key, go to the Left-hand Navigation: Reports & More » Users »  Edit User » API Keys.
    Screen_Shot_2021-04-26_at_4.52.39_PM.png

  2. The user account for making API requests must have the Can Access API user permission from Left-hand Navigation: Reports and More Icon » Groups. 
    mceclip0.png

  3. When making an API request, you will need to include the user's API key to make a successful request. 
    Note: You will see example requests reference the key parameter as "{my_key}"

 

How to: Use Gingr's API.

 

 

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',
    2. start_date: 'YYYY-MM-DD'*
    3. end_date: 'YYYY-MM-DD'* Important Note: the maximum range is 30 days
    4. OR checked_in: true (ignores start/end date)
  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

Example cURL call that returns reservations with dates starting and ending in June

HTML

 
curl "https://{your_subdomain_here}.gingrapp.com/api/v1/reservations" \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "start_date=YYYY-MM-DD" \
--data-urlencode "end_date=YYYY-MM-DD" \
--data-urlencode "key={your_api_key_here}"

*Raw dates can be passed with times: YYYY-MM-DD 00:00:00; however, responses only return with date within a 24-hour period. Passing an end_date with time 00:00:01+ will show results for that entire day up to 00:00:00 the next day. Date parameters passed without time will default to a 00:00:00 time stamp. (i.e. single date w/o time should have end_date set for next day for results to show for a single day)


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 date in YYYY-MM-DD format

 

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

Please note: Reservation data for this call is only pulled for the location the User's API is currently logged into. If a pet has reservations for another location the user isn't currently operating in, that reservation info will not show up via API.

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

Please note: Reservation data for this call is only pulled for the location the User's API is currently logged into. If a pet has reservations for another location the user isn't currently operating in, that reservation info will not show up via API.

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: 'YYYY-MM-DD',
    3. end_date: 'YYYY-MM-DD'
  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: 'YYYY-MM-DD'
    3. end_date: 'YYYY-MM-DD'
  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)

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/list_transactions
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: 'YYYY-MM-DD'
    3. to_date: 'YYYY-MM-DD'

 

HTTP GET https://{your_app}.gingrapp.com/api/v1/list_invoices
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: 'YYYY-MM-DD'
    6. to_date: 'YYYY-MM-DD'
 
HTTP POST 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: 'YYYY-MM-DD'
    3. end_date: 'YYYY-MM-DD'
    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_app}.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={user_specific_api_key}"
 
 
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
Example URL:
https://.gingrapp.com/api/v1/custom_field_search?key={{your_api_key}}&form_id=1&field_name=[your custom Field Name on the form]&search=[the search term you are needing to find]
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.

 

Was this article helpful?

0 out of 3 found this helpful

Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.