Givey API Docs

Introduction

The Givey API conforms to the standards of JSONAPI. As such, URL structure and data is predictable.

We make use of HTTP Status codes in all responses so that you know if a request is successful or not.

For every response, including errors, we return JSON formatted responses.

The Givey API uses versioning with the most up to date version being V4. As a result, all requests to the API must include the version in the URL:

  $ curl https://api.givey.com/v4/

If you wish to test your requests, you can do so with the staging version of the API:

  $ curl https://api-staging.givey.com/v4 \
    -H "Authorization: Bearer ACCESS_TOKEN"

API Endpoint

https://api.givey.com/v4/

Client Libraries

There are currently no client libraries for the Givey API. If you are interested in one, or would like to create one, please contact support@givey.com

Authentication

The Givey API uses access tokens for authentication. An access token is required for every request. In order to generate an access token, please visit Givey Developers.

Our access tokens utilize scopes. When generating an access token, you can request the scopes that you need (such as reading fundraiser data, or creating a donation). These scopes make sure that users only request the data that they need.

The recommended way to authenticate your requests to the Givey API is through the request headers (bearer authentication).

  $ curl https://api.givey.com/v4/charities \
    -H "Authorization: Bearer ACCESS_TOKEN"

Replace ACCESS_TOKEN with your actual access token.

Example request

$ curl https://api.givey.com/v4/charities \
  -H "Authorization: Bearer ACCESS_TOKEN"

Replace ACCESS_TOKEN with your actual access token.

Pagination and ordering

The Givey API uses request arguments to paginate result sets.

If no arguments are passed for pagination, the first page of results will be returned with a default limit set (varies per result set).

All returned result sets include a links object. This object contains links to the next sets in the data.

To order a result set you can use order[attribute] and order[direction].

Example request

$ curl https://api.givey.com/v4/users \
  -H "Authorization: Bearer {access token}" \
  -d page[size]=1 \
  -d page[number]=1 \
  -d order[attribute]="id" \
  -d order[direction]="asc"

Example response

  {
    "data": [
      {}
    ],
    "links": {
      "self": "https://api.givey.com/v4/users?access_token=access_token&page%5Bnumber%5D=1&page%5Bsize%5D=1",
      "first": "https://api.givey.com/v4/users?access_token=access_token&page%5Bnumber%5D=1&page%5Bsize%5D=1",
      "prev": null,
      "next": "https://api.givey.com/v4/users?access_token=access_token&page%5Bnumber%5D=2&page%5Bsize%5D=1",
      "last": "https://api.givey.com/v4/users?access_token=access_token&page%5Bnumber%5D=45798&page%5Bsize%5D=1"
    }
  }

Fundraisers object

A Fundraiser is an entity on Givey which is attached to a Charity or a Project.

Attributes

Id `string`	The unique identifier of the Fundraiser
givey-tag `string`	The Givey Tag (username) of the Fundraiser
name `string`	The name of the Fundraiser
description `string`	The description of the Fundraiser
avatars `object`	An object of different avatar sizes along with their URLs
hero-images `object`	An object of different hero image sizes along with their URLs
twitter-url `string`	The Twitter URL of the Fundraiser
facebook-url `string`	The Facebook URL of the Fundraiser
profile-url `string`	The URL of the Fundraiser on Givey
target `integer`	The target amount the Fundraiser wishes to raise (in pence)
raised `integer`	The amount the Fundraiser has already raised (in pence)
percentage-raised `integer`	The percentage of funds raised compared to the target
created-at `datetime`	The date the Fundraiser was created
ending-at `datetime`	The date the Fundraiser will end (can be null)

Example response

{
  "id": 1,
  "type": "fundraisers",
  "attributes": {
    "givey-tag": "fundraiser-one",
    "name": "Fundraiser one",
    "description": "Description for Fundraiser one",
    "avatars": {
      "tiny": "url_to_avatar",
      "small": "url_to_avatar",
      "medium": "url_to_avatar",
      "large": "url_to_avatar"
    },
    "hero-images": {
      "small": "url_to_avatar",
      "profile": "url_to_avatar",
      "dark": "url_to_avatar"
    },
    "twitter-url": "https://twitter.com/fundraiserone",
    "facebook-url": "https://facebook.com/fundraiser-one",
    "profile-url": "https://givey.com/fundraiser-one",
    "target": 10000,
    "raised": 10000,
    "percentage-raised": 100,
    "created-at": "2018-07-17T09:26:52.688Z",
    "ending-at": "2018-07-17T09:26:52.688Z"
  }
}

