Give API

Our REST API provides a way to retrieve information about objects and activity on Give. The current version of the Give API is v1.0.

If you have feedback or questions, send us an email or tweet to us @iamgivingto. Usage of our API entails agreement to our Terms of Service and Privacy Policy.

Table of Contents


Version API

Description

Returns the current API version. Warnings will include deprecation notices.

Endpoint

https://www.give.to/api/version

Parameters

The Version API does not take any parameters.

Return Values

All requests to the Version API return well-formed JSON with the following keys.

Key Values
ok
true
or
false
version
A string containing the version number.
warnings
An array containing 0 or more warning messages.
errors
An array containing 0 or more error messages.

Examples

URL Description Demo
https://www.give.to/api/version
Retrieve current API version. Try It

Gifts API

Description

Returns information about Gifts, including Artist and Patron information.

Endpoint

https://www.give.to/api/1.0/gifts

Parameters

All parameters are optional. Ordering is by creation date (most recent first).

Parameter Values Usage
limit
1
to
100
(default 10)
Limit the number of Gifts returned
verified
true
or
false
Limit Gifts to only verified or unverified Artists
gift_ids
array of 1 or more integers Retrieve 1 or more Gifts by ID
artist_id
integer Retrieve Gifts by Artist ID
(Takes precedence over
artist_name
if present)
artist_name
string Retrieve Gifts by Artist Name
patron_id
integer Retrieve Gifts by Patron ID

Return Values

All requests to the Gifts API return well-formed JSON with the following keys.

Key Values
ok
true
or
false
gifts
An array containing 0 or more Gifts. See the format of a Gift object.
warnings
An array containing 0 or more warning messages.
errors
An array containing 0 or more error messages.
params
An object containing the request parameters, as well as the API
version
number.

Examples

URL Description Demo
https://www.give.to/api/1.0/gifts
Retrieve 10 Gifts. Try It
https://www.give.to/api/1.0/gifts?limit=5
Retrieve 5 Gifts. Try It
https://www.give.to/api/1.0/gifts?verified=true
Retrieve 10 Gifts to Verified Artists. Try It
https://www.give.to/api/1.0/gifts?artist_name=Andy Shauf
Retrieve 10 Gifts to Andy Shauf. Try It
https://www.give.to/api/1.0/gifts?limit=3&patron_id=1
Retrieve 3 Gifts from the Patron with ID 1. Try It

Artists API

Description

Returns information about Artists. Ordering is by creation date (most recent first), unless the artist_name parameter is set.

Endpoint

https://www.give.to/api/1.0/artists

Parameters

All parameters are optional.

Parameter Values Usage
limit
1
to
100
(default 10)
Limit the number of Artists returned
verified
true
or
false
Limit Gifts to only verified or unverified Artists.
Sorts by verification date (most recent first) if
true
artist_ids
comma-separated list of 1 or more integers Retrieve 1 or more Artists by ID
artist_name
string Retrieve Artists by name.
Sorts results by best name match.

Return Values

All requests to the Artists API return well-formed JSON with the following keys.

Key Values
ok
true
or
false
artists
An array containing 0 or more Artists. See the format of an Artist object.
warnings
An array containing 0 or more warning messages.
errors
An array containing 0 or more error messages.
params
An object containing the request parameters, as well as the API
version
number.

Examples

URL Description Demo
https://www.give.to/api/1.0/artists
Retrieve 10 Artists. Try It
https://www.give.to/api/1.0/artists?limit=5
Retrieve 5 Artists. Try It
https://www.give.to/api/1.0/artists?verified=true
Retrieve 10 Verified Artists. Try It
https://www.give.to/api/1.0/artists?artist_name=Gonzales
Retrieve 10 Artists matching "Gonzales". Try It
https://www.give.to/api/1.0/artists?artist_ids=1681693,302423
Retrieve Artists with IDs 1681693 and 302423. Try It

Object Reference

Description

These are the properties you can expect for objects returned by the API.

Gift Objects

Key Values Usage
id
integer ID of Gift
amount
1
to
1000
Amount of Gift (in $CAD)
url
string URL of Gift
message
text A message from the Patron to the Artist (optional)
created_at
datetime Datetime when Gift was created
paid
boolean True if Gift has been paid to Artist
artist
object Information about the Artist
See the format of an Artist object
patron
object Information about the Patron
See the format of a Patron object

Artist Objects

Key Values Usage
id
integer ID of Artist
name
string Name of Artist
url
string URL of Artist profile
image
string URL of primary Artist image (optional)
verified
boolean True if Artist has been Verified

Patron Objects

Key Values Usage
id
integer ID of Patron
name
string Name of Patron
url
string URL of Patron profile (may be blank if Patron has not authenticated)
image
string URL of Patron profile image