FAQ / Common Issues

Parameters are being used but filtering does not seem to be working

Ensure "ParameterType.RequestBody" is being used for parameters, otherwise they are most likely being send as querystring values.

After including an ID of 4 I get  Error converting value 4 to type 'System.Int32[]'

The parameter might be expecting an array instead of a single integer, try converting the integer to an array.

UpdatedSinceUtc must be in the Utc format.

Check out our dates page on how to format dates.

If allowed this update could potentially overwrite newer information

This can happen when the LastUpdatedDate for an entity is not set. This is to ensure you are retrieving the latest details of an entity so that change are not overwritten by another api call or user.

Is there an API that gives us the local time we are connecting to?

This is available in our location endpoint:

api/v2/location/physicallocation/{id}

This has the locations of each shelter, and then a UtcOffset property you can use to find the UTC Time zone.

Why do I receive a credentials don't match a valid user when authenticating?

This can sometimes happen when the username and password is not URL encoded.

How do i get a list of adoptable animals?

All the API endpoints are listed on our Resources page, the endpoint that we suggest to get adoptable animals (or other searching like lost or found or stray etc) would be the POST api/v2/animal/list?page={page}&pageSize={pageSize} endpoint.  There is some setup to go along with this using these instructions:

1. Setup a search group using the ShelterBuddy application via administration > search group.  You will select which statuses / sources you would like included in your search group

2. Using the api/v2/animal/list?page={page}&pageSize={pageSize} endpoint you would setup a search model with the following:

   1. SearchGroupId: this would be from the new search group you set up.  To get a list of search groups you can use the 
      api/v2/animal/searchgroup/list?page={page}&pageSize={pageSize} end point.

   2. UpdatedSinceUTC: This would be to get new animals updated to the search group since you last queried this information.

3. To check if an animal is no longer in the search group you can use the same endpoint but post with the parameter ExcludeSearchGroupId and UpdatedSinceUTC this will get the list of animals taken off the list since a specific date.

How do i get a list of animals in foster that have been microchipped?

Similar to the above adoptable animals, this can be achieved by search groups:

1. Using the endpoint api/v2/animal/list?page={page}&pageSize={pageSize} you would setup a search model with the following:

   1. SearchGroupId: this would be from the new search group we set up called "Animals In Foster".  To get a list of search groups you can use the api/v2/animal/searchgroup/list?page={page}&pageSize={pageSize} end point and get the ID from here.

   2. UpdatedSinceUTC: This would be to get new animals updated to the search group since you last queried this information.

2. You would loop through all these pets and check if they have a microchip number, if they do you could enroll them into homesafe under the RSPCA QLD owner.

If the animal then gets adopted, or changes owner through the existing processes these will be picked up through your normal API methods.

How do I get a list of adopted animals?

To get a list of adopted animals you can use StatusHistoryV2 with the property DateRange for the dates you want new adoptions for.  You would then populate the Status property with an array of adopted statuses.  To get adopted status you use the StatusV2 endpoint and post with the IsAdoption property.

How do I get a list of in care animals?

This can be achieved by first getting a list of in care statuses, then using this list to query animals with that status:

1. Using the endpoint api/v2/animal/status/list?page={page}&pageSize={pageSize} you can use the search model with the following to get a list of statusId's for in care statuses:

   1. "IsInCare": true

2. Using the endpoint api/v2/animal/list?page={page}&pageSize={pageSize} you would setup a search model with the following:

   1. "StatusId": this accepts an array of id's so you can use the list of in care status Id's retrieved in step 1.

   2. UpdatedSinceUTC: This can be used to get new animals updated since you last queried.

How do I capture pre registrations for adoptions or events?

The api endpoints important for this are:

AcquisitionV2:  This is the reason why we are acquiring a person, for example it may just be a General adoption enquiring, or a specific adoption event.

AcquiredPersonV2:  This is where you will post new people to based on the form filled out from your website online form.

•  AcquisitionId is from the AcquisitionV2 end point and it relates to why you are acquiring the person.  

• Appeal category is for fundraising appeal and not usually used.