GET List all fundraisers

Required scope: fundraisers:read

Retrieves a list of all fundraisers on Givey

Arguments

No arguments

Example request

$ curl https://api.givey.com/v4/fundraisers \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": [
    {
      "id": 1,
      "type": "fundraisers",
      "attributes": {
        "givey-tag": "fundraiser-one",
        "name": "Fundraiser one",
        "description": "Description for Fundraiser one",
        "avatars": {
          "tiny": "url_to_avatar",
          "small": "url_to_avatar",
          "medium": "url_to_avatar",
          "large": "url_to_avatar"
        },
        "hero-images": {
          "small": "url_to_avatar",
          "profile": "url_to_avatar",
          "dark": "url_to_avatar"
        },
        "twitter-url": "https://twitter.com/fundraiserone",
        "facebook-url": "https://facebook.com/fundraiser-one",
        "profile-url": "https://givey.com/fundraiser-one",
        "target": 10000,
        "raised": 10000,
        "percentage-raised": 100,
        "created-at": "2018-07-17T09:26:52.688Z",
        "ending-at": "2018-07-17T09:26:52.688Z"
      }
    }
  ]
}

GET List all fundraisers for a specific charity

Required scope: fundraisers:read

Retrieves a specific fundraiser based on passed arguments

Arguments

charity_id

string

The Id or username of the charity the fundraiser is linked to

Example request

$ curl https://api.givey.com/v4/fundraisers?charity_id=20
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": [
      {
          "id": "1",
          "type": "fundraisers",
          "attributes": {
              "givey-tag": "fundraiser1",
              "name": "Fundraiser 1",
              "description": "<p>Thank you for visiting our Givey page.</p><p>When you make your donation through Givey, the charity receives 100% of the donation.</p>",
              "avatars": {
                  "tiny": "url_to_avatar",
                  "small": "url_to_avatar",
                  "medium": "url_to_avatar",
                  "large": "url_to_avatar"
              },
              "hero-images": {
                  "small": "url_to_avatar",
                  "profile": "url_to_avatar",
                  "dark": "url_to_avatar"
              },
              "twitter-url": "https://twitter.com/",
              "facebook-url": "https://www.facebook.com/",
              "profile-url": "https://www.givey.test/fundraiser1",
              "target": 100000,
              "raised": 0.0,
              "donations-count": 0,
              "percentage-raised": 0,
              "created-at": "2020-02-29T10:36:12.713Z",
              "ending-at": null
          },
          "relationships": {
              "charity": {
                  "data": {
                      "id": "20",
                      "type": "charities"
                  }
              },
              "owner": {
                  "data": {
                      "id": "11314",
                      "type": "users"
                  }
              },
              "admins": {
                  "data": [
                      {
                          "id": "11314",
                          "type": "users"
                      }
                  ]
              }
          }
      }
  ],
}

GET List a specific fundraiser

Required scope: fundraisers:read

Retrieves a list of fundraisers based on passed arguments

Arguments

string

The Id or username of the fundraiser

Example request

$ curl https://api.givey.com/v4/fundraisers/1 \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": {
    "id": 1,
    "type": "fundraisers",
    "attributes": {
      "givey-tag": "fundraiser-one",
      "name": "Fundraiser one",
      "description": "Description for Fundraiser one",
      "avatars": {
        "tiny": "url_to_avatar",
        "small": "url_to_avatar",
        "medium": "url_to_avatar",
        "large": "url_to_avatar"
      },
      "hero-images": {
        "small": "url_to_avatar",
        "profile": "url_to_avatar",
        "dark": "url_to_avatar"
      },
      "twitter-url": "https://twitter.com/fundraiserone",
      "facebook-url": "https://facebook.com/fundraiser-one",
      "profile-url": "https://givey.com/fundraiser-one",
      "target": 10000,
      "raised": 10000,
      "percentage-raised": 100,
      "created-at": "2018-07-17T09:26:52.688Z",
      "ending-at": "2018-07-17T09:26:52.688Z"
    }
  }
}

