📖
API reference

General information
The TGB Public API is a RESTful API. Our API has resource-oriented URLs, it accepts JSON-encoded data and returns JSON-encoded data. We use standard HTTP response codes to communicate status of the request to the consumers and standard verbs to manipulate the resources.
The API is designed to be integrated with one of the consumer's back-end services. It won't work with browsers since our CORS policy doesn't allow this and it would require consumers to store API login and password on the browser side.
It's recommended to use Staging environment during the development to build your application. Donations made to the Staging environment use real crypto networks so you can test everything end-to-end.
Base API URL
Staging environment: https://public-api.tgb-preprod.com
Production environment: https://public-api.tgbwidget.com
Passing Access Token
API uses Bearer authentication (also called “token authentication”) therefore Access Token should be passed in a Authorization Header with a Bearer prefix, example:
Authorization: Bearer YOUR_ACCESS_TOKEN
Example:
if your Access Token is abcdef123456 then token should be passed like this
curl --request GET \
  --url https://public-api.tgbwidget.com/v1/organization/99 \
  --header 'Authorization: Bearer abcdef123456'
Responses format
All responses from the API will be returned in JSON format.
Successful request’s response format:
{
  "data": { 
    "someProperty": "some data"
  },
  "requestId": "uuid for tracing purposes"
}
To simplify investigations for any sort of errors please send requestId to the TheGivingBlock team
Whenever error happens, it will be returned in a following format:
{
  "data": {
    "errorMessage": string;
    "errorType": string;
    "meta": {
      "errorCode": string;
    }
  },
  "requestId": string;
}
Description of every property:
Property
Always present?
Description
errorMessage
Yes
Human readable description of error. Do not use it for programmatic error handling because these messages are likely to be changed over time
errorType
Yes
Human readable description of error. Do not use it for programmatic error handling because these messages are likely to be changed over time
meta
Yes
Type of error, for example: err.authentication, err.forbidden, err.validation, etc.
meta.errorCode
No
In some cases this error code will be present in the response. This property along with errorType can be used for programmatic error handling. See Error Codes section of documentation for list of available errors
Example of Error response when validation error happened:
{
  "data": {
    "errorMessage": "Request body validation failed",
    "errorType": "err.validation",
    "meta": {
      "errorCode": "INVALID_REQUEST"
      "validationErrorMessage": "\"login\" is required",
      "failedAttributes": [
        {
          "attributeName": "login",
          "message": "\"login\" is required",
          "path": [
            "login"
          ]
        }
      ]
    }
  },
  "requestId": "325a3fa0-d3b1-433c-b36a-573368cdbe2e"
}
Here is another example of Error response when you pass expired Access Token
{
  "data": {
    "errorMessage": "Auth token is invalid. Please refresh tokens or log in again",
    "errorType": "err.forbidden",
    "meta": {
      "errorCode": "INVALID_JWT_TOKEN"
    }
  },
  "requestId": "0a2420df2-544c-47fd-a501-a69ebbdf1493"
}
Endpoints documentation
post
https://public-api.tgbwidget.com
/v1/login
Login
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/login \
  --header 'Content-Type: application/json' \
  --data '{
	"login": "your-login",
	"password": "your-password"
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/login',
    headers: {'Content-Type': 'application/json'},
    data: {
        login: 'your login',
        password: 'your password'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes: 
INVALID_REQUEST in case if invalid POST body passed
INVALID_LOGIN_CREDENTIALS if incorrect pair of login/password passed
INACTIVE_USER if user is restricted to access the API
post
https://public-api.tgbwidget.com
/v1/refresh-tokens
RefreshTokens
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/refresh-tokens \
  --header 'Content-Type: application/json' \
  --data '{
	"refreshToken": "your-refresh-token-value"
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/refresh-tokens',
    headers: {'Content-Type': 'application/json'},
    data: {
        refreshToken: 'your refresh token'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes: 
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Refresh Token not found or revoked
INACTIVE_USER if user is restricted to access the API
get
https://public-api.tgbwidget.com
/v1/organizations/list
GetOrganizationsList
Examples:
cURL
Node.js
curl --request GET \
  --url https://public-api.tgbwidget.com/v1/organizations/list \
  --header 'Authorization: Bearer your-access-token'
import axios from "axios";
​
const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/organizations/list',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes: 
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)
EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens
UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user
INACTIVE_USER if user is restricted to access the API
get
https://public-api.tgbwidget.com
/v1/organization/:id
GetOrganizationById
Examples:
cURL
Node.js
curl --request GET \
  --url https://public-api.tgbwidget.com/v1/organization/1189133200 \
  --header 'Authorization: Bearer your-access-token'
import axios from "axios";
​
const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/organization/1189133201',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes: 
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)
EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens
UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user
INACTIVE_USER if user is restricted to access the API
post
https://public-api.tgbwidget.com
/v1/organization/:id/widget-snippet
GetWidgetSnippet
Appearance examples
Both screenshots represent an embedded appearance. You need to use script the endpoint response in order to display the embedded widget. The first screen shows the old widget UI(uiVersion=2). The second screen shows the latest UI (uiVersion=2). 
​
​
​
Example how what the trigger button looks like. depending on the passed uiVersion, a popup will contain either an old or a new UI.
​
​
​
​
Request examples
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/organization/1/widget-snippet \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"uiVersion": 2,
	"button": {"text": "Support US"}
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/organization/99/widget-snippet',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        uiVersion: 2,
        button: { text: "Support Us" }
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
​
​
get
https://public-api.tgbwidget.com
/v1/crypto-to-usd-rate?currency={currencyCode}
Get Crypto Rate
Examples:
cURL
Node.js
curl --request GET \
  --url 'https://public-api.tgbwidget.com/v1/crypto-to-usd-rate?currency=ETH' \
  --header 'Authorization: Bearer your-access-token'
