GoodCoin
GoodCoin follows the emerging JSON API specification. JSON API is an attempt to formalize similar ad hoc client-server interfaces that use JSON as an interchange format. JSON API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability. These is a wide selection of client implementations for the JSON API format which can fasten your implementation.
The GoodCoin API responds in JSON format. The MIME type of requests and responses must be application/vnd.api+json.
The object returned by the API could contain the following top level members:
data– a single resource or a collection of resourcesmeta– meta information about the response object, such as paginationerrors– array of error objectslinks- collection of links related to the resource(s) represented (can typically be pages links for collections, relationships links for single resource responses)included- collection of resources included in the response along the main resource or collection
At the resource level the the resource object returned by the API could contain the following members:
id- unique identifier of the resourcetype- type of the resourceattributes- attributes of the resource
When performing an API call against the GoodCoin API we need to authenticate you and identify the customer (ex: Financial Institution) in the context the API call is being made. Authentication for the GoodCoin API is done using JSON Web Tokens (JWT) - read more here and here.
The JWT will be generate by you, signed with the API Secret (you will receive that from your Account Representative) and sent base64 encoded in the HTTP authentication headers.
Authorization: JWT <JWT>
When generating the JWT you need to use the following claims:
iss(Issuer) - this must be your application name; if not using GoodCoin standard customer identifier you’ll need to agree with GoodCoin on a value for this field.sub(Subject) - this is the field that identifies the GoodCoin customer (ex: Financial Institution) in the context the API call is being made.exp(Expiration) - (optional) - if provided the API won’t accept the API request after this timetyp(Type) - must beJWTalg(Algorithm) - must beHS256- the encryption algorithm will be HMAC SHA-256
Note: if the alg claim contains anything else except the allowed values we will reject the API request.
When the api integration is used with HMAC enabled the following claims are required when generating the token:
sig(Signature) -SHA1-HMACof the requestnce(Nonce) - an unique value that identifies this request used to protect against replay attacks.
The signature (sig) is generated by joining the following values in the exact order and base64 encoding the SHA1 digest of the resulting content.
secret_key- the secret key that has been received from the Account Representative.http_method- the uppercasehttp methodused to make this request ex: (POST, GET)nonce- the value of the nce field send in the payload.request_host- the value of the host headerrequest_uri- the value of the path of uri of the request including the query string (ex: /v1/cycles/charities?filter[market_identifiers]=1)body- the content of the request body or an empty string if the request doesn’t have a body.
The delimiter used for joining is an empty space (’’ character). The base64 encoding method that should be used is the URL and Filename Safe Alphabet described by rfc4648 here
Example: An JWT issues by my-app in the context of customer 42 and signed with the secret very-secret will have the claims:
# header
{
"alg": "HS256",
"typ": "JWT"
}
# payload
{
"iss": "my-app",
"sub": "42"
}
The JWT will be sent to the API in the HTTP header:
Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImlzcyI6Im15LWFwcCIsInN1YiI6IjQyIn0.e30.W1IA0bWo39AkyzvPswwbvxgvzAqlpdYHrvh0Tr9bAeA
Acceptable HTTP Verbs
GETUsed for retrieving resourcesPOSTUsed for creating new resourcesPATCHUsed for updating select attributes for a resourceDELETEUsed for deleting resources
HTTP Response Codes
200- OK400- Bad request (Usually for malformed requests)401- Unauthorized403- Forbidden404- Not found422- Not Acceptable (Usually when the data sent to the API to create/update a resource didn’t passed the validation on the server)500- Internal server error
See the format and examples of responses in the Responses section.
Customers are most commonly financial institutions offering the charitable giving solution to their users (cardholders or account holders) through a GoodCoin hosted web interface or delivered via custom solutions using the API.
Customers identify themselves during the auth process (via the Subject field) to associate user and donation requests with the appropriate GoodCoin customer account. Customer record information can also be requested through the Customer Resource.
Authentication
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
Customer name
User last name
If the Customer wants to restrict donations only for some Cards
If customer restrict Cards this will be a list of allowed BIN ranges
[]GET https://api.goodcoins.io/v1/customer HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "customer",
"attributes": {
"name": "Credit Union 1",
"goodcoins_url": "https://credit-union.goodcoins.io",
"bin_restriction": true,
"bin_ranges": [
"374660",
"374661"
]
}
}
}GET https://api.goodcoins.io/v1/customer HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/customer HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}This section describes the API operations that can be performed on the Charity and Charity Category resources.
{id}{id}Authentication
Get a list of charities. Optionally you can filter, sort and do custom pagination of the result.
Request parameters
Filter results by keywords
Comma separated values of category IDs
Filter results by US state
Filter results by US city
Filter results by Postal Code (it requires the radius filter)
Filter results by GPS (latitude, longitude) coordinates (it requires the radius filter)
When searching by Postal Code or GPS coordinates limit the results within this radius
Sort results by
Sort by relevancy (default)
Sort by name asending
Sort by name descending
Sort by revenue (assets) ascending
Sort by revenue (assets) descending
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
Category name
Total number of resources in the collection
Total number of pages
Current page number
API link to the next page
API link to the last page
API link to the first page
API link to the previous page
GET https://api.goodcoins.io/v1/charities?page[number]=1&page[size]=10&filter[zip]=90210&filter[radius]=25&sort=name HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
"data": [
{
"type": "charity_category",
"id": "1"
}
]
}
}
},
{
"id": 2,
"type": "charity",
"attributes": {
"name": "American Red Cross",
"description": "The American Red Cross prevents and alleviates human suffering in the face of emergencies by mobilizing the power of volunteers and the generosity of donors.",
"ein": "81-2321523",
"cover_image_url": "http://static.goodcoins.io/covers/81-2321523.jpg",
"logo_url": "https://static.goodcoins.io/logos/81-2321523.png",
"address": "431 18th St NW",
"city": "Washington",
"region": "DC",
"zip": "20006",
"country": "US",
"website_url": "http://www.redcross.org",
"facebook_url": "https://www.facebook.com/redcross",
"linkedin_url": "https://linkedin.com/company/American-Red-Cross",
"twitter_url": "https://twitter.com/redcross",
"instagram_url": "https://www.instagram.com/americanredcross",
"year_founded": "1881",
"revenue_total": 2676037116
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
},
{
"id": 2,
"type": "charity_category"
}
]
}
}
}
],
"included": [
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
},
{
"id": 2,
"type": "charity_category",
"attributes": {
"name": "Benefit to Society"
}
}
],
"meta": {
"total_records": 37,
"total_pages": 4,
"page": "1"
},
"links": {
"next": "https://api.goodcoins.io/v1/charities?page[number]=2&page[size]=10&filter[zip]=90210&filter[radius]=25&sort=name",
"last": "https://api.goodcoins.io/v1/charities?page[number]=4&page[size]=10&filter[zip]=90210&filter[radius]=25&sort=name",
"first": "https://api.goodcoins.io/v1/charities?page[number]=1&page[size]=10&filter[zip]=90210&filter[radius]=25&sort=name",
"prev": null
}
}GET https://api.goodcoins.io/v1/charities HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Get a Charity by ID
Path variables
Charity ID
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
Category name
GET https://api.goodcoins.io/v1/charities/1 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"links": {
"self": "https://api.goodcoins.io/v1/charities/1"
},
"relationships": {
"categories": {
"data": [
{
"type": "charity_category",
"id": "1"
}
]
}
}
},
"included": [
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}
]
}GET https://api.goodcoins.io/v1/charities/42 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/charities/1 HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/1 HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}Authentication
Get a list of charity categories. Optionally you can sort and do custom pagination of the result.
Request parameters
Sort results by
Sort by name asending (default)
Sort by name descending
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
Category name
Total number of resources in the collection
Total number of pages
Current page number
API link to the next page
API link to the last page
API link to the first page
API link to the previous page
GET https://api.goodcoins.io/v1/charity/categories HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
},
{
"id": 2,
"type": "charity_category",
"attributes": {
"name": "Benefit to Society"
}
}
],
"meta": {
"total_records": 37,
"total_pages": 4,
"page": "1"
},
"links": {
"next": "https://api.goodcoins.io/v1/charity_categories?page[number]=2",
"last": "https://api.goodcoins.io/v1/charity_categories?page[number]=4",
"first": "https://api.goodcoins.io/v1/charity_categories",
"prev": null
}
}GET https://api.goodcoins.io/v1/charity/categories HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charity/categories HTTP/1.1
Authorization: JWT FORBIDDEN-VALID-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Get a Charity Category by ID.
Path variables
Charity Category ID
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
Category name
GET https://api.goodcoins.io/v1/charities/categories/1 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}
}GET https://api.goodcoins.io/v1/charities/categories/42 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/charities/categories/1 HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/categories/1 HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}The Cycles API is intended to be used for programs that requries control over the data that is provided to a donor or brake down the charities in groups of interests which are called markets.
The charities can be grouped into
- cycles which are active a ceritan period of time.
- markets in order to brake down the charities in groups of interest (activity domains, geographic areas, etc.)
{cycle_charity_id}/donationsAuthentication
Get a list of Cycles.
You can retreive only the active cycles at a given moment in time by providing a date-time value to the active-on filter.
Note: active_on filter is optional and if unspecified current date is used for filtering.
Request parameters
Filter cycles for ones active on the specified date. Incoming date is expected to be in UTC timezone. If not present current date is used.
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
The cycle name
The cycle custom identifier
The cycle year
The cycle start date
The cycle end date
The cycle creation date
GET https://api.goodcoins.io/v1/charities/cycles?filter[active_on]=2018-05-16T04:00:00.000Z&page[number]=1&page[size]=10 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "cycle",
"attributes": {
"name": "Cycle #1",
"identifier": "cycle-1",
"year": "2020",
"start_date": "2020-03-01T03:00:00.000Z",
"end_date": "2020-05-01T03:00:00.000Z",
"created_at": "2018-02-15T03:00:00.000Z"
}
}
]
}GET https://api.goodcoins.io/v1/charities/cycles HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"status": "400",
"code": "invalid",
"title": "Could not properly parse the data received",
"detail": "JSON parse error - Expecting property name at line 1 column 2 (char 1)."
}
]
}GET https://api.goodcoins.io/v1/charities/cycles HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/cycles HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/cycles HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/charities/cycles HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/active_on",
"parameter": "active_on"
},
"title": "Value must be a valid date-time",
"detail": "You must specify a valid date-time"
}
]
}Authentication
Get the details of the cycles that are active on a given date.
The response will include all the cycles that are active and for each
of the cycles the details of the market and what charities are present will be returned.
Note: active_on filter is optional and if unspecified current date is used for filtering.
Note: market_identifiers filter can be used to restrict the result only to the markets of interest. The identifiers correspond with cycle_market.identifier
Request parameters
Filter for active cycle on the specified date. Incoming date is expected to be in UTC timezone. If not present current date is used.
Filter for specified markets. Coma separated values. Identifiers’s corresponding with CycleMarket#identifier
Zip code that will be rezolved in to a set market(s). Only 5 digits zip codes are supported (there is no area code support).
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
The cycle name
The cycle custom identifier
The cycle year
The cycle start date
The cycle end date
The cycle creation date
Market id
Market type
Market id
Market type
Market name
Market size
Market Identifier
Market creation date
Market goal
Current goal progress, the sum of donations for this market in this cycle
The number of streches achieved
The amount of donations in the last strech
Cycle Charity id
Cycle Charity type
Resource identifier
Resource type
Global unique identfier for this charity
Charity name
Charity description
Charity EIN
Charity website url
Charity logo url with support for different screen densities
The congratulation message that the charity is providing to the donnors after a donation has been made
Street of the regitered charity
Region/state of the registered charity
City of the regitered charity
Zip Code of the regitered charity
The goal set for the charity
Current goal progress, the sum of donations for this market in this cycle.
The number of streches achieved
The amount of donations in the last strech
This charity has been marked as beeing a national one.
The total number of donations that have been received by this cause.
GET https://api.goodcoins.io/v1/cycles/charities HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 37,
"type": "cycle",
"attributes": {
"name": "Cycle #1",
"identifier": "cycle-1",
"year": "2020",
"start_date": "2020-03-01",
"end_date": "2020-05-01",
"created_at": "2018-02-15T03:00:00.000Z"
},
"relationships": {
"markets": {
"data": [
{
"id": 1,
"type": "cycle_market"
}
]
}
}
}
],
"included": [
{
"id": 1,
"type": "cycle_market",
"attributes": {
"name": "Market #1",
"size": "XS",
"identifier": "Market custom identifier",
"created_at": "2020-05-01T00:00:00.000Z",
"goal_amount": 100.13,
"goal_progress": 99.13,
"goal_streches": 5,
"goal_strech_progress": 400,
"donations_count": 10
},
"relationships": {
"cycle_charities": {
"data": [
{
"id": 42,
"type": "cycle_charity"
}
]
}
}
},
{
"id": 42,
"type": "cycle_charity",
"attributes": {
"charity_id": "1",
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"website_url": "http://www.unicefusa.org",
"logo_url": {
"1.0x": "https://res.cloudinary.com/inpact/image/fetch/w_120,h_120,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"1.5x": "https://res.cloudinary.com/inpact/image/fetch/w_180,h_180,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"2.0x": "https://res.cloudinary.com/inpact/image/fetch/w_240,h_240,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"3.0x": "https://res.cloudinary.com/inpact/image/fetch/w_360,h_360,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"4.0x": "https://res.cloudinary.com/inpact/image/fetch/w_480,h_480,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"5.0x": "https://res.cloudinary.com/inpact/image/fetch/w_600,h_600,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png"
},
"cover_image_url": {
"1.0x": "https://res.cloudinary.com/inpact/image/fetch/w_384,h_216,c_scale,g_center,d_default_logo.png/https%3A%2F%2Fstatic.goodcoins.io%2Fdefault-cover.jpg",
"1.5x": "https://res.cloudinary.com/inpact/image/fetch/w_576,h_324,c_scale,g_center,d_default_logo.png/https%3A%2F%2Fstatic.goodcoins.io%2Fdefault-cover.jpg",
"2.0x": "https://res.cloudinary.com/inpact/image/fetch/w_768,h_432,c_scale,g_center,d_default_logo.png/https%3A%2F%2Fstatic.goodcoins.io%2Fdefault-cover.jpg",
"3.0x": "https://res.cloudinary.com/inpact/image/fetch/w_1152,h_648,c_scale,g_center,d_default_logo.png/https%3A%2F%2Fstatic.goodcoins.io%2Fdefault-cover.jpg",
"4.0x": "https://res.cloudinary.com/inpact/image/fetch/w_1536,h_864,c_scale,g_center,d_default_logo.png/https%3A%2F%2Fstatic.goodcoins.io%2Fdefault-cover.jpg",
"5.0x": "https://res.cloudinary.com/inpact/image/fetch/w_1920,h_1080,c_scale,g_center,d_default_logo.png/https%3A%2F%2Fstatic.goodcoins.io%2Fdefault-cover.jpg""
},
"thank_you_message": "Thank you for the donation.",
"call_to_action": "With this donation we'll make a better world",
"street_address": "",
"region": "",
"city": "",
"zip": "",
"goal_amount": 100,
"goal_progress": 81,
"goal_streches": 1,
"goal_strech_progress": 81,
"national": false,
"donations_count": 10
}
}
]
}GET https://api.goodcoins.io/v1/charities/cycle HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"status": "400",
"code": "invalid",
"title": "Could not properly parse the data received",
"detail": "JSON parse error - Expecting property name at line 1 column 2 (char 1)."
}
]
}GET https://api.goodcoins.io/v1/charities/cycle HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/cycle HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/cycle HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/charities/cycle HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/active_on",
"parameter": "active_on"
},
"title": "Value must be a date-time",
"detail": "You must specify a valid date-time"
}
]
}Authentication
Get a list of markets for a cycle.
Note: active_on filter is optional and if unspecified current date is used for filtering.
Request parameters
Filter for active cycle on the specified date. Incoming date is expected to be in UTC timezone. If not present current date is used.
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
Body
Market id
Market type
Market name
Market size
Market Identifier
The amount of donations that this the goal for this market
Total amount of donations made on this market in a cycle
The number of streches achieved
The amount of donations in the last strech
Market creation date
The total number of donations that have been made in this market
GET https://api.goodcoins.io/v1/cycles/markets HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "cycle_market",
"attributes": {
"name": "Market #1",
"size": "XS",
"identifier": "Market custom identifier",
"goal_amount": 10000,
"goal_progress": 5000,
"goal_streches": 5,
"goal_strech_progress": 400,
"created_at": "2020-05-01T00:00:00.000Z"
}
}
]
}GET https://api.goodcoins.io/v1/charities/cycle/markets HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"status": "400",
"code": "invalid",
"title": "Could not properly parse the data received",
"detail": "JSON parse error - Expecting property name at line 1 column 2 (char 1)."
}
]
}GET https://api.goodcoins.io/v1/charities/cycle/markets HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/cycle/markets HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/charities/cycle/markets HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/charities/cycle/markets HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/active_on",
"parameter": "active_on"
},
"title": "Value must be a date-time",
"detail": "You must specify a valid date-time"
}
]
}{cycle_charity_id}/donationsAuthentication
Create a new donation associated with a cycle charity.
Path variables
Cycle Charity ID
Request headers
Authorization header
Request body
Donation amount in client’s currency, by default the amount is exchanged in USD at rate of 1
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Include a note with the donation
The date when a transaction that triggered the donation occurred and that can be reconciled using the external_identifier.
Rate for exchanging the amount in client’s currency. Required - when client has variable exchange rate, Ignored - when client has fixed exchange rate
Responses
Body
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Donation amount in client’s currency
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
Resource identifier
Resource type
Global unique identfier for this charity
Charity name
Charity description
Charity EIN
Charity website url
Charity logo url with support for different screen densities
The congratulation message that the charity is providing to the donnors after a donation has been made
Street of the regitered charity
Region/state of the registered charity
City of the regitered charity
Zip Code of the regitered charity
The goal set for the charity
Current goal progress, the sum of donations for this market in this cycle.
The number of streches achieved
The amount of donations in the last strech
This charity has been marked as beeing a national one.
The total number of donations that have been received by this cause.
POST https://api.goodcoins.io/v1/cycles/charities/{cycle_charity_id}/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "cycle_donation",
"attributes": {
"amount": 1,
"external_identifier": "1",
"external_user_identifier": "0c6d1cb691dfb86b",
"note": "",
"reference_date": "2018-05-16T04:00:00.000Z",
"exchange_currency": 0.1
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "94182444-b1cc-11e8-9643-eb44a3760e11",
"type": "cycle_donation",
"attributes": {
"external_identifier": "1",
"external_user_identifier": "0c6d1cb691dfb86b",
"amount": 333.33,
"reference_date": "2018-05-16T03:15:34.000Z",
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "cycle_charity"
}
}
}
},
"included": [
{
"id": 1,
"type": "cycle_charity",
"attributes": {
"charity_id": 1,
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"logo_url": {
"1.0x": "https://res.cloudinary.com/inpact/image/fetch/w_205,h_205,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"1.5x": "https://res.cloudinary.com/inpact/image/fetch/w_308,h_308,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"2.0x": "https://res.cloudinary.com/inpact/image/fetch/w_410,h_410,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"3.0x": "https://res.cloudinary.com/inpact/image/fetch/w_615,h_615,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"4.0x": "https://res.cloudinary.com/inpact/image/fetch/w_820,h_820,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"5.0x": "https://res.cloudinary.com/inpact/image/fetch/w_1024,h_1024,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png"
},
"website_url": "http://www.unicefusa.org",
"call_to_action": "",
"thank_you_message": "Thank you for the donation."
}
}
]
}POST https://api.goodcoins.io/v1/charities/1/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"amount": null,
"external_identifier": "1"
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/amount",
},
"title": "Value cannot be empty",
"detail": "You must specify an amount in order to create a donation"
}
]
}POST https://api.goodcoins.io/v1/charities/1/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT INVALID-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"amount": 1,
"external_identifier": "1"
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}POST https://api.goodcoins.io/v1/charities/1/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"amount": 1,
"external_identifier": "1"
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}Authentication
Get a list of donations.
Note: market_identifiers filter can be used to restrict the result only to the markets of interest. The identifiers correspond with identifier attribute from cycle_market.
Request parameters
Comma separated values of Cycle Charities IDs. The id attribute from the cycle_charity type
Comma separated values of Charity IDs
Comma separated values of External user identifiers
Comma separated values of External user identifiers
Filter for specified markets. Coma separated values. Identifiers’s corresponding with CycleMarket#identifier
Filter donations for ones made before the specified reference_date. Incoming date is expected to be in UTC timezone. The reference_date is the date when a transaction that triggered the donation occurred.
Filter donations for ones made after the specified reference_date. Incoming date is expected to be in UTC timezone. The reference_date is the date when a transaction that triggered the donation occurred.
Sort results by
Sort by reference_date ascending
Sort by reference_date descending
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Donation amount in client’s currency
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
Resource identifier
Resource type
Global unique identfier for this charity
Charity name
Charity description
Charity EIN
Charity website url
Charity logo url with support for different screen densities
The congratulation message that the charity is providing to the donnors after a donation has been made
Street of the regitered charity
Region/state of the registered charity
City of the regitered charity
Zip Code of the regitered charity
The goal set for the charity
Current goal progress, the sum of donations for this market in this cycle.
The number of streches achieved
The amount of donations in the last strech
This charity has been marked as beeing a national one.
The total number of donations that have been received by this cause.
Market id
Market type
Market name
Market size
Market Identifier
The amount of donations that this the goal for this market
Total amount of donations made on this market in a cycle
The number of streches achieved
The amount of donations in the last strech
Market creation date
The total number of donations that have been made in this market
Resource Unique Identifier
Resource type
The cycle name
The cycle custom identifier
The cycle year
The cycle start date
The cycle end date
The cycle creation date
Total number of resources in the collection
Total number of pages
Current page number
GET https://api.goodcoins.io/v1/cycles/donations HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "94182444-b1cc-11e8-9643-eb44a3760e11",
"type": "cycle_donation",
"attributes": {
"external_identifier": "1",
"external_user_identifier": "0c6d1cb691dfb86b",
"amount": 333.33,
"reference_date": "2018-05-16T03:15:34.000Z",
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 42,
"type": "cycle_charity"
}
}
}
}
],
"included": [
{
"id": 42,
"type": "cycle_charity",
"attributes": {
"charity_id": "1",
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"website_url": "http://www.unicefusa.org",
"logo_url": {
"1.0x": "https://res.cloudinary.com/inpact/image/fetch/w_205,h_205,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"1.5x": "https://res.cloudinary.com/inpact/image/fetch/w_308,h_308,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"2.0x": "https://res.cloudinary.com/inpact/image/fetch/w_410,h_410,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"3.0x": "https://res.cloudinary.com/inpact/image/fetch/w_615,h_615,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"4.0x": "https://res.cloudinary.com/inpact/image/fetch/w_820,h_820,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png",
"5.0x": "https://res.cloudinary.com/inpact/image/fetch/w_1024,h_1024,c_pad,g_center,b_auto,d_default_logo_partners_cause.png/https%3A%2F%2Fstatic.goodcoins.io%2Flogos%2F13-1760110.png"
},
"cover_image_url": "https://staging.inpact.care//images/fallback/unclaimed_profile/cover/default.png",
"thank_you_message": "Thank you for the donation.",
"call_to_action": "With this donation we'll make a better world",
"street_address": "",
"region": "",
"city": "",
"zip": "",
"goal_amount": 100,
"goal_progress": 81,
"goal_streches": 1,
"goal_strech_progress": 81,
"national": false
}
}
],
"meta": {
"total_records": 37,
"total_pages": 4,
"page": 1
}
}GET https://api.goodcoins.io/v1/cycles/donations HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/cycles/donations HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}User accounts should be created for individual donors, to retain and recall giving history for tax reporting purposes. Additionally, users can manage favorite charities for easy access through the application or view common stats associated with their giving history.
{id}{id}{id}{id}/stats{id}/favorite-charities{id}/favorite-charities{id}/favorite-charities{external-identifier}/round-up-transactions{external-identifier}/round-upAuthentication
Get a list of user. Optionally you can filter, sort and do custom pagination of the result.
Request parameters
Filter results by the donor first or last name
Filter results by the donor email
Filter results by external identifier. Expects comma separated values of external identifiers
Sort results by
Sort by creation date ascending
Sort by creation date descending
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
Total number of resources in the collection
Total number of pages
Current page number
API link to the next page
API link to the last page
API link to the first page
API link to the previous page
GET https://api.goodcoins.io/v1/users HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"external_identifier": "1",
"region": "SC"
},
"relationships": {
"favorite-charities": {
"links": {
"self": "https://api.goodcoins.io/api/users/1/favorite-charities"
}
}
}
}
],
"meta": {
"total_records": 37,
"total_pages": 4,
"page": 1
},
"links": {
"next": "",
"last": "",
"first": "",
"prev": ""
}
}GET https://api.goodcoins.io/v1/users HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/users HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}Authentication
Create a new user.
Request headers
Authorization header
Request body
Donor first name
Donor last name
Donor email
Donor state
An identifier provided by the API client for cross referencing resources
Responses
Created
Body
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
POST https://api.goodcoins.io/v1/users HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@domain.com",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"external_identifier": "1"
}
}
}POST https://api.goodcoins.io/v1/users HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/email",
},
"title": "Value cannot be empty",
"detail": "You must provide the email address of the user"
}
]
}POST https://api.goodcoins.io/v1/users HTTP/1.1
Content-Type: application/json
Authorization: JWT INVALID-JSON-WEB-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@domain.com",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}POST https://api.goodcoins.io/v1/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer FORBIDDEN-API-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@domain.com",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Update a users. This API endpoint will do a partial update of the user using the given attributes.
Path variables
User ID
Request headers
Authorization header
Request body
User ID
Donor first name
Donor last name
Donor email
Donor state
Responses
OK
Body
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
PATCH https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"email": "john@domain.com"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@domain.com",
"external_identifier": "1",
"region": "SC"
},
"relationships": {
"favorite-charities": {
"links": {
"self": "https://api.goodcoins.io/api/users/1/favorite-charities"
}
}
}
}
}PATCH https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "user",
"attributes": {
"email": ""
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/email",
},
"title": "Value cannot be empty",
"detail": "You must provide the email address of the user"
}
]
}PATCH https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: JWT INVALID-JSON-WEB-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@domain.com",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}PATCH https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: Bearer FORBIDDEN-API-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@domain.com",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Update a users. This API endpoint will do a full update of the user using the given attributes.
Path variables
User ID
Request headers
Authorization header
Request body
User ID
Donor first name
Donor last name
Donor email
Donor state
Responses
OK
Body
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
PUT https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe"
"email": "john@domain.com"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@domain.com",
"external_identifier": "1",
"region": null
},
"relationships": {
"favorite-charities": {
"links": {
"self": "https://api.goodcoins.io/api/users/1/favorite-charities"
}
}
}
}
}PATCH https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "user",
"attributes": {
"email": ""
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/email",
},
"title": "Value cannot be empty",
"detail": "You must provide the email address of the user"
}
]
}PATCH https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: JWT INVALID-JSON-WEB-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@domain.com",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}PATCH https://api.goodcoins.io/v1/users/1 HTTP/1.1
Content-Type: application/json
Authorization: Bearer FORBIDDEN-API-TOKEN
{
"data": {
"type": "user",
"attributes": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe@domain.com",
"region": "SC",
"external_identifier": "1"
}
}
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Path variables
User ID
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
GET https://api.goodcoins.io/v1/users/1 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"external_identifier": "1",
"region": "SC"
}
}
}GET https://api.goodcoins.io/v1/users/42 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/users/1 HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/users/1 HTTP/1.1
Authorization: Bearer FORBIDDEN-API-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}/statsAuthentication
Path variables
User ID
Request headers
Authorization header
Responses
OK
Body
Resource
Number of active recurring donactions
Total amount of donations in USD in the last 30 days
Total amount of donations in USD in the last 6 months
Total amount of donations in USD in the last 12 months
Total amount of donations in USD since the user joined GoodCoin
GET https://api.goodcoins.io/v1/users/1/stats HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "user_stats",
"attributes": {
"active_recurring_donations": 5,
"last_30_days_donations_amount": 3533.5,
"last_6_months_donations_amount": 5744.32,
"last_12_months_donations_amount": 10000,
"lifetime_donations_amount": 10000
}
}
}GET https://api.goodcoins.io/v1/users/42/stats HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/users/1/stats HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/users/1/stats HTTP/1.1
Authorization: Bearer FORBIDDEN-API-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}/favorite-charitiesAuthentication
Get a list of charities favorited by a user
Path variables
User ID
Request parameters
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
Category name
Total number of resources in the collection
Total number of pages
Current page number
API link to the next page
API link to the last page
API link to the first page
API link to the previous page
GET https://api.goodcoins.io/v1/users/1/favorite-charities?page[number]=1&page[size]=10 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
"data": [
{
"type": "charity_category",
"id": "1"
}
]
}
}
},
{
"id": 2,
"type": "charity",
"attributes": {
"name": "American Red Cross",
"description": "The American Red Cross prevents and alleviates human suffering in the face of emergencies by mobilizing the power of volunteers and the generosity of donors.",
"ein": "81-2321523",
"cover_image_url": "http://static.goodcoins.io/covers/81-2321523.jpg",
"logo_url": "https://static.goodcoins.io/logos/81-2321523.png",
"address": "431 18th St NW",
"city": "Washington",
"region": "DC",
"zip": "20006",
"country": "US",
"website_url": "http://www.redcross.org",
"facebook_url": "https://www.facebook.com/redcross",
"linkedin_url": "https://linkedin.com/company/American-Red-Cross",
"twitter_url": "https://twitter.com/redcross",
"instagram_url": "https://www.instagram.com/americanredcross",
"year_founded": "1881",
"revenue_total": 2676037116
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
},
{
"id": 2,
"type": "charity_category"
}
]
}
}
}
],
"included": [
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
},
{
"id": 2,
"type": "charity_category",
"attributes": {
"name": "Benefit to Society"
}
}
],
"meta": {
"total_records": 2,
"total_pages": 1,
"page": "1"
},
"links": {
"next": null,
"last": "https://api.goodcoins.io/v1/users/1/favorite-charities?page[number]=1&page[size]=10",
"first": "https://api.goodcoins.io/v1/users/1/favorite-charities?page[number]=1&page[size]=10",
"prev": null
}
}GET https://api.goodcoins.io/v1/users/1/favorite-charities HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/users/1/favorite-charities HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}/favorite-charitiesAuthentication
Path variables
User ID
Request headers
Authorization header
Request body
Responses
POST https://api.goodcoins.io/v1/users/1/favorite-charities HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": [
{
"id": "1",
"type": "charity"
}
]
}
HTTP/1.1 204 No Content
{id}/favorite-charitiesAuthentication
Path variables
User ID
Request headers
Authorization header
Request body
Responses
DELETE https://api.goodcoins.io/v1/users/1/favorite-charities HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": [
{
"id": "1",
"type": "charity"
}
]
}
HTTP/1.1 204 No Content
Authentication
Request headers
Authorization header
Request body
Resource type
Email address
First name
Last name
External identifier
Institution Identifier
Enrollement completion callback URL. Payload to this url is the same as RoundUP Status: https://speca.io/inpact/goodcoin#user-roundup-status
If true the goodcoin platform will deliver an enrollment email to the provided email address.
If false no enrollment email will be sent.
If the attribute is missing the default behavior value is considered
Responses
Body
Resource Unique Identifier
Resource type
Profile email address
An url that can be used to start the enrollment flow for the user.
Body
Type of problem encountered
Which part of the request document caused the error
Erorr triggered by the email attribute
Description of the error specific for this particular case
POST https://api.goodcoins.io/v1/users/provisional-profiles HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "provisional_profile",
"attributes": {
"email": "joe@domain.com",
"data": {
"first_name": "Joe",
"last_name": "Doe",
"external_identifier": "external-id",
"institution_id": "1",
"callback_url": "http://www.example.com",
"notification": true
}
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": 1,
"type": "provisional_profile",
"attributes": {
"email": "user@example.test",
"enrollment_url": "https://giving-site.goodcoins.io/round_up_confirmations/:id"
}
}
}{external-identifier}/round-up-transactionsAuthentication
Path variables
Request body
Resource type
Amount
Date when donation resource was created (UTC Timezone)
Description
Reference Identifer
Responses
Body
Resource Unique Identifier
Resource type
Amount
Date when donation resource was created (UTC Timezone)
Description
Reference Identifier
Body
Type of problem encountered
Which part of the request document caused the error
When the error is triggered by an attribute given use this to reference that attribute
Description of the error specific for this particular case
POST https://api.goodcoins.io/v1/users/0000-0000-0001/round-up-transactions HTTP/1.1
Content-Type: application/json
{
"data": {
"type": "round_up_transaction",
"attributes": {
"amount": 0.99,
"date": "2019-01-01",
"description": "Transaction #9999",
"reference_id": "9999"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": 1,
"type": "round_up_transaction",
"attributes": {
"amount": "10",
"date": "2019-01-10",
"description": "Transaction #9999",
"reference_id": "9999"
}
}
}{external-identifier}/round-upAuthentication
Path variables
Request headers
Authorization header
Responses
Body
Resource Type
Enrolment Status
RoundUp balance
Auto Donate Status
Auto Donate Charity Name
Account status, one of suspended or active
GET https://api.goodcoins.io/v1/users/0000-0000-0001/round-up HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"type": "user_round_up_status",
"attributes": {
"round_up_enrolment_status": "pending/completed",
"balance": 100.99,
"auto_donate_status": "true",
"auto_donate_charity_name": "Unicef",
"account_status": "active"
}
}
}Direct donations from users to charities can be registered through the Donations API. Client applications are responsible for payment processing of the appropriate amount to the GoodCoin Foundation, and donation data will be reconciled by GCF against bank deposits to verify grant integrity. Users can also include a donation to GoodCoin Foundation to help offset operating costs. The full donation amount is tax deductible.
For loyalty applications, providers should convert points to the cash value and make a donation in that amount. It’s encouraged to let users know the cash value of their donation prior to making their gift. In this case, the loyalty provider (not cardholders) receive the tax receipt from the GoodCoin Foundation for their gift.
{id}{id}/donationsAuthentication
Get a list of donations. Optionally, you can filter the list by the donor email, Charity IDs, User IDs or keyword.
Note: market_identifiers filter can be used to restrict the result only to the markets of interest. The identifiers correspond with identifier attribute from cycle_market.
Request parameters
Filter results by the donor email
Comma separated values of Charity IDs
Comma separated values of User IDs
Filter for specified markets. Coma separated values. Identifiers’s corresponding with CycleMarket#identifier
Comma separated values of External user identifiers
Comma separated values of donation external identifiers
Filter donations for ones made after the specified date. Incoming date is expected to be in UTC timezone
Filter donations for ones made before the specified date. Incoming date is expected to be in UTC timezone
Sort results by
Sort by date ascending
Sort by date descending
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Id of the market that recored this donation. This is used in conjuction with cycle API.
Donation amount in client’s currency
Donation made for The GoodCoin Foundation in client’s currency
Note included with the donation
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
If the donation was created using the cycle donation api then the type will be cycle_charity
This resource will be missing if the API integration is in anonymized mode and it will be present in the default mode.
User ID
Resource Unique Identifier
Resource type
Category name
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
Resource identifier
Resource type
Global unique identfier for this charity
Charity name
Charity description
Charity EIN
Charity website url
Charity logo url with support for different screen densities
The congratulation message that the charity is providing to the donnors after a donation has been made
Street of the regitered charity
Region/state of the registered charity
City of the regitered charity
Zip Code of the regitered charity
The goal set for the charity
Current goal progress, the sum of donations for this market in this cycle.
The number of streches achieved
The amount of donations in the last strech
This charity has been marked as beeing a national one.
The total number of donations that have been received by this cause.
Total number of resources in the collection
Total number of pages
Current page number
API link to the next page
API link to the last page
API link to the first page
API link to the previous page
GET https://api.goodcoins.io/v1/donations HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "donation",
"attributes": {
"external_identifier": "1",
"amount": 100,
"gcf_donation": 15,
"note": "Great job!",
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "charity"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
},
{
"id": 2,
"type": "donation",
"attributes": {
"external_identifier": "2",
"amount": 200,
"gcf_donation": 0,
"note": "",
"created_at": "2018-05-17T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "charity"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
],
"included": [{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
}
}, {
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}, {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"region": "SC",
"external_identifier": "1"
}
}],
"meta": {
"total_records": 37,
"total_pages": 4,
"page": 1
},
"links": {
"next": "",
"last": "",
"first": "",
"prev": ""
}
}GET https://api.goodcoins.io/v1/donations HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/donations HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}Authentication
Get the summary of donations.
Request parameters
Filter results by the donor email
Comma separated values of Charity IDs
Comma separated values of Cycle Charities IDs. The id attribute from the cycle_charity type
Comma separated values of User IDs
Filter for specified markets. Coma separated values. Identifiers’s corresponding with CycleMarket identifier attribute
Comma separated values of External user identifiers
Comma separated values of donation external identifiers
Filter donations for ones made after the specified date. Incoming date is expected to be in UTC timezone
Filter donations for ones made before the specified date. Incoming date is expected to be in UTC timezone
Filter donations for ones made after the specified reference_date. Incoming date is expected to be in UTC timezone. The reference_date is the date when a transaction that triggered the donation occurred.
Filter donations for ones made before the specified reference_date. Incoming date is expected to be in UTC timezone. The reference_date is the date when a transaction that triggered the donation occurred.
Request headers
Authorization header
Responses
OK
Body
The summarized donation amount for the given filter
GET https://api.goodcoins.io/v1/donations/summary HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
Content-Type: application/json
{
"data": {
"type": "donations_summary",
"attributes" : {
"amount": 100.13
}
}
}GET https://api.goodcoins.io/v1/donations HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/donations HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Path variables
Donation ID
Request headers
Authorization header
Responses
OK
Body
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Id of the market that recored this donation. This is used in conjuction with cycle API.
Donation amount in client’s currency
Donation made for The GoodCoin Foundation in client’s currency
Note included with the donation
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
If the donation was created using the cycle donation api then the type will be cycle_charity
This resource will be missing if the API integration is in anonymized mode and it will be present in the default mode.
User ID
GET https://api.goodcoins.io/v1/donations/1 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "donation",
"attributes": {
"external_identifier": "1",
"amount": 15,
"gcf_donation": 1.5,
"note": "Great job!",
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "charity"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
},
"included": [{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
}
}, {
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}, {
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"region": "SC",
"external_identifier": "1"
}
}]
}GET https://api.goodcoins.io/v1/donations/42 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/donations/1 HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/donations/1 HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}/donationsAuthentication
Create a new donation record associated with a charity.
Discussion on external_user_identifier:
When creating a donation and the API integration is configured to accept anonymized donations mode an user resource will not be accepted as input argument for the api call. In this mode the external_user_identifier is required.
When the API integration is configured in the default mode the user resource is required and the API call will fail if an external_user_identifier is present.
Path variables
Charity ID
Request headers
Authorization header
Request body
Donation amount in client’s currency, by default the amount is exchanged in USD at rate of 1
Donation made for The GoodCoin Foundation in client’s currency
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Include a note with the donation
Send occasional updates from this charity
A market identifier if one is availale. This is used in conjunction with the cycle api when running programs that contain vetted charities.
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Rate for exchanging the amount in client’s currency. Required - when client has variable exchange rate, Ignored - when client has fixed exchange rate
Only required if the API integration is in default mode. In anonymized mode this should not be present but an external_user_identifier should be passed instead.
User ID
Responses
Body
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Id of the market that recored this donation. This is used in conjuction with cycle API.
Donation amount in client’s currency
Donation made for The GoodCoin Foundation in client’s currency
Note included with the donation
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
If the donation was created using the cycle donation api then the type will be cycle_charity
This resource will be missing if the API integration is in anonymized mode and it will be present in the default mode.
User ID
Resource Unique Identifier
Resource type
Category name
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
POST https://api.goodcoins.io/v1/charities/{id}/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"amount": 333.33,
"gcf_donation": 1,
"external_identifier": "1",
"external_user_identifier": "0c6d1cb691dfb86b",
"note": "",
"receive_updates": "false",
"market_id": "market-id",
"reference_date": "2018-05-16T04:00:00.000Z",
"exchange_currency": 0.5
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}POST https://api.goodcoins.io/v1/charities/1/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"amount": null,
"external_identifier": "1"
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/amount",
},
"title": "Value cannot be empty",
"detail": "You must specify an amount in order to create a donation"
}
]
}POST https://api.goodcoins.io/v1/charities/1/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT INVALID-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"amount": 1,
"external_identifier": "1"
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}POST https://api.goodcoins.io/v1/charities/1/donations HTTP/1.1
Content-Type: application/json
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"amount": 1,
"external_identifier": "1"
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}For loyalty providers, as an alternative to full cash gifts to charities, the Donation Pool is an opportunity for users to crowd-fund a large grant to a nonprofit organization. Providers can configure a donation pool for a specified amount (ex. $1,000), and users can contribute points to the campaign up to a specified amount, at which point the grant is triggered. This is a useful option for low point value redemptions that may not otherwise be enough for a full cash donation. Votes are used as the generic currency, which could be points or some other intermediate value.
For example, if each loyalty point (vote) should be equivalent to a $0.50 donation toward a $1,000 gift, then set the donation_amount to 1000 and the goal to 2000. If users have different dollar values associated with a point on their account, set each vote to be worth $0.01 (100,000 votes in this example). Then cast votes in increments corresponding to the value of a point (a $0.50 value point would be 50 votes).
{id}{id}{id}/votesAuthentication
Get a list of donation pools.
Request parameters
Filter results by status
Filter results by keywords
Filter results based on charity (You can pass either a single charity Identifier or multiple comma separated)
Filter pools for ones completed after the specified date. Note that by applying this filter we will only show completed pools. Incoming date is expected to be in UTC timezone
Filter pools for ones completed before the specified date. Note that by applying this filter we will only show completed pools. Incoming date is expected to be in UTC timezone
Filter results based on pool type. This can have 3 values as follows:
- empty (default) - Return shared pools and current customer pools
- false - Return current customer pools only
- true - Return shared pools only
Sort results by
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
The donation pool title (usually the charity name)
The charity pool description
Date when the pool will be deactivated
Donation amount in USD that will be granted once the votes goal will be reached
Number of votes required for the donation for this pool to be granted
Number of current votes
Percentage value of current progress
Status of the pool
Date and time the pool was completed
Date when Donation Pool was created
Charity towards to donation is directed to for this pool
Charity Resource Identifier
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
Category name
Total number of resources in the collection
Total number of pages
Current page number
API link to the next page
API link to the last page
API link to the first page
API link to the previous page
GET https://api.goodcoins.io/v1/donation-pools HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500,
"current": 110,
"progress": 22,
"status": "active",
"completed_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
}
],
"included": [
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
}
]
}
}
},
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}
],
"meta": {
"total_records": 37,
"total_pages": 4,
"page": 1
},
"links": {
"next": "",
"last": "",
"first": "",
"prev": ""
}
}GET https://api.goodcoins.io/v1/donation-pools HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/donation-pools HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Get a donation pool by its ID.
Path variables
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
The donation pool title (usually the charity name)
The charity pool description
Date when the pool will be deactivated
Donation amount in USD that will be granted once the votes goal will be reached
Number of votes required for the donation for this pool to be granted
Number of current votes
Percentage value of current progress
Status of the pool
Date and time the pool was completed
Date when Donation Pool was created
Charity towards to donation is directed to for this pool
Charity Resource Identifier
Resource Unique Identifier
Resource type
Category name
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
GET https://api.goodcoins.io/v1/donations/pools/1 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500,
"current": 110,
"progress": 22,
"status": "active",
"completed_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
},
"included": [
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
}
]
}
}
},
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}
]
}GET https://api.goodcoins.io/v1/donations/pools/42 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}GET https://api.goodcoins.io/v1/donations/pools/1 HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/donations/pools/1 HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}Authentication
Create a donation pool.
Request headers
Authorization header
Request body
Resource type
The charity pool title
The charity pool description
Date when the pool will be deactivated
Number of votes required for the donation for this pool to be granted
Donation amount in USD that will be granted once the votes goal will be reached
Flag to specify if it is accessible to all Customers or just current Customer
Charity towards to donation is directed to for this pool
Charity Resource Identifier
Responses
Body
Resource Unique Identifier
Resource type
The donation pool title (usually the charity name)
The charity pool description
Date when the pool will be deactivated
Donation amount in USD that will be granted once the votes goal will be reached
Number of votes required for the donation for this pool to be granted
Number of current votes
Percentage value of current progress
Status of the pool
Date and time the pool was completed
Date when Donation Pool was created
Charity towards to donation is directed to for this pool
Charity Resource Identifier
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
Category name
POST https://api.goodcoins.io/v1/donation-pools HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 2500,
"donation_amount": 50000,
"end_date": "2018-12-31T23:59:59.999Z"
},
"relationships": {
"charity": {
"data": {
"id": "1269",
"type": "charity"
}
}
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "1",
"type": "donation_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"end_date": "2018-12-31T23:59:59.999Z",
"donation_amount": 50000,
"goal": 2500,
"current": null,
"progress": 0,
"status": "active",
"completed_at": null
},
"relationships": {
"charity": {
"data": {
"id": "1269",
"type": "charity"
}
}
}
},
"included": [
{
"id": "1269",
"type": "charity",
"attributes": {
"name": "UNICEF USA",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": null,
"logo_url": "https://www.guidestar.org/ViewEdoc.aspx?eDocId=3769887&approved=true",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": null,
"linkedin_url": null,
"twitter_url": null,
"instagram_url": "https://www.instagram.com/unicefusa",
"year_founded": "1947",
"revenue_total": 473933337,
"documents": [
{
"url": "http://www.guidestar.org/FinDocuments/2017/131/760/2017-131760110-0eeba8ad-9.pdf",
"name": "2017 Form 990",
"type": "form-990",
"created-at": "2017-12-31"
},
{
"url": "http://www.guidestar.org/FinDocuments/2017/131/760/2017-131760110-0ef71688-9.pdf",
"name": "2017 Form 990",
"type": "form-990",
"created-at": "2017-12-31"
},
{
"url": "http://www.guidestar.org/FinDocuments/2016/131/760/2016-131760110-0d7cc082-9.pdf",
"name": "2016 Form 990",
"type": "form-990",
"created-at": "2016-12-31"
}
],
"programs": [
{
"name": "Health & Immunization",
"budget": "",
"description": "UNICEF gives children brighter futures by supporting healthy lives around the world. Low-cost, proven solutions, including oral rehydration salts to treat life-threatening diarrhea and insecticide-treated mosquito nets to help prevent malaria, are helping kids get a healthy start. As one of the world’s largest buyers of lifesaving supplies, UNICEF has unique leverage to negotiate the lowest prices– and thus, to save more lives. Immunizations are one of the most effective and cost-effective ways to protect children’s health, but more than half of the world’s most vulnerable children still miss out on the essential vaccines they need to protect them from diseases like polio, measles and tetanus. UNICEF reaches nearly half of the world’s children through immunization, saving up to 3 million children from life-threatening diseases each year.",
"areas-served": [
"Global"
],
"target-population": "Children and youth (0-19 years)"
},
{
"name": "Nutrition",
"budget": "",
"description": "Good nutrition is the bedrock of child survival and development. Well-nourished children are better able to grow and learn, participate in their communities and remain resilient to disease or disaster. Yet, 1 in 4 children around the world is malnourished, and malnutrition is linked to nearly half of all childhood deaths under age 5. UNICEF helps children survive and thrive by procuring and distributing 80 percent of the world’s supply of a “miracle” treatment known as Ready-To-Use Therapeutic Food (RUTF). UNICEF treats children with the lifesaving paste that enables them to grow and thrive, while also working with manufacturers to increase supplies and keep prices down. In 2016, UNICEF and partners treated 3.4 million children for severe acute malnutrition in 71 countries. ",
"areas-served": [
"Global"
],
"target-population": "Children and youth (0-19 years)"
}
],
"impact_survey": [
{
"answer": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. By providing access to health care, nutrition, clean water, education, protection and more, UNICEF empowers every child to have a brighter future. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes, and every child has a safe and healthy childhood.",
"question": "What is your organization aiming to accomplish"
},
{
"answer": "− UNICEF works day-in and day-out in some of the world's toughest places. We've been there for decades, working in communities to do what's best for children. \r\n\r\n− UNICEF has unequalled experience and expertise in saving and improving children's lives. \r\n\r\n− UNICEF is globally recognized for instituting long-term, sustainable solutions.\r\n\r\n− Innovation has always been at the heart of UNICEF's ability to achieve results for children, from negotiating drug prices, to establishing new delivery methods, to utilizing new technologies.\r\n\r\n− UNICEF's vast network means it can take successful approaches from one place and adapt them to meet challenges elsewhere, helping drive results for children on a global scale.\r\n\r\n− In all UNICEF does, it works to engage and empower young people to have a voice in the decisions that affect their lives and support their peers.\r\n\r\n− UNICEF USA invites all Americans to join us. Whether it's by giving time or money, through education, awareness-raising or advocacy, everyone has something to contribute to make this world a better place for all children. \r\n\r\n− In the United States, UNICEF USA has a long history of instilling global citizenship in students. In 2016, over a million kids participated in UNICEF USA programs, including Trick-or-Treat for UNICEF and UNICEF Kid Power. ",
"question": "What are your strategies for making this happen?"
},
{
"answer": "− UNICEF works in more than 190 countries — more than any other children's organization. This includes nearly 13,000 staff in 157 field offices carrying out programs on the ground and 34 national committees that conduct fundraising, advocacy and education in support of UNICEF's mission.\r\n\r\n− With a global innovation center to help scale up proven solutions, UNICEF is helping lead the development of a new wave of technologies and products to help reach the hardest-to-reach children and communities.\r\n\r\n− As one of the world's largest buyers of lifesaving supplies such as vaccines, mosquito nets and Ready-to-Use Therapeutic Food (RUTF), UNICEF has unique leverage to negotiate the lowest prices.\r\n\r\n− UNICEF's global network of staff and volunteers is on the ground before, during and after humanitarian emergencies, in some of the toughest, most remote places in the world. Activating at a moment's notice, UNICEF can ship emergency supplies anywhere in the world within 48 to 72 hours from its warehouse in Copenhagen, which is the world's largest humanitarian warehouse.\r\n\r\n− UNICEF USA has communities of supporters all over the United States that work together to fundraise and advocate for the world's most vulnerable children.\r\n\r\n− The organization's nine regional offices work to highlight UNICEF's work from coast to coast and engage people in their communities in support of our mission. Each office hosts a number of events, educational speaker series, and family-friendly activities throughout the year that allow people to take action locally, knowing that their impact will be felt around the globe. \r\n\r\n− Students can join UNICEF high school and college campus clubs, which participate in campaigns, host international dinners, organize concerts, advocate on Capitol Hill, collaborate on regional webinars, and much more.\r\n\r\n− UNICEF USA has a long history of promoting global citizenship among children and young people. More than 66 years ago, Trick-or-Treat for UNICEF — the original Kids-Helping-Kids campaign — was introduced as a way for kids in the U.S. to help their peers around the world. In 2014, building on the success of the original Kids-Helping-Kids campaign, UNICEF USA launched UNICEF Kid Power, which activates kids' inner heroes, giving them the power to end global malnutrition and save lives, one step at a time.",
"question": "What are your organization's capabilities for doing this?"
},
{
"answer": "UNICEF implements programs with specific key performance indicators, based on research and evidence that demonstrates they are effective. A data-driven organization, UNICEF evaluates and reports on the success of its programs annually. UNICEF is also accountable and transparent about its financial and programmatic outcomes. With seven regional offices around the world, UNICEF teams share knowledge and lessons learned across countries to help scale results and strengthen institutional knowledge for maximum effectiveness. \r\n\r\nUNICEF is a thought leader and primary researcher on the conditions, challenges and progress on children's issues, and must report to the U.N. — and the world — on this. UNICEF produces a global flagship report on the State of the World's Children, showing the progress that we and other partners have helped to achieve in terms of child survival, education, protection and beyond. UNICEF also releases an annual report on its global impact, demonstrating the results achieved in the previous year. ",
"question": "How will your organization know if you are making progress?"
},
{
"answer": "There have been tremendous advances made for children around the world, especially in the past 30 years ...\r\n\r\n− Since its inception over 70 years ago, UNICEF has helped save more children's lives than any other humanitarian organization.\r\n\r\n− Overall, UNICEF's programs have helped reduce the number of child deaths by more than 56% since 1990.\r\n\r\n− UNICEF is the world's largest purchaser and distributor of Ready-to-Use Therapeutic Food (RUTF) — procuring 80% of the lifesaving malnutrition treatment. In 2016, UNICEF and its partners treated 3.4 million children for severe acute malnutrition.\r\n\r\n− UNICEF reaches nearly half of the world's children through immunization, making UNICEF the largest buyer of vaccines for children, and saving up to 3 million children from life-threatening diseases each year. \r\n\r\n− UNICEF works in more than 100 countries to improve access to safe, clean water and sanitation facilities, and uses innovative technologies, like solar-powered water pumps, to provide sustainable access to water. UNICEF and partners have helped 2.6 billion people gain access to clean water since 1990. \r\n\r\n− UNICEF has one of the largest global child education footprints, with programs in 155 countries that provide education materials to more than 15 million children. In 2016, UNICEF provided 15.7 million children with learning materials through nearly 331,000 classrooms.\r\n\r\n... but millions of children are still left behind\r\n\r\n− Every day, about 15,000 children die from things we can prevent.\r\n\r\n− More than half of the world's most vulnerable children still miss out on the essential vaccines they need to survive and live healthy lives.\r\n\r\n− One in four children worldwide suffer from chronic malnutrition.\r\n\r\n− Over 800 children die every day — about one every two minutes — due to unsafe drinking water, poor sanitation or poor hygiene.\r\n\r\n− Worldwide, at least 264 million children and teens have no chance to go to school.\r\n\r\n− Fifty million children have been forced from their homes or countries — many fleeing violence, war, poverty and climate change.",
"question": "What have you accomplished so far and what's next?"
}
],
"expenses": {
"year": 2017,
"total": 476195828,
"fundrasing": 44352935,
"administration": 15072309,
"program-services": 416770584
},
"revenue_sources": {
"year": 2017,
"contributions": 471461166,
"special-events": 0,
"governmental-grants": 0
},
"matching": {
"available": false
}
},
"relationships": {
"categories": {
"data": [
{
"id": "7",
"type": "category"
},
{
"id": "6",
"type": "category"
},
{
"id": "5",
"type": "category"
}
]
}
}
},
{
"id": "7",
"type": "charity_category",
"attributes": {
"name": "Foreign Affairs"
}
},
{
"id": "5",
"type": "charity_category",
"attributes": {
"name": "Health"
}
},
{
"id": "6",
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}
]
}
POST https://api.goodcoins.io/v1/donations/pools HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 1000001,
"end_date": "2018-12-31T23:59:59.999Z"
},
"relationships": {
"charity": {
"data": {
"id": "1269",
"type": "charity"
}
}
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "less_than_or_equal_to",
"source": {
"pointer": "/data/attributes/goal"
},
"detail": "Goal must be less than or equal to 1000000"
},
{
"code": "not_a_number",
"source": {
"pointer": "/data/attributes/donation_amount"
},
"detail": "Donation amount is not a number"
}
]
}POST https://api.goodcoins.io/v1/donation-pools HTTP/1.1
Content-Type: application/json
Authorization: JWT INVALID-JSON-WEB-TOKEN
{
"data": {
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}POST https://api.goodcoins.io/v1/donation-pools HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
}
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}Authentication
Mark a pool as completed
Path variables
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
The donation pool title (usually the charity name)
The charity pool description
Date when the pool will be deactivated
Donation amount in USD that will be granted once the votes goal will be reached
Number of votes required for the donation for this pool to be granted
Number of current votes
Percentage value of current progress
Status of the pool
Date and time the pool was completed
Date when Donation Pool was created
Charity towards to donation is directed to for this pool
Charity Resource Identifier
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
Category name
DELETE https://api.goodcoins.io/v1/donations/pools/1 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": 1,
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500,
"current": 110,
"progress": 22,
"status": "active",
"completed_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
},
"included": [
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
}
]
}
}
},
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}
]
}DELETE https://api.goodcoins.io/v1/donations/pools/42 HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}DELETE https://api.goodcoins.io/v1/donations/pools/1 HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}DELETE https://api.goodcoins.io/v1/donations/pools/1 HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}{id}/votesAuthentication
Path variables
Donations Pool ID
Request headers
Authorization header
Request body
Number of votes to cast
An identifier provided by the API client for cross referencing resources
User ID
Responses
Body
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
Number of votes
Date when donation resource was created (UTC Timezone)
User ID
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
The donation pool title (usually the charity name)
The charity pool description
Date when the pool will be deactivated
Donation amount in USD that will be granted once the votes goal will be reached
Number of votes required for the donation for this pool to be granted
Number of current votes
Percentage value of current progress
Status of the pool
Date and time the pool was completed
Date when Donation Pool was created
Charity towards to donation is directed to for this pool
Charity Resource Identifier
Resource Unique Identifier
Resource type
Category name
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
POST https://api.goodcoins.io/v1/donation-pools/1/votes HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "vote",
"attributes": {
"count": 1,
"external_identifier": "1"
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": 1,
"type": "donation",
"attributes": {
"external_identifier": "1",
"count": 1,
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "donations_pool"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
},
"included": [
{
"id": 1,
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500,
"current": 1,
"progress": 0,
"status": "active",
"completed_at": null
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
},
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
}
]
}
}
},
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
},
{
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"external_identifier": "1",
"region": "SC"
},
"relationships": {
"favorite-charities": {
"links": {
"self": "https://api.goodcoins.io/api/users/1/favorite-charities"
}
}
}
}
]
}POST https://api.goodcoins.io/v1/donation-pools/1/votes HTTP/1.1
Content-Type: application/json
Authorization: JWT VALID-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"count": null,
"external_identifier": "1",
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/amount",
"parameter": "id"
},
"title": "Value cannot be empty",
"detail": "You must specify an amount in order to create a donation"
}
]
}POST https://api.goodcoins.io/v1/donation-pools/1/votes HTTP/1.1
Content-Type: application/json
Authorization: JWT INVALID-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"count": 1,
"external_identifier": "1",
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}POST https://api.goodcoins.io/v1/donation-pools/1/votes HTTP/1.1
Content-Type: application/json
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
{
"data": {
"type": "donation",
"attributes": {
"count": 2,
"external_identifier": "1",
},
"relationships": {
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}Authentication
Request parameters
Comma separated values of Donations Pool IDs
Comma separated values of User IDs
Comma separated values of donation external identifiers
Filter donations for ones made after the specified date. Incoming date is expected to be in UTC timezone
Filter donations for ones made before the specified date. Incoming date is expected to be in UTC timezone
Page number to fetch
Number of results per page
Request headers
Authorization header
Responses
Body
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Id of the market that recored this donation. This is used in conjuction with cycle API.
Donation amount in client’s currency
Donation made for The GoodCoin Foundation in client’s currency
Note included with the donation
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
If the donation was created using the cycle donation api then the type will be cycle_charity
This resource will be missing if the API integration is in anonymized mode and it will be present in the default mode.
User ID
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Id of the market that recored this donation. This is used in conjuction with cycle API.
Donation amount in client’s currency
Donation made for The GoodCoin Foundation in client’s currency
Note included with the donation
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
If the donation was created using the cycle donation api then the type will be cycle_charity
This resource will be missing if the API integration is in anonymized mode and it will be present in the default mode.
User ID
Resource Unique Identifier
Resource type
The donation pool title (usually the charity name)
The charity pool description
Date when the pool will be deactivated
Donation amount in USD that will be granted once the votes goal will be reached
Number of votes required for the donation for this pool to be granted
Number of current votes
Percentage value of current progress
Status of the pool
Date and time the pool was completed
Date when Donation Pool was created
Charity towards to donation is directed to for this pool
Charity Resource Identifier
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
Resource Unique Identifier
Resource type
Category name
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
GET https://api.goodcoins.io/v1/donation-pools/1/donations HTTP/1.1
Authorization: JWT VALID-JSON-WEB-TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 1,
"type": "donation",
"attributes": {
"external_identifier": "1",
"amount": 1,
"gcf_donation": 0,
"note": "",
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "donations_pool"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
},
{
"id": 2,
"type": "donation",
"attributes": {
"external_identifier": "1",
"amount": 3,
"gcf_donation": 0,
"note": "",
"created_at": "2018-05-17T04:00:01.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "donations_pool"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}
],
"included": [
{
"id": 1,
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500,
"current": 0,
"progress": 0,
"status": "active",
"completed_at": null
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
},
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
}
]
}
}
},
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
},
{
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"external_identifier": "1",
"region": "SC"
},
"relationships": {
"favorite-charities": {
"links": {
"self": "https://api.goodcoins.io/api/users/1/favorite-charities"
}
}
}
}
]
}GET https://api.goodcoins.io/v1/donation-pools/1/donations HTTP/1.1
Authorization: JWT INVALID-JSON-WEB-TOKEN
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}GET https://api.goodcoins.io/v1/donation-pools/1/donations HTTP/1.1
Authorization: JWT FORBIDDEN-JSON-WEB-TOKEN
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}The Resource Identifier is an object used across the API to identify a resource. Will be present when responding to resources requests and to reference relationships between resources.
Resource Unique Identifier
Resource type
This is an abstract representation of a resource object. All resources have an id property representing the unique identifier of the resource and a type property to describe the resource type. Those 2 properties can be considered globally unique across the whole system. All resources all contain an attributes property under which all other resource properties are defined.
Unique Identifier of a resource
Resource type
Resource attributes
For resources having relationships to other resources this object will containt references to those resources
Key will be the resource name
Resource Unique Identifier
Resource type
Key will be the collection name
Under the data key there will be an arrat of Resource Identifier objects
Resource Unique Identifier
Resource type
User resource.
Resource Unique Identifier
Resource type
User first name
User last name
User email address
An identifier provided by the API client for cross referencing resources
Donor state
API endpoint to user’s favorite charities
{
"id": 1,
"type": "user",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"external_identifier": "1",
"region": "SC"
},
"relationships": {
"favorite-charities": {
"links": {
"self": "https://api.goodcoins.io/api/users/1/favorite-charities"
}
}
}
}User Stats
Resource
Number of active recurring donactions
Total amount of donations in USD in the last 30 days
Total amount of donations in USD in the last 6 months
Total amount of donations in USD in the last 12 months
Total amount of donations in USD since the user joined GoodCoin
{
"id": 1,
"type": "user_stats",
"attributes": {
"active_recurring_donations": 5,
"last_30_days_donations_amount": 3533.5,
"last_6_months_donations_amount": 5744.32,
"last_12_months_donations_amount": 10000,
"lifetime_donations_amount": 10000
}
}This resource represents a Charity.
Resource Unique Identifier
Resource type
Charity name
Charity description or mission statement
Charity Employer Identification Number
Cover image url
Logo url
Street address
City
State
Postal Code
Country
Website url
Facebook page
LinkedIn profile
Twitter url
Instagram page
Year the charity was founded
Total revenue (last reporting year)
Collection documents related to the charity activity (can be IRS Form 990 or Annual Report)
Document type
Document title
Date when document was release
URL to the document (usually it’s a PDF document)
Collection of programs the charity is running
Name of the program
Description of the program
Targetted population for this program
Budget allocated for this program
Collection of geographical areas served by this program
Collection of questions and answers related to charity impact
Charity expenses breakdown
Boolean flag indicating if donation matching is available for direct donations towards this charity
The minimum amount a donor must give to enable matching
The maximum dollar value of matching that will be applied to a donation
Percentage of the donation that will be matched
{
"id": 1,
"type": "charity",
"attributes": {
"name": "UNICEF",
"description": "The United Nations Children's Fund (UNICEF) works in more than 190 countries and territories to put children first. UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States. Together, we are working toward the day when no children die from preventable causes and every child has a safe and healthy childhood.",
"ein": "13-1760110",
"cover_image_url": "http://static.goodcoins.io/covers/13-1760110.jpg",
"logo_url": "https://static.goodcoins.io/logos/13-1760110.png",
"address": "125 Maiden Lane",
"city": "New York",
"region": "NY",
"zip": "10038",
"country": "US",
"website_url": "http://www.unicefusa.org",
"facebook_url": "https://www.facebook.com/unicef/",
"linkedin_url": "https://linkedin.com/company/unicef",
"twitter_url": "https://twitter.com/UNICEF",
"instagram_url": "https://www.instagram.com/unicef/",
"year_founded": "1947",
"revenue_total": 553250245
},
"relationships": {
"categories": {
data: [
{
"id": 1,
"type": "charity_category"
}
]
]
}
}{
"id": 2,
"type": "charity",
"attributes": {
"name": "American Red Cross",
"description": "The American Red Cross prevents and alleviates human suffering in the face of emergencies by mobilizing the power of volunteers and the generosity of donors.",
"ein": "81-2321523",
"cover_image_url": "http://static.goodcoins.io/covers/81-2321523.jpg",
"logo_url": "https://static.goodcoins.io/logos/81-2321523.png",
"address": "431 18th St NW",
"city": "Washington",
"region": "DC",
"zip": "20006",
"country": "US",
"website_url": "http://www.redcross.org",
"facebook_url": "https://www.facebook.com/redcross",
"linkedin_url": "https://linkedin.com/company/American-Red-Cross",
"twitter_url": "https://twitter.com/redcross",
"instagram_url": "https://www.instagram.com/americanredcross",
"year_founded": "1881",
"revenue_total": 2676037116
},
"relationships": {
"categories": {
"data": [
{
"id": 1,
"type": "charity_category"
},
{
"id": 2,
"type": "charity_category"
}
]
}
}
}
Charity Category resource.
Resource Unique Identifier
Resource type
Category name
{
"id": 1,
"type": "charity_category",
"attributes": {
"name": "Human Services"
}
}{
"id": 2,
"type": "charity_category",
"attributes": {
"name": "Benefit to Society"
}
}The Donation resource. A donation can be created towards a Charity or a Donations Pool.
Note: The external_identifier field can be used to cross reference donation data with your own informational systems. You can use any values for this field as it isn’t validated (presence, uniquness, etc). You could use it to reference donations records on your system by passing here an identifier relate to your donation.
Note: The external_user_identifier field can be used to corss reference the user identity with your own identity management system. This can be used when the API integration is configured to accept anonymized donations.
When the API integration is configured to accept anonymized donations the user resource won’t be present and external_user_identifier will be exposed instead.
In the default mode the user resource is included and the external_user_identifier it will be excluded.
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Id of the market that recored this donation. This is used in conjuction with cycle API.
Donation amount in client’s currency
Donation made for The GoodCoin Foundation in client’s currency
Note included with the donation
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
If the donation was created using the cycle donation api then the type will be cycle_charity
This resource will be missing if the API integration is in anonymized mode and it will be present in the default mode.
User ID
{
"id": 1,
"type": "donation",
"attributes": {
"external_identifier": "1",
"amount": 1.5,
"created_at": "2018-05-16T03:16:34.000Z",
"gcf_donation": 1,
"note": "Great job!"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "charity"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}{
"id": 1,
"type": "donation",
"attributes": {
"external_identifier": "1",
"amount": 1,
"created_at": "2018-05-16T03:16:34.000Z",
"gcf_donation": 0,
"note": ""
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "donations_pool"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}The Donation Pool resource is a resources with a one-to-one relationship to the Charity resource. Donations can be made towards a Donation Pool.
Resource Unique Identifier
Resource type
The donation pool title (usually the charity name)
The charity pool description
Date when the pool will be deactivated
Donation amount in USD that will be granted once the votes goal will be reached
Number of votes required for the donation for this pool to be granted
Number of current votes
Percentage value of current progress
Status of the pool
Date and time the pool was completed
Date when Donation Pool was created
Charity towards to donation is directed to for this pool
Charity Resource Identifier
{
"id": 1,
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500,
"current": 110,
"progress": 22,
"status": "active",
"completed_at": null
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
}{
"id": 1,
"type": "donations_pool",
"attributes": {
"title": "United States Fund for UNICEF",
"description": "UNICEF has helped save more children’s lives than any other humanitarian organization, by providing health care and immunizations, clean water and sanitation, nutrition, education, emergency relief and more. UNICEF USA supports UNICEF's work through fundraising, advocacy and education in the United States.",
"goal": 500,
"current": 500,
"progress": 100,
"status": "completed",
"completed_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"charity": {
"data": {
"id": "1",
"type": "charity"
}
}
}
}Customer resource
Resource Unique Identifier
Resource type
Customer name
User last name
If the Customer wants to restrict donations only for some Cards
If customer restrict Cards this will be a list of allowed BIN ranges
[]{
"id": 1,
"type": "customer",
"attributes": {
"name": "Credit Union 1",
"goodcoins_url": "https://credit-union.goodcoins.io",
"bin_restriction": true,
"bin_ranges": [
"374660",
"374661"
]
}
}The Donation resource. A donation can be created towards a Charity or a Donations Pool.
Note: The external_identifier field can be used to cross reference donation data with your own informational systems. You can use any values for this field as it isn’t validated (presence, uniquness, etc). You could use it to reference donations records on your system by passing here an identifier relate to your donation or you could reference an user identifier specific for your record to reference user donations.
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
Number of votes
Date when donation resource was created (UTC Timezone)
User ID
{
"id": 1,
"type": "vote",
"attributes": {
"external_identifier": "1",
"count": 1,
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"donation_pool": {
"data": {
"id": 1,
"type": "donations_pool"
}
},
"user": {
"data": {
"id": "1",
"type": "user"
}
}
}
}Resource Unique Identifier
Resource type
Profile email address
An url that can be used to start the enrollment flow for the user.
{
"id": 1,
"type": "provisional_profile",
"attributes": {
"email": "user@example.test",
"enrollment_url": "https://giving-site.goodcoins.io/..."
}
}Resource Unique Identifier
Resource type
Amount
Date when donation resource was created (UTC Timezone)
Description
Reference Identifier
A Cycle containes all the charities for a program in a given interval of time.
Resource Unique Identifier
Resource type
The cycle name
The cycle custom identifier
The cycle year
The cycle start date
The cycle end date
The cycle creation date
This resource tracks market brakedown of charities for a cycle
Market id
Market type
Market name
Market size
Market Identifier
The amount of donations that this the goal for this market
Total amount of donations made on this market in a cycle
The number of streches achieved
The amount of donations in the last strech
Market creation date
The total number of donations that have been made in this market
A charity that is part of a cycle.
Resource identifier
Resource type
Global unique identfier for this charity
Charity name
Charity description
Charity EIN
Charity website url
Charity logo url with support for different screen densities
The congratulation message that the charity is providing to the donnors after a donation has been made
Street of the regitered charity
Region/state of the registered charity
City of the regitered charity
Zip Code of the regitered charity
The goal set for the charity
Current goal progress, the sum of donations for this market in this cycle.
The number of streches achieved
The amount of donations in the last strech
This charity has been marked as beeing a national one.
The total number of donations that have been received by this cause.
The Cycle Donation resource. A donation can be created towards a Charity from a Cycle.
Note: The external_identifier field can be used to cross reference donation data with your own informational systems. You can use any values for this field as it isn’t validated (presence, uniquness, etc). You could use it to reference donations records on your system by passing here an identifier relate to your donation.
Note: The external_user_identifier field can be used to corss reference the user identity with your own identity management system. This can be used when the API integration is configured to accept anonymized donations.
Resource Unique Identifier
Resource type
An identifier provided by the API client for cross referencing resources
An identifier provided by the API client for cross referecing donor identity.
Donation amount in client’s currency
The date when a transaction that tirggered the donation occurred and that can be reconciled using the external_identifier.
Date when donation resource was created (UTC Timezone)
{
"id": "94182444-b1cc-11e8-9643-eb44a3760e11",
"type": "cycle_donation",
"attributes": {
"external_identifier": "1",
"external_user_identifier": "0c6d1cb691dfb86b",
"amount": 100,
"reference_date": "2018-05-16T03:15:34.000Z",
"created_at": "2018-05-16T03:16:34.000Z"
},
"relationships": {
"beneficiary": {
"data": {
"id": 1,
"type": "cycle_charity"
}
}
}
}This is the response received when a request is made API endpoint that is expected to return a resource
Body
Unique Identifier of a resource
Resource type
Resource attributes
For resources having relationships to other resources this object will containt references to those resources
Key will be the resource name
Resource Unique Identifier
Resource type
Key will be the collection name
Under the data key there will be an arrat of Resource Identifier objects
Resource Unique Identifier
Resource type
Unique Identifier of a resource
Resource type
Resource attributes
For resources having relationships to other resources this object will containt references to those resources
Key will be the resource name
Resource Unique Identifier
Resource type
Key will be the collection name
Under the data key there will be an arrat of Resource Identifier objects
Resource Unique Identifier
Resource type
This is the response received when a request is made API endpoint that is expected to return a collection of resources
Body
Unique Identifier of a resource
Resource type
Resource attributes
For resources having relationships to other resources this object will containt references to those resources
Key will be the resource name
Resource Unique Identifier
Resource type
Key will be the collection name
Under the data key there will be an arrat of Resource Identifier objects
Resource Unique Identifier
Resource type
Unique Identifier of a resource
Resource type
Resource attributes
For resources having relationships to other resources this object will containt references to those resources
Key will be the resource name
Resource Unique Identifier
Resource type
Key will be the collection name
Under the data key there will be an arrat of Resource Identifier objects
Resource Unique Identifier
Resource type
Total number of resources in the collection
Total number of pages
Current page number
API link to the next page
API link to the last page
API link to the first page
API link to the previous page
This is the response received when a request is made with an invalid JSON document sent
Body
Examples
{
"errors": [
{
"status": "400",
"code": "invalid",
"title": "Could not properly parse the data received",
"detail": "JSON parse error - Expecting property name at line 1 column 2 (char 1)."
}
]
}This is the response received when a request is made with invalid API credentials
Body
Examples
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "You are not authorized to access this endpoint"
}
]
}This is the response received when a request is made with valid API credentials towards an API endpoint or resource you do not have access to.
Body
Examples
{
"errors": [
{
"status": "403",
"code": "forbidden",
"title": "Forbidden",
"detail": "You are not allowed to access this endpoint"
}
]
}This is the response received when a request is made with valid API credentials towards an API endpoint or resource that cannot be found.
Body
Examples
{
"errors": [
{
"status": "404",
"code": "notfound",
"title": "Resource not found",
"detail": "The requested resource was not found"
}
]
}This is the response received when a request is made with valid API credentials towards and API endpoint that resulted in a resource being invalid. For example when you try to create a donation without providing an amount
Body
Type of problem encountered
Which part of the request document caused the error
When the error is triggered by an attribute given use this to reference that attribute
When the error is triggered by a query parameter use this to reference the parameter
Generic title describing the error
Description of the error specific for this particular case
Examples
{
"errors": [
{
"code": "blank",
"source": {
"pointer": "/data/attributes/amount",
},
"title": "Value cannot be empty",
"detail": "You must specify an amount in order to create a donation"
}
]
}This is the response received when a request is made towards API but the API could not fulfill the request due to factors on the API side. Do not expect for this request to respond with a response body.