Givinga API (1.0)

Download OpenAPI specification:Download

The Givinga API allows corporations to programmatically send and receive data, such as charity, account, and donation data, over a RESTful, JSON-based, HTTP API.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Authentication

The API authenticates requests using HTTP basic authentication as described in RFC 7617. Primarily, this means that each request MUST include an Authorization header with the value Basic <token>, where <token> is the string <username>:<password> encoded in base 64.

Because basic authentication credentials are not encrypted, and because the data may contain sensitive information, the request MUST be made over HTTPS using TLS version 1.2 or higher.

HTTP basic authentication is intended for server-to-server communication and MUST NOT be used from the client side, where end users and malicious parties could potentially gain access to the unencrypted credentials.

Request Format

Each action or resource in the API is associated with an endpoint and an HTTP method. Each of these defines a specific request format that MUST be used when making requests to the API. In general, requests with bodies (e.g. POST or PUT) MUST have the content type application/json and MUST have a body consisting of a single JSON value (typically an object or array, as defined by the specification here).

Request URIs are typically of the form https://hub.givinga.com/api/v1/<resource>, where <resource> is the path to the specific resource or action being requested. Note that credentials may be partner-specific. Contact Givinga for credentials.

The Givinga API allows corporations to programmatically send and receive data, such as charity, account, and donation data, over a RESTful, JSON-based, HTTP API.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Base URL's

Development:

test.givinga.com

Production:

hub.givinga.com

Create User Account

Creates a new user account associated with the remote ID.

Request Body schema: application/json
firstName
string

The user's first name.

lastName
string

The user's last name.

email
string

The user's email address.

remoteId
string

A remote identifier for tracking what user ID this account belongs to in a remote system.

countryCode
string

The country code for the user.

preferredCurrency
string

Currency the user's transaction activity will default too unless otherwise specified.

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Smith",
  • "email": "jsmith@example.com",
  • "remoteId": "631456",
  • "countryCode": "SGP",
  • "preferredCurrency": "CAD"
}

Response samples

Content type
application/json
{
  • "userId": 1025,
  • "donorAccountNumber": "15006196",
  • "employeeAccountNumber": "15269643",
  • "d4dEmployeeAccountNumber": "15531497"
}

Update User Account

Updates the user account with the given Givinga ID. MUST be the Givinga ID returned in the userId field of AddUserRequestResponse, not the remote ID.

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Request Body schema: application/json

The same payload as creating a user account.

firstName
string

The user's first name.

lastName
string

The user's last name.

email
string

The user's email address.

remoteId
string

A remote identifier for tracking what user ID this account belongs to in a remote system.

countryCode
string

The country code for the user.

preferredCurrency
string

Currency the user's transaction activity will default too unless otherwise specified.

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Smith",
  • "email": "jsmith@example.com",
  • "remoteId": "631456",
  • "countryCode": "SGP",
  • "preferredCurrency": "CAD"
}

Response samples

Content type
application/json
{
  • "message": "Error in request body: ..."
}

Deactivate or Reactivate User Account

Updates the status of the account with the requested ID. The ID MUST be the Givinga ID returned in the userId field of AddUserRequestResponse, not the remote ID. A body of true sets the account status to active, and a body of false sets the status to inactive. Inactive accounts cannot make new transactions, but the account still exists, and uniqueness requirements and other constraints still apply. Accounts cannot be deleted through the API.

Accounts created through the API are active by default, so you should only need to use this endpoint for deactivating and reactivating accounts.

path Parameters
userId
required
string
header Parameters
Content-Type
required
string
Request Body schema: application/json

A JSON Boolean indicating whether the account should be active (true) or inactive (false).

boolean

Responses

Request samples

Content type
application/json
false

Response samples

Content type
application/json
{
  • "message": "User not found."
}

Account Details By Email

Returns information about the account identified by email address.

query Parameters
email
required
string

The email account associated with the Givinga user. Not case sensitive. MUST be URL encoded.

Responses

Response samples

Content type
application/json
{
  • "userId": 1025,
  • "donorAccountNumber": "15006196",
  • "employeeAccountNumber": "15269643",
  • "d4dEmployeeAccountNumber": "15531497",
  • "firstName": "John",
  • "lastName": "Smith",
  • "email": "jsmith@example.com",
  • "remoteId": "631456",
  • "active": true,
  • "countryCode": "SGP"
}

User Profile

A Givinga account represents a single pool of money, similar to a bank account, and has an 8-digit account number. A single user-account may have multiple Givinga account numbers associated with it.

query Parameters
numbers
required
string

A comma-separated list of account numbers to query.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Charity Search

query Parameters
eins
string

A comma-separated list of charity eins to filter for.

filterText
string

Used to filter charities by text (matching the charity name, category, cause EIN, tag line, mission, street address, city, state, zip, phone, or general email fields).

categoryIds
string

A comma-separated list of category IDs the charities should match.

causeIds
string

A comma-separated list of cause IDs the charities should match.

overallRatings
string

A comma-separated list of ratings (0, 1, 2, 3, or 4) the charities should match.

length
integer <int32>

The maximum number of results to return (capped at 500). Defaults to 10.

ascending
boolean

Whether or not the results should be sorted in ascending order. Defaults to true.

orderBy
string

What field to sort the results by ("name", or "overallScore"). Defaults to overallScore.

startIndex
string

The index of the first record in the result set to return. Defaults to 0.

sponsored
boolean

If true, only charities sponsored by the organization will be included in the result set. Defaults to false.

matched
boolean

If true, only charities matched by the organization will be included in the result set. Defaults to false.

volunteer
boolean

