Using the Global Financials APIs

The API is REST based. All requests must be made over HTTPS. All request and response body data is in JSON format.

Authentication

Global Financials API calls utilize access tokens, generated from a consumer key/secret combination, for authentication (based on the Client Credentials Grant flow of the OAuth 2 specification.

For details on generating an access Token, please see the Authentication Guide.

Requests

The Global Financials API is based on REST principles: data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, the API strives to use appropriate HTTP verbs for each action:

VERB	DESCRIPTION
POST	Used for performing an action such as Authenticate or Search Financials

For each API, the API Reference page includes URI, Verb used, description, code sample, request parameters, and response parameters.

The code sample is automatically generated from the request parameters. Code should be verified before use; all parameters are included in the sample, even if they are mutually exclusive.

Responses

All data is received as a JSON object. Responses for each API are documented on its API Reference page.

Security

OAuth 2 Token based authentication. Valid client ID and secret key need to be used to access the tokens for enabling transactions through API.

Global Financials recomments Transport Security Layer version 1.2 (TLS 1.2)

API Best Practices

We strongly recommend that you design your integration with the following guidelines in mind:

• Handle errors appropriately
• Implement logging

Handle errors appropriately

A successful error handling strategy requires that your integration recognize the difference between errors that can potentially be resolved by retrying the request and errors that should never be retried automatically. The HTTP status code that is returned with each response is your first indication as to the outcome of the request.

Error status code	Meaning	Retry?
2xx	Request was successful.	n/a
4xx	A problem with the request prevented it from being executed successfully.	Never automatically retry the request.
5xx	The request was properly formatted, but the operation failed on the application for run time scenarios mainly environmental errors.	In some scenarios, requests could be automatically retried using exponential backoff. In other cases, requests should not be retried.

A list of error codes and recommendations for handling those are available under Resources: Error and Information Codes.

Implement logging

We strongly recommend that you design your integration such that it is capable of logging API requests and responses. Having access to the raw requests and responses (including detailed error codes and error messages) when API issues emerge will streamline troubleshooting and accelerate time to resolution.

The following examples show the type of information that your application should log for API requests and responses.

Request: verb, URI, header(s), request body

	POST https://api.globalfinancials.com/generateToken
	Authorization: TOKEN-VALUE
	Content-Type: application/json
	{
		"documentID": "716dece0-a30a-4e0f-9619-b1cdc1e7eeb3",
		"creationTimestamp": "2018-11-28T12:29:32.313+0000",
		"requestType": "result",
		"sessionID": "user908@bank.com",
		"matchCriteria": {
			"businessAddress": {
			 "countryCode":  [ 111]
			},
			"numberOfEmployees": {
			"fromValue":  10000
			}
		},
		"pagination": {
		"startRecordNumber":  1,
		"numberOfRecords":  10
		}
	}

Response: HTTP status code, response body

200,
	{
		"documentID": "THORAPI_20190408104100017",
		"requestID": "716dece0-a30a-4e0f-9619-b1cdc1e7eeb3",
		"creationTimestamp": "2019-04-08 10:41:17.017Z",
		"responseType": "result",
		"transactionStatus": {
			"isFailure": true,
			"statusCode": "404",
			"statusMessage": "No match found"
		},
		"pagination": {
			"startRecordNumber":  1,
			"numberOfRecords":  10
		},
		"sessionID":  "user908@bank.com"
	}

API Troubleshooting

Should you encounter issues with the API while building an integration using a particular programming language (e.g., Java, C#, PHP, Python), keep the following troubleshooting techniques in mind:

1. Try executing the same API Request using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw Request / Response.
2. If you receive a similar error when you execute the Request using cURL or Postman, there is likely an issue with the Request format or contents. Refer to the API Documentation for the correct format and contents.
3. If you are able to execute the Request successfully using cURL or Postman, then it is likely that the Request your code is sending is different than what you intend. You’ll need to compare the successful Request with the unsuccessful Request that your code is generating.
   
   • Examine the Request that your code is sending (including the HTTP verb, URI, headers, and Request body) and the Response that it’s receiving back from Smartsheet (including the HTTP status code, headers, and response body).
   • Inspect the full trace of Request and Response in the log file. Compare the Request that your application is logging with the successful Request from cURL or Postman, and update your code to correct any discrepancies.
   • Try a tool like Fiddler or Charles HTTP Proxy to inspect the full trace of Request and Response. Compare the Request trace that your application generates with the successful Request from cURL or Postman, and update your code to correct any discrepancies.