post Create a fundraiser

Required scope: fundraisers:create

Creates a fundraiser based on passed arguments

Arguments

charity_id `string`	The Id or username of the Charity this fundraiser is for
name `string`	The name of the fundraiser
description `string`	The description of the fundraiser
target `integer`	The target to be raised for the fundraiser (in pence)
offline_amount `integer`	The amount already raised from donations (in pence)
ending_at `datetime`	The date that this fundraiser will end

Example request

$ curl https://api.givey.com/v4/fundraisers \
  -H "Authorization: Bearer {access token}" \
  -d fundraisers[charity_id]=1 \
  -d fundraisers[name]="Fundraiser one" \
  -d fundraisers[description]="The description" \
  -d fundraisers[target]=10000 \
  -d fundraisers[offline_amount]=1000 \
  -d fundraisers[ending_at]="2019-12-25"

Example response

{
  "data": {
    "id": 1,
    "type": "fundraisers",
    "attributes": {
      "givey-tag": "fundraiser-one",
      "name": "Fundraiser one",
      "description": "Description for Fundraiser one",
      "avatars": {
        "tiny": "url_to_avatar",
        "small": "url_to_avatar",
        "medium": "url_to_avatar",
        "large": "url_to_avatar"
      },
      "hero-images": {
        "small": "url_to_avatar",
        "profile": "url_to_avatar",
        "dark": "url_to_avatar"
      },
      "twitter-url": "https://twitter.com/fundraiserone",
      "facebook-url": "https://facebook.com/fundraiser-one",
      "profile-url": "https://givey.com/fundraiser-one",
      "target": 10000,
      "raised": 10000,
      "percentage-raised": 100,
      "created-at": "2018-07-17T09:26:52.688Z",
      "ending-at": "2018-07-17T09:26:52.688Z"
    }
  }
}

Donations object

Attributes

Id `string`	The unique identifier of the Donation
activity-id `string`	A unique identifier used on Givey
amount `integer`	The amount the donation was for (in pence)
comments-count `integer`	The amount of comments on this donation
content-text `string`	The message that was left with this donation
matched-total `integer`	The amount that was matched by the business (in pence)
processed `boolean`	Whether or not the donation has been processed by our payment provider
status `string`	The donation status. Can be one of failed, pending or complete
created-at `datetime`	The date the Fundraiser was created
is-anonymous `boolean`	Whether or not the donation was made anonymously

Example response

{
  "id": 1,
  "type": "donations",
  "attributes": {
    "activity-id": "MK1234HFWEI",
    "amount": 1000,
    "comments-count": 12,
    "content-text": "Well done",
    "matched-total": 500,
    "processed": true,
    "status": "complete",
    "created-at": "2018-07-17T09:26:52.688Z",
    "is-anonymous": true,
  }
}

GET List all donations

Required scope: donations:read

Retrieves a list of all donations on Givey

Arguments

No arguments

Example request

$ curl https://api.givey.com/v4/donations \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": [
    {
      "id": 1,
      "type": "donations",
      "attributes": {
        "activity-id": "MK1234HFWEI",
        "amount": 1000,
        "comments-count": 12,
        "content-text": "Well done",
        "matched-total": 500,
        "processed": true,
        "status": "complete",
        "created-at": "2018-07-17T09:26:52.688Z",
        "is-anonymous": true,
      }
    }
  ]
}

GET List a specific donation

Required scope: donations:read

Retrieves a specific donation based on passed arguments

Arguments

No arguments

Example request

$ curl https://api.givey.com/v4/donations/123 \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": {
    "id": 123,
    "type": "donations",
    "attributes": {
      "activity-id": "MK1234HFWEI",
      "amount": 1000,
      "comments-count": 12,
      "content-text": "Well done",
      "matched-total": 500,
      "processed": true,
      "status": "complete",
      "created-at": "2018-07-17T09:26:52.688Z",
      "is-anonymous": true,
    }
  }
}

Users object

Attributes