import axios from "axios";
​
const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/crypto-to-usd-rate',
    params: {currency: 'ETH'},
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes: 
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)
EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens
UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user
INACTIVE_USER if user is restricted to access the API
post
https://public-api.tgbwidget.com
/v1/deposit-address
CreateDepositAddress
receiptEmail is optional. The Giving Block won't send receipt email If organization has isReceiptEnabled as false (available in response from GetOrganizationsList method) or your API account has default setting that tells us to not send any receipt emails for transactions created through the API. In case if you need The Giving Block to send receipt emails - ask us to set up your API account accordingly and make sure you send receiptEmail in CreateDepositAddress request.
If donation is not anonymous - fields firstName, lastName, addressLine1, addressLine2, country, state, city, zipcode are required.
Returned pledgeId field is an unique identifier for the donation. It will be sent along with transactions' notifications as pledgeId to link events to donations.
Some notes on qrCode property: it is base64 encoded QR code image that represents depositAddress . That being said, when you decode that QR code, you'll get a text that is in depositAddress field. This image can be used to display on your donation page to give to the donor an easy way to enter depositAddress to make a donation.
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/deposit-address \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"organizationId": 99,
	"isAnonymous": true,
	"pledgeCurrency": "btc",
	"pledgeAmount": "0.000001"
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/deposit-address',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        organizationId: 1,
        isAnonymous: false,
        pledgeCurrency: 'ETH',
        pledgeAmount: '0.1',
        receiptEmail: '[email protected]',
        firstName: 'Test',
        lastName: 'User',
        addressLine1: 'Street 4321',
        addressLine2: 'Apt 55',
        country: 'US',
        state: 'NY',
        city: 'New York',
        zipcode: '442452'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes:
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)
EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens
UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user
INACTIVE_USER if user is restricted to access the API
post
https://public-api.tgbwidget.com
/v1/currencies/list
List Currencies
Examples
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/currencies/list \
  --header 'Authorization: Bearer your-access-token'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/currencies/list',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes: 
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)
EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens
UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user
INACTIVE_USER if user is restricted to access the API​
post
https://public-api.tgbwidget.com
/v1/transaction/list
GetTransactionList
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/transaction/list \
  --header 'Authorization: Bearer {your-access-token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "pagination": {
    "page": 1,
    "itemsPerPage": 100
  },
  "filters": {
    "date": {
      "from": 1664632635000
    }
  }
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/transaction/list',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        pagination: {page: 1, itemsPerPage: 100},
        filters: {date: {from: 1664632635000}}
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible errors
Error Codes:
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)
EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens
UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user
INACTIVE_USER if user is restricted to access the API
post
https://public-api.tgbwidget.com
/v1/organizations/total-raised
GetTotalRaisedStats
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/organizations/total-raised \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
    	"organizationIds": [99]
    }
  }'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/organizations/total-raised',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        pagination: {page: 1, itemsPerPage: 100},
        filters: {organizationIds: [1000120214]}
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
Possible Error Codes:
INVALID_REQUEST in case if invalid POST body passed
INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)
EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens
UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user
INACTIVE_USER if user is restricted to access the API
post
https://public-api.tgbwidget.com
/v1/donation/fiat
CreateFiatDonationPledge
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/donation/fiat \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"organizationId": "99",
	"isAnonymous": true,
	"pledgeAmount": "10"
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/donation/fiat',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {organizationId: '10120152', isAnonymous: true, pledgeAmount: '10'}
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
post
https://public-api.tgbwidget.com
/v1/donation/fiat/charge
ChargeFiatDonationPledge
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/donation/fiat/charge \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"pledgeId": "434b9bfb-69f1-4f19-baf7-55f41e331faf",
	"cardToken": "tok_Nc4ZfL926ZT4X32xtBspxf0y3"
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/donation/fiat/charge',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        pledgeId: '9534a8a5-80a6-4f4c-a3a4-848c9e921ff8',
        cardToken: 'tok_Nc4ZfL926ZT4X32xtBspxf0y3'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