If true, only charities that are approved for volunteer hours by the organization will be included in the result set. Defaults to false.

countryCodes
string

A comma-separated list of 3-letter country codes the charities should match.

Responses

Response samples

Content type
application/json
{
  • "count": "32",
  • "charities": [
    ]
}

Charities by EIN

query Parameters
numbers
required
string

A comma-separated list of charity eins to query.

sponsored
boolean

If true, only charities sponsored by the organization will be included in the result set. Defaults to false.

matched
boolean

If true, only charities matched by the organization will be included in the result set. Defaults to false.

volunteer
boolean

If true, only charities that are approved for volunteer hours by the organization will be included in the result set. Defaults to false.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Charity Categories

Retrieves a list of the charity category mappings.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Charity Causes

Retrieves a list of the charity cause mappings.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transactions

Allows an API user to view transaction history for specific account numbers or for all accounts in a corporation within a date range. If you want to see transactions for a whole corporation, exclude the accountNumbers and provide a date range.

query Parameters
accountNumbers
string

A comma-separated list of account numbers to query. Omit this parameter to see transactions for the whole corporation.

startDate
string

A date string for the start date of the date range.

endDate
string

A date string for the end date of the date range.

activityId
integer <int32>

Including this parameter will filter the list results to include only transactions with this activityId.

activityId2
integer <int32>

Including this parameter will filter the list results to include only transactions with this activityId2.

activityId3
integer <int32>

Including this parameter will filter the list results to include only transactions with this activityId3.

offline
boolean

Optional flag for returning only offline transactions. Defaults to false

currency
string

If present, each transaction will include a conversion to this currency in the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transfer Funds

Allows the transfer of funds between Givinga accounts. Transfers always take place between accounts in the same corporation as the API user. The only account types currently supported are Employee and Corporate. The sender account can either be the API user's own, or another employee/corporate account.

header Parameters
Content-Type
required
string
Request Body schema: application/json
sender
string

The unique account number for the Givinga account where the funds will be sent from. This can be either a corporate account, or an employee account.

receiver
string

The unique account number for the Givinga account where the funds will be sent to. This can be either a corporate account, or an employee account.

amount
number <double>

The amount to be transferred. Will be treated as currency and converted to USD (cents) based on current rates.

currency
string

The currency that the amount is represented in.

Responses

Request samples

Content type
application/json
{
  • "sender": "15006196",
  • "receiver": "15531497",
  • "amount": 20000,
  • "currency": "USD"
}

Response samples

Content type
application/json
{
  • "message": "Insufficient funds to make transfer"
}

Match Caps

query Parameters
currency
string

If present, a conversion of the match caps to this currency will be returned.

Responses

Response samples

Content type
application/json
{
  • "corporateCap": 21825.12,
  • "employeeCap": 130.39,
  • "corporationConversion": {
    },
  • "conversion": {
    }
}

Corporate Match Statistics

query Parameters
currency
string

If present, a conversion of the match caps to this currency will be returned.

Responses

Response samples

Content type
application/json
{
  • "matchedAmount": 98473.76,
  • "corporationConversion": {
    },
  • "conversion": {
    }
}

User Match Statistics

query Parameters
userIds
required
string

A comma-separated list of Givinga User IDs.

currency
string

If present, a conversion of the match caps to this currency will be returned.

startDate
string

A date string for the start date of the date range. If provided, the url should also have the endDate as well.

endDate
string

A date string for the end date of the date range. If provided, the url should also have the startDate as well.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Match Requests

query Parameters
accountNumbers
required
string

A comma-separated list of account numbers to query.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Show Available Matching Funds

path Parameters
userId
required
number <double>

A Givinga user ID.

query Parameters
currency
string

If present, a conversion of the match caps to this currency will be returned.

Responses

Response samples

Content type
application/json
{
  • "userId": 2392,
  • "availableFunds": 250
}

Submit Funded Donation

header Parameters
Content-Type
required
string
Request Body schema: application/json
accountNumber
string

The unique account number of the employee making the donation.

charityId
number <double>

The id of the charity the donation should be made to.

projectId
number <double>

The id of the Global Giving Project the donation should be made to.

offline
boolean

Indicates whether or not the donation was made within or outside of Givinga.

matchRequested
boolean

Indicates whether the donation should be matched by the corporate account tied to the user.

date
string

The date the offline donation was made. Only accepted if offline is true.

amount
number <double>

The amount of money to be donated to the charity. Will be treated as currency and converted to USD based on current rates.

currency
string

The currency that the amount is represented in.

activityId
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId2
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

activityId3
string

An optional value set by the client that can be used to associate the Givinga transaction with data on the client side.

anonymity
string

One of Full Transparency, Partial Transparency, or Anonymous. If not provided, defaults to Anonymous.

notes
string

Notes that will be sent to the charity along with the donation.

properties
object

A key, value pairing for adding additional metadata to transactions

Responses

Request samples

Content type
application/json
{
  • "accountNumber": "23456789",
  • "charityId": 10002,
  • "projectId": 124,
  • "offline": false,
  • "matchRequested": false,
  • "date": "MM-dd-yyyy",
  • "amount": 300.13,
  • "currency": "CAD",
  • "activityId": "abcd1234",
  • "activityId2": "abcd1234",
  • "activityId3": "abcd1234",
  • "anonymity": "Full Transparency",
  • "notes": "this is an example",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Retrieve Exchange Rates

Retrieve the exchange rate that Givinga has stored for a given currency

query Parameters
currency
required
string

The currency to retrieve an exchange rate for.

Responses

Response samples

Content type
application/json
{
  • "JPY": 1000.324
}