Id `string`	The unique identifier of the user
givey-tag `string`	The Givey Tag (username) of the user
name `string`	The name of the user
first_name `string`	The first name of the user
last_name `string`	The last name of the user
avatars `object`	An object of different avatar sizes along with their URLs
hero-images `object`	An object of different hero image sizes along with their URLs
donations-count `integer`	The amount of donations this user has made
following-count `integer`	The amount of users this user is following
followers-count `integer`	The amount of users that follow this user
created-at `datetime`	The date the Fundraiser was created

Example response

{
  "id": "1",
  "type": "users",
  "attributes": {
  "givey-tag": "user-one",
  "name": "User one",
  "first-name": "User",
  "last-name": "one",
  "avatars": {
    "tiny": "url_to_avatar",
    "small": "url_to_avatar",
    "medium": "url_to_avatar",
    "large": "url_to_avatar"
  },
  "hero-images": {
    "small": "url_to_avatar",
    "profile": "url_to_avatar",
    "dark": "url_to_avatar"
  },
  "donations-count": 55,
  "followers-count": 21,
  "following-count": 14,
  "matching": {
    "enabled": true,
    "percent": 50
  },
  "created-at": "2018-08-14T08:41:28.801Z"
}

GET List all users

Required scope: users:read

Retrieves a list of all users on Givey

Arguments

No arguments

Example request

$ curl https://api.givey.com/v4/users \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "users",
      "attributes": {
      "givey-tag": "user-one",
      "name": "User one",
      "first-name": "User",
      "last-name": "one",
      "avatars": {
        "tiny": "url_to_avatar",
        "small": "url_to_avatar",
        "medium": "url_to_avatar",
        "large": "url_to_avatar"
      },
      "hero-images": {
        "small": "url_to_avatar",
        "profile": "url_to_avatar",
        "dark": "url_to_avatar"
      },
      "donations-count": 55,
      "followers-count": 21,
      "following-count": 14,
      "matching": {
        "enabled": true,
        "percent": 50
      },
      "created-at": "2018-08-14T08:41:28.801Z"
    }
  ]
}

GET List a specific user

Required scope: users:read

Retrieves a specific user

Arguments

string

The Id or username of the user

Example request

$ curl https://api.givey.com/v4/users/1 \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": {
    "id": "1",
    "type": "users",
    "attributes": {
    "givey-tag": "user-one",
    "name": "User one",
    "first-name": "User",
    "last-name": "one",
    "avatars": {
      "tiny": "url_to_avatar",
      "small": "url_to_avatar",
      "medium": "url_to_avatar",
      "large": "url_to_avatar"
    },
    "hero-images": {
      "small": "url_to_avatar",
      "profile": "url_to_avatar",
      "dark": "url_to_avatar"
    },
    "donations-count": 55,
    "followers-count": 21,
    "following-count": 14,
    "matching": {
      "enabled": true,
      "percent": 50
    },
    "created-at": "2018-08-14T08:41:28.801Z"
  }
}

post Create a user

Required scope: users:create

Creates a user based on passed arguments

Arguments

first_name `string`	The first name of the user
last_name `string`	The last name of the user
email `string`	The email address of the user
password `string`	The password of the user

Example request

$ curl https://api.givey.com/v4/users \
  -H "Authorization: Bearer {access token}" \
  -d users[first_name]="User" \
  -d users[last_name]="one" \
  -d users[email]="userone@example.com" \
  -d users[password]="$ABC123!"

Example response