get
https://public-api.tgbwidget.com
/v1/stocks/brokers
GetBrokersList
Examples:
cURL
Node.js
curl --request GET \
  --url https://public-api.tgbwidget.com/v1/stocks/brokers \
  --header 'Authorization: Bearer your-auth-token'
import axios from "axios";
​
const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/stocks/brokers',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
post
https://public-api.tgbwidget.com
/v1/stocks/tickers
GetTickersList
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/stocks/tickers \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"pagination": {
		"itemsPerPage": 25,
		"page": 1
	}
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/stocks/tickers',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {pagination: {itemsPerPage: 25, page: 1}}
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
get
https://public-api.tgbwidget.com
/v1/stocks/ticker-cost
GetTickerCost
Examples:
cURL
Node.js
curl --request GET \
  --url 'https://public-api.tgbwidget.com/v1/stocks/ticker-cost?ticker=FOUR' \
  --header 'Authorization: Bearer your-auth-token'
import axios from "axios";
​
const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/stocks/ticker-cost',
    params: {ticker: 'FOUR'},
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
post
https://public-api.tgbwidget.com
/v1/donation/stocks
CreateStockDonationPledge
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/donation/stocks \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"organizationId": "99",
	"assetSymbol": "AAAU",
	"assetDescription": "Goldman Sachs Physical Gold ETF Shares",
	"pledgeAmount": 100,
	"receiptEmail": "[email protected]",
	"firstName": "John",
	"lastName": "Doe",
	"addressLine1": "Tukan Street 4321",
	"addressLine2": "Apt 51",
	"country": "US",
	"state": "NY",
	"city": "New York",
	"zipcode": "89000",
	"phoneNumber": "55555555"
}'
import axios from "axios";
​
const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/donation/stocks',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        organizationId: '99',
        assetSymbol: 'AAAU',
        assetDescription: 'Goldman Sachs Physical Gold ETF Shares',
        pledgeAmount: 100,
        receiptEmail: '[email protected]',
        firstName: 'John',
        lastName: 'Doe',
        addressLine1: 'Tukan Street 4321',
        addressLine2: 'Apt 51',
        country: 'US',
        state: 'NY',
        city: 'New York',
        zipcode: '89000',
        phoneNumber: '55555555'
    }
};
​
axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});
post
https://public-api.tgbwidget.com
/v1/stocks/submit
SubmitStockDonation
Examples:
cURL
Node.js
curl --request POST \
  --url https://public-api.tgbwidget.com/v1/stocks/submit \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"donationUuid": "6118018e-6beb-4e04-a3e2-d22fd9aaec0f",
	"brokerName": "ameriprise",
	"brokerageAccountNumber": "12345678",
	"brokerContactName": "John Doe",
	"brokerEmail": "[email protected]",
	"brokerPhone": "65515254"
}'
Property	Always present?	Description
errorMessage	Yes	Human readable description of error. Do not use it for programmatic error handling because these messages are likely to be changed over time
errorType	Yes	Human readable description of error. Do not use it for programmatic error handling because these messages are likely to be changed over time
meta	Yes	Type of error, for example: err.authentication, err.forbidden, err.validation, etc.
meta.errorCode	No	In some cases this error code will be present in the response. This property along with errorType can be used for programmatic error handling. See Error Codes section of documentation for list of available errors