Finigree for Developers
Review the Terms of Use before continuing.
Finigree offers JSON-based API's for accessing public and trending timelines (with optional update search functionality), as well comment threads relating to a particular media item.
Endpoints & Summaries
Timelines: https://demo.network.finigree.com/t/[public/trending]?api[&q=query]
When calling a Timeline API, the "q" GET parameter is optional, but if provided, will force the API to only output results matching a particular search string. One use of this parameter might be to locate public updates syndicated to an interest timeline using hashtags (URL-encoded as %23).
A maximum of 10 updates will be returned from a Timeline API call. To retrieve earlier updates, you may set an offset value for the API call using the "px" GET parameter. For example, if you wanted to skip the first 25 updates, you would set the "px" parameter equal to 25.
Example output from a Timeline API call is provided below, with supplementary notes printed in green and optional output printed in orange.
"Timeline": [
{
"Attachment": [ (Only when an attachment exists)
"Type": "Picture",
"Link URL": "http://subdomain.domain.ext/...",
"Thumbnail URL": "http://subdomain.domain.ext/..."
],
"Reposted From": [ (Only when "Reposted" is true)
"User ID": "2",
"Display Name": "Eve Evington"
],
"Reposted From (Original Poster)": [ (Only when "Reposted" is true and the content was not directly reposted from the original user)
"User ID": "3",
"Display Name": "Paul Paulson"
],
"Reposted": true,
"System Update": false,
"Update ID": 1,
"User ID": 1,
"User Profile URL": "http://subdomain.domain.ext/...",
"User Thumbnail": "http://subdomain.domain.ext/...",
"Display Name": "Bob Bobbington",
"PG Restricted": false, (If true, do not display to viewers under the age of 13)
"Message": "Example message.", (Finigree [markup] items will not be translated to HTML.)
"Timestamp": 1425713657,
"Positive Vibes": 21,
"Negative Vibes": 2,
"Comments": 15
}
],
"Pagination": {
"Previous": false, (Are there more pages before this?)
"Next": false (Are there more pages after this?
}
}
Example call: https://demo.network.finigree.com/t/public?api
Comments: https://demo.network.finigree.com/comment/view_all?api&media_type=media_type&media_id=media_id
When comments are collapsed (when data for all comments in a series cannot be provided at once), the last non-excluded comment in a series will have of “More” attribute containing the URL to an API endpoint for retrieving additional items in the series, at that comment's same indentation level. Multiple comments in the result set may have a “More” attribute, as multiple partial comment threads can be returned in a single response.
Example output from a Comments API call is provided below. In this sample output, the media item has one first-level comment, which itself has received a single (second-level) reply.
"Comments": [
{
"Comment ID": 1,
"Comment Depth": 1, (First-level comments are at depth 1, replies to those are depth 2, etc.)
"User ID": 1,
"User Profile URL": "http:\/\/subdomain.domain.ext\/...",
"User Thumbnail": "http:\/\/subdomain.domain.ext\/...",
"Display Name": "Bob Bobbington",
"PG Restricted": false,
"Private": false, (Is this comment only visible to the currently logged-in user?)
"Message": "Test comment.",
"Timestamp": 1425856216,
"Positive Vibes": 0,
"Negative Vibes": 0
},
{
"Comment ID": 2,
"Comment Depth": 2,
"User ID": 2,
"User Profile URL": "http:\/\/subdomain.domain.ext\/...",
"User Thumbnail": "http:\/\/subdomain.domain.ext\/...",
"Display Name": "Eve Evington",
"PG Restricted": false,
"Private": false,
"Message": "A second-level reply to \"Test comment.\"",
"Timestamp": 1425856244,
"Positive Vibes": 0,
"Negative Vibes": 0
}
]
}
Example call: https://demo.network.finigree.com/comment/view_all?api&media_type=2&media_id=1
Finigree also offers a number of authenticated, JSON-based API services. Authenticated API services allow their clients to authenticate as an Finigree user, or to conduct secure transactions with Finigree on behalf of the API client, directly. In order to use authenticated API services, a client must first establish a client ID, obtaining a "secret key" and "auth code" in the process. (Client registration can be performed from the API Settings page.)
Once you have an API client ID, secret key, and auth code, in order to authenticate as an Finigree user, you will need the user's Finigree account ID, as well as a permissions grant on the part of the user that allows your application to access the account functionality you would like to work with. You can request account permissions from the user using a special endpoint, documented below.
Authenticated requests should include a GET or POST argument, cid, set to the API client ID. In addition, there must be a parcel argument containing an encrypted JSON object. If the request does not involve authenticating as a Finigree user, this JSON object will have one data member, timestamp, containing the current UNIX timestamp, as reported by the requesting server. If the request does involve taking actions on behalf of a Finigree user, it must also include a user_id data member identifying the Finigree user account being worked with.
When encrypting the JSON message (the parcel argument), clients should use AES-256-CBC (Rijndael-128) encryption, using their client secret key as the encryption key. Clients must then generate a keyed-hash message authentication code (HMAC) using the SHA-512 algorithm, employing their client auth code (only) as the secret key. Once the cipher text and HMAC values have been obtained, a complete parcel body should be formed by concatenating the initialization vector (from when the cipher text was being generated), cipher text, and HMAC (in that order), and then Base64-encoding the result: Base64(IV+cipherText+HMAC).
Sample authenticated API client code in PHP is provided below.
// Set the API client secret key.
$secret_key = 'INSERT_API_CLIENT_SECRET_KEY_HERE';
// Set the API client authentication code.
$auth_code = 'INSERT_API_CLIENT_AUTH_CODE_HERE';
// Create the JSON message object identifying the user account we wish to access.
$message_object = json_encode(['user_id' => INSERT_USER_ID_HERE, 'timestamp' => time()], JSON_UNESCAPED_UNICODE);
// Encrypt and authenticate the message object.
$packed_key = pack('H*', $secret_key);
$iv_size = openssl_cipher_iv_length('AES-256-CBC');
$iv = openssl_random_pseudo_bytes($iv_size);
$cipher_text = openssl_encrypt($message_object, 'AES-256-CBC', $packed_key, 0, $iv);
if ($cipher_text === false) { /* Could not encrypt data. */ }
$auth = hash_hmac('sha512', $cipher_text, $auth_code, true);
$parcel = base64_encode($iv.$cipher_text.$auth);
// Set the API endpoint.
$endpoint = 'https://demo.network.finigree.com/t/network?api&cid=INSERT_API_CLIENT_ID_HERE&parcel='.rawurlencode($parcel);
// Connect to the API endpoint and retrieve the encrypted response message.
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $endpoint);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_MAXREDIRS, 3);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_USERAGENT, ini_get('user_agent'));
$response = curl_exec($curl);
curl_close($curl);
// Decrypt the response.
$response = base64_decode($response);
if ($response === false) { /* Could not decode base64 response. */ }
$iv = substr($response, 0, $iv_size);
$auth = substr($response, -64);
$cipher_text = substr($response, $iv_size, -64);
if ($auth !== hash_hmac('sha512', $cipher_text, $auth_code, true)) { /* Response authentication failed. */ }
$json = openssl_decrypt($cipher_text, 'AES-256-CBC', $packed_key, 0, $iv);
if ($json === false) { /* Could not decrypt cipher text. */ }
// Decode JSON message object.
$message = json_decode($json, true);
// Take a look at what we received.
var_dump($message);
?>
User Account Permissions
To request API permissions from a user, simply forward the user to the following GET endpoint: https://demo.network.finigree.com/login?cid=API_CLIENT_ID&scope=SCOPE_CODE_CSV
The available permission scope codes are as follows:
- DISBURSE: This permission allows a third-party application to record file disbursements to your account.
- SSO: This permission allows the requesting application to sign users into your account without the need for a username or password.
- TIMELINE: This permission allows the third-party application to read your various social timelines.
After the user has signed into their Finigree account (as applicable) and approved the permissions request, they will be redirected back to your application (using the Permissions Redirect URL provided for your API client). A GET argument, token, will be appended to the redirect URL. This token will serve as a unique identifier for the permissions request, and allows your client to verify the permissions grant and retrieve the user's Finigree account ID, assuming the permissions request was accepted.
Permissions Verification Endpoint: https://demo.network.finigree.com/api/permission_verification?api&cid=api_client_id&parcel=encrypted_parcel
When validating user account permissions, the parcel object should include the required timestamp data member, as well as a token data member containing the permission request token provided to your application.
Example output from a valid call to this endpoint is provided below."Permission Verification": [
{
"Scope": "SSO,TIMELINE", (You should validate that the permissions granted match the needs of your client.)
"Status": "APPROVED", (Possible values are APPROVED, DECLINED, or PENDING.)
"User ID": 1 (This field will only be included if “Status” is set to APPROVED.)
}
]
}
Cross-domain Single Sign-On
Temporary use SSO tokens are used to sign users into the Finigree network via a third-party application. To generate an SSO token, the API client must have the “SSO” permission over the associated user's account. Each SSO token generated expires automatically after 30 seconds, or immediately upon use.
Once an SSO token has been generated, direct the user to the following endpoint to execute it: https://demo.network.finigree.com/login/sso?cid=API_CLIENT_ID&token=SSO_TOKEN
SSO Token Generation Endpoint: https://demo.network.finigree.com/api/sso_token?api&cid=api_client_id&parcel=encrypted_parcel
When requesting an SSO token, the parcel object should include the required timestamp and user_id data members.
Example output from a valid call to this endpoint is provided below."SSO Token": [
{
"Token": "...", (SSO tokens are 100 characters in length.)
"User ID": 1
}
]
}
In the event that an error arises during an API call (other than HTTP status code 404 and 500 errors), the API output will be a non-JSON-encoded string beginning with either $API-ERR: or $ERR:, where the first represents an error that should not be displayed to the user, while the latter should (the message that follows will be an unabridged, display-ready error message). A complete list of $API-ERR messages is presented below, along with explanations for each in italics.
- $API-ERR:DATA TIMEOUT communications with data services were unresponsive
- $API-ERR:GENERAL a general application error was encountered
- $API-ERR:AUTHENTICATION FAILURE the API client could not be authenticated with the data provided
- $API-ERR:PERMISSION ERROR a user or API client permissions violation occurred
- $API-ERR:DAMAGED PARCEL the authenticated request message body could not be decoded
- $API-ERR:DATA MISSING the request is missing required data
- $API-ERR:DATA INVALID the request included invalid arguments in the parcel body
- $API-ERR:MODULE N/A a module does not allow programmatic access
- $API-ERR:NO MODULE no module was identified with the API request
- $API-ERR:FEATURE N/A a module feature does not allow programmatic access
Endpoint: https://demo.network.finigree.com/t/rss?type=[public/trending/user]&rss=1[&eid=user_id]
Each item in a feed will contain the following elements, which adhere to the RSS 2.0 specification: "description", "comments", "guid", and "pubDate".
In the event of any feed generation errors, the system will attempt to output an empty (item-less) feed with a channel title of "Syndication Error".