{
  "data": {
    "id": "1",
    "type": "users",
    "attributes": {
    "givey-tag": "user-one",
    "name": "User one",
    "first-name": "User",
    "last-name": "one",
    "avatars": {
      "tiny": "url_to_avatar",
      "small": "url_to_avatar",
      "medium": "url_to_avatar",
      "large": "url_to_avatar"
    },
    "hero-images": {
      "small": "url_to_avatar",
      "profile": "url_to_avatar",
      "dark": "url_to_avatar"
    },
    "donations-count": 55,
    "followers-count": 21,
    "following-count": 14,
    "matching": {
      "enabled": true,
      "percent": 50
    },
    "created-at": "2018-08-14T08:41:28.801Z"
  }
}

Charities object

A Charity is an entity on Givey that can have many Fundraisers. They can be donated to directly, or via one of it's fundraisers. Projects on Givey are like Charities and the object is exactly the same. A Project is a not-for-profit organisation which is not registered with the Charity Commission.

Attributes

Id `string`	The unique identifier of the Charity
givey-tag `string`	The Givey Tag (username) of the Charity
name `string`	The name of the Charity
description `string`	The description of the Charity
avatars `object`	An object of different avatar sizes along with their URLs
hero-images `object`	An object of different hero image sizes along with their URLs
website-url `string`	The URL of the Charity's website
twitter-url `string`	The Twitter URL of the Charity
facebook-url `string`	The Facebook URL of the Charity
profile-url `string`	The URL of the Charity on Givey
donations-count `integer`	The amount of donations the Charity has
following-count `integer`	The amount of users this Charity is following
followers-count `integer`	The amount of users that follow this Charity
raised `integer`	The amount that this Charity has raised (in pence)
billing-enabled? `boolean`	Whether or not this Charity is enabled on Givey
created-at `datetime`	The date the Charity was created

Example response

{
  "id": 1,
  "type": "charities",
  "attributes": {
    "givey-tag": "charity-one",
    "name": "Charity one",
    "description": "Description for Charity one",
    "avatars": {
      "tiny": "url_to_avatar",
      "small": "url_to_avatar",
      "medium": "url_to_avatar",
      "large": "url_to_avatar"
    },
    "hero-images": {
      "small": "url_to_avatar",
      "profile": "url_to_avatar",
      "dark": "url_to_avatar"
    },
    "website-url": "https://charityone.com",
    "twitter-url": "https://twitter.com/fundraiserone",
    "facebook-url": "https://facebook.com/fundraiser-one",
    "profile-url": "https://givey.com/charity-one",
    "donations-count": 123,
    "following-count": 11,
    "followers-count": 22,
    "raised": 10000,
    "billing-enabled?": true,
    "created-at": "2018-07-17T09:26:52.688Z"
  }
}

GET List all charities

Required scope: charities:read

Retrieves a list of all charities on Givey

Arguments

No arguments

Example request

$ curl https://api.givey.com/v4/charities \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": [
    {
      "id": 1,
      "type": "charities",
      "attributes": {
        "givey-tag": "charity-one",
        "name": "Charity one",
        "description": "Description for Charity one",
        "avatars": {
          "tiny": "url_to_avatar",
          "small": "url_to_avatar",
          "medium": "url_to_avatar",
          "large": "url_to_avatar"
        },
        "hero-images": {
          "small": "url_to_avatar",
          "profile": "url_to_avatar",
          "dark": "url_to_avatar"
        },
        "website-url": "https://www.charityone.com",
        "twitter-url": "https://twitter.com/charityone",
        "facebook-url": "https://facebook.com/charity-one",
        "profile-url": "https://givey.com/charity-one",
        "donations-count": 123,
        "following-count": 11,
        "followers-count": 22,
        "raised": 10000,
        "billing-enabled?": true,
        "created-at": "2018-07-17T09:26:52.688Z"
      }
    }
  ]
}

GET List a specific charity

Required scope: charities:read

Retrieves a specific charity based on passed arguments

Arguments

string

The Id or username of the charity

Example request

$ curl https://api.givey.com/v4/charities/1 \
  -H "Authorization: Bearer {access token}"

Example response

{
  "data": {
    "id": 1,
    "type": "charities",
    "attributes": {
      "givey-tag": "charity-one",
      "name": "Charity one",
      "description": "Description for Charity one",
      "avatars": {
        "tiny": "url_to_avatar",
        "small": "url_to_avatar",
        "medium": "url_to_avatar",
        "large": "url_to_avatar"
      },
      "hero-images": {
        "small": "url_to_avatar",
        "profile": "url_to_avatar",
        "dark": "url_to_avatar"
      },
      "website-url": "https://www.charityone.com",
      "twitter-url": "https://twitter.com/charityone",
      "facebook-url": "https://facebook.com/charity-one",
      "profile-url": "https://givey.com/charity-one",
      "donations-count": 123,
      "following-count": 11,
      "followers-count": 22,
      "raised": 10000,
      "billing-enabled?": true,
      "created-at": "2018-07-17T09:26:52.688Z"
    }
  }
}