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. See How to test section for details.

Base API URL

Production environment: https://public-api.tgbwidget.com
Sandbox environment: https://public-api.sandbox.thegivingblock.com

Passing Access Token

See details on how to authenticate in Authentication section.

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 The Giving Block 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"  
}