• Meta Data is a key value pair, for example:

  "MetaData": [{key:"MyKey",value:"MyValue"}]

When adding a person via the AcquiredPersonV2 endpoint, they will then show up in a area in shelterbuddy for users to find pre registered people, and then users check if they exist and merge them in or create a new person.   From within the ShelterBuddy app, on the main search page there is a link "Pre Registration / Data Acquisition" And then the link for each indivdual acquisition type. This lists all the pre registered people. Once the person is merged or created, then users can process the person (e.g. an adoption) as per normal.

What is the ideal method for accessing photos?

For public sites like an adoptable animal site the photos should be downloaded and cached locally.  When polling for animal updates you should re-download photos in case the animal update included a photo change.  Photos can be retrieved by using the PhotoV2 endpoint and posting a search model with the animal Id.

The photov2 endpoint includes a url for the photo, just simply prepend the site domain to the start of the url to access the photo. There is no need to append the file name extension as well (e.g. “jpg”).

Is the animal's last updated date updated when a photo is added or updated?

Yes, when a user updates or adds a photo, the animals last updated date is updated.

How do I put an animal on hold?

To put an animal on hold you simply set the animal's status to hold. The endpoint for changing an animal status is
/api/v2/animal/{id}/status
the {id]} is the animal ID you wish to put on hold. The request is a PATCH. An example of the request body is:

The LastUpdateDateTimeUtc property is the date / time the animal was updated, just to make sure that you have the most up to date information of the pet before saving.

To remove a hold you use the same animal status endpoint and you set the animals status status to the previous status it was before applying the hold.  To get the previous status you can either cache this before you apply your hold status, or you can retrieve it from the end point api/v2/animal/statushistory/list?page={page}&pageSize={pageSize} posting with the searchModel of the animalId and then looping through to find the most recent history before the hold history.

How do I get the medical history pdf?

This can be achieved by using the end point:
MedicalHistoryV2
api/v2/animal/medicalhistory/{animalId}

How do I set the address type when processing a license?

To set the location address radio box on the license details screen you can use the AddressDetail property of the license model and set it to “residential” and this will flag the location address as “Owner’s Residential”. If nothing is set for this property then it will default to “other”.

How can we access these icon values from the API

This is a Icon property in the animal entity, its an array of the icons the animal has ticked.

How do I adopt an animal?

Use the following endpoint to adopt an animal:

AdoptionProcessV2 (/api/v2/animal/process/adoption)

See our Resources page for examples of the adoption insert model.

PersonId is the id of the person who is adopting the animal (i.e. the new owner).

StatusId is the id of an adoption status to create in the status history. StatusDateTimeUtc is the value used for the status date.

The Receipt model (for a new receipt) or a ReceiptId (for an existing receipt) is required. Any payments and allocations made for the adoption should be included in the Receipt model or added using the receipt endpoint (ReceiptV2 /api/v2/receipt).

AdoptionCounselorId is the id of a user who is listed as an adoption counselor.

AdoptionFeeId is required if the animal doesn't already have an adoption amount or adoption fee set.

SelectedOptInChoiceIds is an array of ids for each of the choices the person wants to be opted in to. If null then the person will not be opted in to any choice. You can get a list of available opt in choices from LookupListItemV2 /api/v2/person/optinchoice.

How do i select only people that have opted in to a service as part of an adoption?

The endpoint api/v2/person has a person model that includes the property OptInChoices, you would use this to see if a person has opted in to specific external companies. If a company is listed in this array then it means they have opted in. Using the endpoint api/v2/animal/statushistory/list you could filter for adoption statuses and a date range that you are polling for. From this you can then query the animal endpoint or adoption end point for the animal to get the owner and then query the person endpoint for their OptInChoices.

What is an example of saving a person?

Using the /api/v2/person/ PUT endpoint you can use the below an example of the minimum required fields to create a person record:

I’m being blocked by CORS policy. How do I fix?

By default we block all cross origin requests. To get your origin authorised you will need to contact ShelterBuddy support, please provide the ShelterBuddy site you are using and the origin you would like authorised.