General notes

Register application

Applications that want to access the figo Connect must be registered beforehand. If you’d like to create a partner application, please email us. We will generate a client identifier and client secret for your application.

Calling the figo Connect API

All requests to the figo Connect API must contain an access token in the Authorization: Bearer HTTP header. Before any of the REST endpoints can be called, an access token has to be requested from the figo Connect autorization server.

Command line demo

Try out our figo Connect API:

curl -H "Authorization: Bearer ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo22ujRI\
P_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ" https://api.figo.me/rest/accounts

figo SDK

Integrate figo Connect easier and faster with one of our figo SDKs.

Language Download
Python https://github.com/figo-connect/python-figo
Ruby https://github.com/figo-connect/ruby-figo
Node.js https://github.com/figo-connect/node-figo
PHP https://github.com/figo-connect/php-figo
Java https://github.com/figo-connect/java-figo

Error handling

As long as not specified otherwise, standard HTTP error codes are used for error handling.

HTTP code Description
200 Success
301 Redirect
400 Malformed request
401 Missing, invalid or expired access token. A new access token must be requested or the user must be re-authenticated.
403 Insufficient permission
404 Requested object does not exist
405 Unexpected request method
503 Exceeded rate limit

Version information

/version

Description

Get figo Connect server version.

Request URL
GET https://api.figo.me/version
Response
product_name Product name of figo Connect server.

product_version Product version of figo Connect server.

product_environment Environment of figo Connect server; Possible values are production, sandbox or staging.

ssl_fingerprints List of SHA-1 fingerprints of all valid figo Connect server SSL/TLS certificates.

Sample JSON response

{
  "product_name": "figo Connect",
  "product_version": "929f8b8",
  "product_environment": "production",
  "ssl_fingerprints": [
    "A6:FE:08:F4:A8:86:F9:C1:BF:4E:70:0A:BD:72:AE:B8:8E:B7:78:52",
    "AD:A0:E3:2B:1F:CE:E8:44:F2:83:BA:AE:E4:7D:F2:AD:44:48:7F:1E",
    "B0:8B:03:C2:07:93:B3:B8:5B:A0:15:03:FB:A4:71:7D:86:9C:8F:63"
  ]
}

Authentication

We use OAuth 2.0 for authentication and authorization.

/auth/code

Description
Before your application can request an access token, it must first obtain an authorization code.

Your application initiates the authorization process by directing the user’s web browser to a popup window of figo Connect.

The popup window will ask the user for his or her figo Account credentials. The user will see the permissions as specified in scope and a list of accounts to choose from. If the user grants access to your application, the figo Connect server sends an authorization code to the callback URL by redirecting the browser to redirect_uri.

Popup window URL
https://api.figo.me/auth/code
Parameters
response_type mandatory This parameter must be set to code.

client_id mandatory The client identifier obtained during application registration.

redirect_uri The authorization code will be sent to this callback URL. It must match one of the URLs registered during application registration.

scope A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions agreed during application registration. If this parameter is omitted, the permissions agreed during application registration are used in place.

state mandatory Any kind of string that will be forwarded in the response message. It serves two purposes: The value is used to maintain state between this request and the callback, e.g. it might contain a session ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

Sample popup window URL

https://api.figo.me/auth/code?response_type=code&\
client_id=CaESKmC8MAhNpDe5rvmWnSkRE_7pkkVIIgMwclgzGcQY&\
scope=accounts%3Dro+balance%3Dro+transactions%3Dro&\
state=xqD6gjWygsBlF0uB
Redirect on success
code The authorization code for obtaining an access token. It can only be used once and will expire after a few minutes.

state The state parameter from the request.

Sample redirect

GET /callback?code=OkA7jUIro6JNmOF7i5f7QmepCLLoIFug6621ADHLMjK6oimFYK1x5xy5\
rl0wVZNkheCv5nMkH3hZ0v24immWGaI5Gc0P0F9ue0sgnV7DqwvM&state=xqD6gjWygsBlF0uB
Redirect on error
error One of the error codes as defined in section 4.1.2.1 of the OAuth 2.0 specification.

error_description A human-readable error message intended for the application developer.

state The state parameter from the request.

/auth/token (authorization code)

Description
After your application obtained an authorization code, it may exchange the authorization code for an access token.

The Authorization: Basic HTTP header must contain the client identifier as username and the client secret as password.

Request URL
POST https://api.figo.me/auth/token
Parameters
grant_type mandatory This parameter must be set to authorization_code.

code mandatory The authorization code returned from the initial request.

redirect_uri If the callback URL was specified in the initial request, then it must also be included in this request.

Sample request

grant_type=authorization_code&code=OkA7jUIro6JNmOF7i5f7QmepCLLoIFug6621ADHL\
MjK6oimFYK1x5xy5rl0wVZNkheCv5nMkH3hZ0v24immWGaI5aGc0P0F9ue0sgnV7DqwvM
Response on success
access_token The access token

token_type This response parameter is set to Bearer.

expires_in The remaining live time of the access token in seconds.

refresh_token A refresh token that may be used to request new access tokens. Refresh tokens remais valid until the user revokes access to your application. This response parameter is only present if the permission offline has been requested in the authorization code request.

scope A space delimited set of requested permissions.

Sample JSON response

{
  "access_token": "ASHWLIkouP2O6_bgA2wWReRhletgWKHYjLqDaqb0LFfamim9RjexTo\
                   22ujRIP_cjLiRiSyQXyt2kM1eXU2XLFZQ0Hro15HikJQT_eNeT_9XQ",
  "token_type":"Bearer",
  "expires_in": 3600,
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPtmobD2p_1epZUYmidZAO\
                    oT1TkFspMQOzNlCZpIrZREHrSdYeObea3Qda7hk2Q6PO5BEVF3GBh0",
  "scope": "accounts=ro balance=ro transactions=ro offline"
}
Response on error
error One of the error codes as defined in section 5.2 of the OAuth 2.0 specification.

error_description A human-readable error message intended for the application developer.

/auth/token (refresh token)

Description
Request new access token with refresh token. New access tokens can be obtained as long as the user has not revoked the access granted to your application.

The Authorization: Basic HTTP header must contain the client identifier as username and the client secret as password.

Request URL
POST https://api.figo.me/auth/token
Parameters
grant_type mandatory This parameter must be set to refresh_token.

refresh_token mandatory The refresh token returned from the authorization code exchange.

scope A space delimited set of requested permissions. The requested permissions can be narrower but not broader than the permissions supplied in the authorization code request. If this parameter is omitted, the permissions supplied in the authorization code request are used in place.

Sample request

grant_type=refresh_token&refresh_token=RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPtm\
obD2p_1epZUYmidZAOoT1TkFspMQOzNlCZpIrZREHrSdYeObea3Qda7hk2Q6PO5BEVF3GBh0
Response
The response is similar to the response documented in the previous section.

/auth/revoke

Description
When a user unsubscribes from your application, your application must also revoke its access to figo Connect.

No Authorization HTTP header is required for this task.

The supplied token can either be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refesh token will also be revoked.

Request URL
GET https://api.figo.me/auth/revoke
Parameters
token A refresh token or access token.

Sample request

token=RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPtmobD2p_1epZUYmidZAOoT1TkFspMQOzNlC\
ZpIrZREHrSdYeObea3Qda7hk2Q6PO5BEVF3GBh0
Response
A sucessfull response contains no content. On error the following response parameters will be returned:

error One of the error codes invalid_request or invalid_grant.

error_description A human-readable error message intended for the application developer.

User management

/rest/user (GET)

Description
Get figo Account settings.
Permissions
None required
Request URL
GET https://api.figo.me/rest/user
Response
name First and last name.

email Email address.

Sample JSON request

{
  "name": "John Doe",
  "email": "demo@figo.me",
}

REST API

Bank accounts and transactions can easily accessed via a RESTful web service with JSON objects.

/rest/accounts (GET)

Description
List all accounts that the user has chosen to share with your application.
Permissions
accounts=ro
Request URL
GET https://api.figo.me/rest/accounts
Response
accounts List of account objects.

Sample JSON response

{
  "accounts": [
    {
      "account_id": "A1.1",
      "bank_id": "B1.1",
      "name": "Girokonto",
      "owner": "figo",
      "account_number": "4711951500",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "currency": "EUR",
      "iban": "DE67900900424711951500",
      "bic": "DEMODE01",
      "type": "Giro account",
      "icon": "https://api.figo.me/assets/accounts/demokonto.png",
      "status": {
        "code": 1,
        "sync_timestamp": "2013-04-11T19:16:00.000Z",
        "success_timestamp": "2013-04-11T19:16:00.000Z"
      }
    },
    {
      "account_id": "A1.2",
      "bank_id": "B1.1",
      "name": "Sparkonto",
      "owner": "figo",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "currency": "EUR",
      "iban": "DE05900900424711951501",
      "bic": "DEMODE01",
      "type": "Savings account",
      "icon": "https://api.figo.me/assets/accounts/demokonto.png",
      "status": {
        "code": -1,
        "message": "Could not get transactions.",
        "sync_timestamp": "2013-04-11T19:16:00.000Z",
        "success_timestamp": "2013-04-11T15:16:00.000Z"
      }
    }
  ]
}

/rest/accounts/{account_id} (GET)

Description
Get information about a particular bank account.
Permissions
accounts=ro
Request URL
GET https://api.figo.me/rest/accounts/{account_id}

account_id Internal figo Connect account ID.

Response
A single account object.

Sample JSON response

{
  "account_id": "A1.1",
  "bank_id": "B1.1",
  "name": "Girokonto",
  "owner": "figo",
  "account_number": "4711951500",
  "bank_code": "90090042",
  "bank_name": "Demobank",
  "currency": "EUR",
  "iban": "DE67900900424711951500",
  "bic": "DEMODE01",
  "type": "Giro account",
  "icon": "https://api.figo.me/assets/accounts/demokonto.png",
  "status": {
    "code": 1,
    "sync_timestamp": "2013-04-11T19:16:00.000Z",
    "success_timestamp": "2013-04-11T19:16:00.000Z"
  }
}

/rest/accounts/{account_id}/balance (GET)

Description
Get balance and account limits.
Permissions
balance=ro
Request URL
GET https://api.figo.me/rest/accounts/{account_id}/balance

account_id Internal figo Connect account ID.

Response
balance Account balance; This response parameter will be omitted if the balance is not yet known.

balance_date Bank server timestamp of balance; This response parameter will be omitted if the balance is not yet known.

credit_line Credit line.

monthly_spending_limit User-defined spending limit.

status Synchronization status object.

Sample JSON response

{
  "balance": 3250.31,
  "balance_date": "2013-04-11T12:00:00.000Z",
  "credit_line": 0.00,
  "monthly_spending_limit": 1000.00,
  "status": {
    "code": 1,
    "sync_timestamp": "2013-04-11T19:16:00.000Z",
    "success_timestamp": "2013-04-11T19:16:00.000Z"
  }
}

/rest/transactions

Description
Get transactions of all accounts that the user has chosen to share with your application.
Permissions
transactions=ro
Request URL
GET https://api.figo.me/rest/transactions
Parameters
since This parameter can either be a transaction ID or a date.

If this parameter is a transaction ID, then the transactions which were booked after the referenced transaction will be returned in the response.

If this parameter is a date, then the transactions which were booked on or after this date will be returned in the response.

start_id Do only return transactions which were booked after the start transaction ID. In combination with the count parameter this can be used to paginate the result list.

count Limit the number of returned transactions. The default number is 1000. In combination with the start_id parameter this can be used to paginate the result list.

offset Offset into the implicit list of transactions used as starting point for the returned transactions. In combination with the count parameter this can be used to paginate the result list.

include_pending This flag indicates whether pending transactions should be included in the response. Pending transactions are always included as a complete set, regardless of the since parameter. Before caching a copy of the pending transactions, all existing pending transactions for the same account must be removed from the local cache.

Example request

since=2013-04-10&include_pending=1
Response
transactions List of transaction objects.

status Synchronization status object. The error messages of all accounts will be concatenated to a single error message. For oldest timestamp of all accounts will be used.

Sample JSON response

{
  "transactions": [
    {
      "transaction_id": "T1.1.24",
      "account_id": "A1.1",
      "name": "Dr. House Solutions GmbH",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": -300.00,
      "currency": "EUR",
      "booking_date": "2013-04-10T12:00:00.000Z",
      "value_date": "2013-04-10T12:00:00.000Z",
      "purpose": "Miete Vertragsnr. 12993",
      "type": "Direct debit",
      "booking_text": "Lastschrift",
      "booked": true,
      "creation_timestamp": "2013-04-10T08:21:36.000Z",
      "modification_timestamp": "2013-04-11T13:54:02.000Z",
      "visited": true
    },
    {
      "transaction_id": "T1.2.15",
      "account_id": "A1.2",
      "name": "Girokonto",
      "account_number": "4711951500",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": 200.00,
      "currency": "EUR",
      "booking_date": "2013-04-11T12:00:00.000Z",
      "value_date": "2013-04-11T12:00:00.000Z",
      "purpose": "Sparen",
      "type": "Standing order",
      "booking_text": "Dauerauftrag",
      "booked": true,
      "creation_timestamp": "2013-04-11T13:54:42.000Z",
      "modification_timestamp": "2013-04-11T13:54:42.000Z",
      "visited": false
    }
  ],
  "status": {
    "code": -1,
    "message": "Could not get transactions.",
    "sync_timestamp": "2013-04-11T19:16:00.000Z",
    "success_timestamp": "2013-04-11T15:16:00.000Z"
  }
}

/rest/accounts/{account_id}/transactions

Description
Get transactions of a particular account.
Permissions
transactions=ro
Request URL
GET https://api.figo.me/rest/accounts/{account_id}/transactions

account_id Internal figo Connect account ID.

Parameters
The same parameters as documented in the previous section.
Response
transactions List of transaction objects.

status Synchronization status object.

Sample JSON response

{
  "transactions": [
    {
      "transaction_id": "T1.1.25",
      "account_id": "A1.1",
      "name": "Rogers Shipping, Inc.",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": -17.90,
      "currency": "EUR",
      "booking_date": "2013-04-11T12:00:00.000Z",
      "value_date": "2013-04-11T12:00:00.000Z",
      "purpose": "Ihre Sendung 0815 vom 01.03.2012, Vielen Dank",
      "type": "Transfer",
      "booking_text": "Überweisung",
      "booked": false,
      "creation_timestamp": "2013-04-11T13:54:02.000Z",
      "modification_timestamp": "2013-04-11T13:54:02.000Z",
      "visited": true
    },
    {
      "transaction_id": "T1.1.24",
      "account_id": "A1.1",
      "name": "Dr. House Solutions GmbH",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": -300.00,
      "currency": "EUR",
      "booking_date": "2013-04-10T12:00:00.000Z",
      "value_date": "2013-04-10T12:00:00.000Z",
      "purpose": "Miete Vertragsnr. 12993",
      "type": "Direct debit",
      "booking_text": "Lastschrift",
      "booked": true,
      "creation_timestamp": "2013-04-10T08:21:36.000Z",
      "modification_timestamp": "2013-04-11T13:54:02.000Z",
      "visited": true
    }
  ],
  "status": {
    "code": 1,
    "sync_timestamp": "2013-04-11T19:16:00.000Z",
    "success_timestamp": "2013-04-11T19:16:00.000Z"
  }
}

Payments

/rest/accounts/{account_id}/payments (GET)

Description
List all payments known to the figo Connect server.
Permissions
payments=ro
Request URL
GET https://api.figo.me/rest/accounts/{account_id}/payments

account_id Internal figo Connect account ID.

Parameters
since This parameter can either be a payment ID or a date.

If this parameter is a payment ID, then the payments which were created after the referenced payment will be returned in the response.

If this parameter is a date, then the payments which were created on or after this date will be returned in the response.

count Limit the number of returned payments. The default number is 1000.

Example request

since=2013-06-15
Response
payments List of payment objects. If one of the payment objects is a container for multiple payments, then the field container will be set to the empty list. The complete payment object can be fetched with /rest/accounts/{account_id}/payments/{payment_id}.

Sample JSON response

{
  "payments": [
    {
      "payment_id": "P1.1.234",
      "account_id": "A1.1",
      "type": "Transfer",
      "name": "figo",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "amount": 0.89,
      "currency": "EUR",
      "purpose": "Thanks for all the fish.",
      "text_key": 51,
      "text_key_extension": 0,
      "notification_recipient": "",
      "creation_timestamp": "2013-07-16T13:53:56.000Z",
      "modification_timestamp": "2013-07-16T13:53:56.000Z"
    }
  ]
}

/rest/accounts/{account_id}/payments (POST)

Description
Insert payment into payment list.
Permissions
payments=rw
Request URL
POST https://api.figo.me/rest/accounts/{account_id}/payments

account_id Internal figo Connect account ID.

Parameters
type mandatory Payment type

name Name of creditor or debtor; This field is mandatory unless container is set, in which case this field will be ignored.

account_number Account number or IBAN of creditor or debtor; This field is mandatory unless container is set, in which case this field will be ignored.

bank_code Bank code or BIC of creditor or debtor; This field is mandatory unless container is set, in which case this field will be ignored.

amount Order amount; This field is mandatory unless container is set, in which case this field will be ignored.

currency Three-character currency code; This field defaults to the account’s currency and will be ignored if container is set.

purpose Purpose text; This field will be ignored if container is set.

text_key DTA text key; This field will be ignored if container is set.

text_key_extension DTA text key extension; This field will be ignored if container is set.

notification_recipient Recipient of the payment notification, should be an email address.

scheduled_date Scheduled date specified according to ISO 8601. Recurring time intervals for standing orders are specified according ISO 8601, too.

container List of payment objects. This payment can only be a container for multiple payments if the field supported_file_formats of the payment parameters is not empty.

Sample JSON request

{
  "type": "Transfer",
  "name": "figo",
  "account_number": "4711951501",
  "bank_code": "90090042",
  "amount": 0.89,
  "purpose": "Thanks for all the fish."
}
Response
A single payment object.

Sample JSON response

{
  "payment_id": "P1.1.234",
  "account_id": "A1.1",
  "type": "Transfer",
  "name": "figo",
  "account_number": "4711951501",
  "bank_code": "90090042",
  "bank_name": "Demobank",
  "amount": 0.89,
  "currency": "EUR",
  "purpose": "Thanks for all the fish.",
  "text_key": 51,
  "text_key_extension": 0,
  "notification_recipient": "",
  "creation_timestamp": "2013-07-16T13:53:56.000Z",
  "modification_timestamp": "2013-07-16T13:53:56.000Z"
}

/rest/accounts/{account_id}/payments/{payment_id} (GET)

Description
Get information about a particular payment.
Permissions
payments=ro
Request URL
GET https://api.figo.me/rest/accounts/{account_id}/payments/{payment_id}

account_id Internal figo Connect account ID.

payment_id Internal figo Connect payment ID.

Response
A single payment object.

Sample JSON response

{
  "payment_id": "P1.1.234",
  "account_id": "A1.1",
  "type": "Transfer",
  "name": "figo",
  "account_number": "4711951501",
  "bank_code": "90090042",
  "bank_name": "Demobank",
  "amount": 0.89,
  "currency": "EUR",
  "purpose": "Thanks for all the fish.",
  "text_key": 51,
  "text_key_extension": 0,
  "notification_recipient": "",
  "creation_timestamp": "2013-07-16T13:53:56.000Z",
  "modification_timestamp": "2013-07-16T13:53:56.000Z"
}

/rest/accounts/{account_id}/payments/{payment_id} (PUT)

Description
Modify payment in list.

If the payments has already been submitted to the bank server, i.e. the field submission_timestamp is set, then the only field that can be modified with this method is transaction_id.

Permissions
payments=rw
Request URL
PUT https://api.figo.me/rest/accounts/{account_id}/payments/{payment_id}

account_id Internal figo Connect account ID.

payment_id Internal figo Connect payment ID.

Parameters
name Name of creditor or debtor

account_number Account number of creditor or debtor

bank_code Bank code of creditor or debtor

amount Order amount

currency Three-character currency code

purpose Purpose text

text_key DTA text key

text_key_extension DTA text key extension

notification_recipient Recipient of the payment notification, should be an email address.

scheduled_date Scheduled date specified according to ISO 8601. Recurring time intervals for standing orders are specified according ISO 8601, too.

container List of payment objects. This payment can only be a container for multiple payments if the field supported_file_formats of the payment parameters is not empty.

transaction_id This field is set to the transaction ID that has been matched to the payment.

Sample JSON request

{
  "amount": 8.99,
  "purpose": "Thanks for all the fish."
}
Response
A sucessfull response contains no content.

/rest/accounts/{account_id}/payments/{payment_id} (DELETE)

Description
Delete payment from list.
Permissions
payments=rw
Request URL
DELETE https://api.figo.me/rest/accounts/{account_id}/payments/{payment_id}

account_id Internal figo Connect account ID.

payment_id Internal figo Connect payment ID.

Response
A sucessfull response contains no content.

/rest/accounts/{account_id}/payments/{payment_id}/submit

Description
Submit payment to bank server.

This call will return immediately. Your application must either direct the user’s web browser to a pop window of figo Connect with the URL /task/start, or moniter the progress itself by using the task token with /task/progress.

Permissions
submit_payments
Request URL
POST https://api.figo.me/rest/accounts/{account_id}/payments/{payment_id}/submit

account_id Internal figo Connect account ID.

payment_id Internal figo Connect payment ID.

Parameters
redirect_uri mandatory At the end of the submission process a response will be sent to this callback URL.

state mandatory Any kind of string that will be forwarded in the callback response message. It serves two purposes: The value is used to maintain state between this request and the callback, e.g. it might contain a session ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

tan_scheme_id mandatory TAN scheme ID of user-selected TAN scheme.

Sample JSON request

{
  "redirect_uri": "https://api.figo.me/callback",
  "state": "4HgwtQP0dnX4UjPf",
  "tan_scheme_id": "M1.1.1"
}
Response
task_token Task token.

Sample JSON response

{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKz\
                 LdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}

Synchronization

During synchronization the figo Connect server fetches the current balance, recent transactions and scheduled payments from the banks, payment providers or financial service providers.

Usually the figo Connect server synchronizes all bank accounts on a daily basis. However, the synchronization has to be triggered manually either if the user disabled automatic synchronization or there was a PIN error or the PIN has not been saved on the figo Connect server.

/rest/sync

Description
Your application initiates the synchronization process by requesting a task token.
Permissions
balance=ro or transactions=ro or payments=ro
Request URL
POST https://api.figo.me/rest/sync
Parameters
redirect_uri mandatory At the end of the synchronization process a response will be sent to this callback URL.

state mandatory Any kind of string that will be forwarded in the callback response message. It serves two purposes: The value is used to maintain state between this request and the callback, e.g. it might contain a session ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

disable_notifications This flag indicates whether notifications should be sent to your application. Since your application will be notified by the callback URL anyway, you might want to disable any additional notifications.

if_not_synced_since If this parameter is set, only those accounts will be synchronized, which have not been synchronized within the specified number of minutes.

account_ids Only sync the accounts with these IDs

account_filter Python re expression to filter the accounts to be synced. The re will be applied to the bank codes and bank names

Sample JSON request

{
  "redirect_uri": "https://api.figo.me/callback",
  "state": "4HgwtQP0dnX4UjPf",
  "disable_notifications": true,
  "if_not_synced_since": 15
}
Response
task_token Task token.

Sample JSON response

{
  "task_token": "YmB-BtvbWufLnbwgAVfP7XfLatwhrtu0sATfnZNR7LGP-aLXiZ7BKz\
                 LdZI--EqEPnwh_h6mCxToLEBhtA7LVd4uM4gTcZG8F6UJs47g6kWJ0"
}

/task/start

Description
Start communication with bank server. After your application obtained a task token, it may direct the user’s web browser to a popup window of figo Connect.

The popup window will ask the user for his or her account PIN, perform two-factor authentication or ask for a TAN. It also displays status messages as the task proceeds.

After the task has been finished, the figo Connect server sends a response message to the callback URL by redirecting the browser to redirect_uri. Your application can then use the REST API to retrieve the current balance, recent transactions and scheduled payments.

Popup window URL
https://api.figo.me/task/start?id={id}

id Task token from the initial request.

Redirect
state The state parameter from the request.

Sample redirect

GET /callback?state=4HgwtQP0dnX4UjPf

Notifications

Whenever the bank account of a user received new transactions, the figo Connect server can asynchronously notify your application with webooks.

/rest/notifications (GET)

Description
List all notifications your application did register for the user.
Request URL
GET https://api.figo.me/rest/notifications
Response
notifications List of registered notification objects.

Sample JSON response

{
  "notifications": [
    {
      "notification_id": "N1.7",
      "observe_key": "/rest/transactions?include_pending=0",
      "notify_uri": "https://api.figo.me/callback",
      "state": "cjLaN3lONdeLJQH3"
    }
  ]
}

/rest/notifications (POST)

Description
Register your application to receive notifications.
Request URL
POST https://api.figo.me/rest/notifications
Parameters
observe_key mandatory Notification key

notify_uri mandatory Notification messages will be sent to this URL.

state mandatory Any kind of string that will be forwarded in the notification message. It serves two purposes: The value is used to maintain state between this request and the notification message, e.g. it might contain an user ID from your application. The value should also contain a random component, which your application checks to mitigate cross-site request forgery.

Sample JSON request

{
  "observe_key": "/rest/transactions?include_pending=0",
  "notify_uri": "https://api.figo.me/callback",
  "state": "cjLaN3lONdeLJQH3"
}
Response
notification_id Internal figo Connect notification ID.

Remainder Properties of the newly created notification

Sample JSON response

{
  "notification_id": "N1.7"
  "observe_key": "/rest/transactions?include_pending=0",
  "notify_uri": "https://api.figo.me/callback",
  "state": "cjLaN3lONdeLJQH3"
}

/rest/notifications/{notification_id} (DELETE)

Description
Unregister notification.
Request URL
DELETE https://api.figo.me/rest/notifications/{notification_id}

notification_id Internal figo Connect notification ID.

Response
A sucessfull response contains no content.

Webhooks

Description
Whenever the figo Connect server sends a notification message to your webhook URL, your application can update its accounts, balance or transactions with the REST API.
Webhook parameters
notification_id Internal figo Connect notification ID from the notification registration response.

observe_key Notification key

state The state parameter from the notification registration request.

Sample webhook message

{
  "notification_id": "N1.7",
  "observe_key": "/rest/transactions?include_pending=0",
  "state": "cjLaN3lONdeLJQH3"
}

Notification keys

Account balance

Description
Triggered when the respective account balance changes.
Permissions
balance=ro
Notification key
/rest/accounts/{account_id}/balance

account_id Internal figo Connect account ID.

Parameters
inferior_limit Trigger if the balance of the account is under the provided value.

Account transactions

Description
Triggered when an account has received new transactions.
Permissions
transactions=ro
Notification key
/rest/accounts/{account_id}/transactions

account_id Internal figo Connect account ID.

Parameters
include_pending Trigger not only for booked but also for pending transactions.

more_expenses_then_deposits Trigger only if the sum of expenses in the current month exceeds the sum of deposits in the same time. Only combinable with include_pending.

current_month_expense_goal Trigger only if the sum of expenses in the current month exceeds the provided value. Only combinable with include_pending.

single_expense_goal Trigger only for expense transactions exceeding the provided value. Only combinable with include_pending.

single_deposit_goal Trigger only for expense transactions exceeding the provided value. Only combinable with include_pending.

purpose Trigger only on transactions whose purpose contains the provided value. Only combinable with include_pending.

name Trigger only on transactions whose sender/receiver name contains the provided value. Only combinable with include_pending.

All transactions

Description
Triggered when any of the accounts that the user has chosen to share with your application has received new transactions.
Permissions
transactions=ro
Notification key
/rest/transactions
Parameters
include_pending Trigger not only for booked but also for pending transactions.

Test notification

Description
Triggered immediately. This special notification key can be used to test the delivery of notifications. The notification message will be sent immediately and no registration occurs.
Notification key
/rest/notifications/test

Common JSON objects

Permissions

Permission Description
accounts=ro Read-only access to the list of accounts and account details.
balance=ro Read-only access to the account balance.
transactions=ro Read-only access to the account transactions.
offline Access figo Connect when the user is not present.

Account object

Field Description
account_id Internal figo Connect account ID
bank_id Internal figo Connect bank ID
name Account name
owner Account owner
auto_sync This flag indicates whether the account will be automatically synchronized.
account_number Account number
bank_code Bank code
bank_name Bank name
currency Three-character currency code
iban IBAN
bic BIC
type Account type
icon Account icon URL
status Synchronization status object

Account types

Account type constants
Giro account
Savings account
Credit card
Loan account
PayPal
Cash book
Unknown

Transaction object

Field Description
transaction_id Internal figo Connect transaction ID
account_id Internal figo Connect account ID
name Name of originator or recipient
account_number Account number of originator or recipient
bank_code Bank code of originator or recipient
bank_name Bank name of originator or recipient
amount Transaction amount
currency Three-character currency code
booking_date Booking date
value_date Value date
purpose Purpose text
type Transaction type
booking_text Booking text
booked This flag indicates whether the transaction is booked or pending.
creation_timestamp Internal creation timestamp on the figo Connect server.
modification_timestamp Internal modification timestamp on the figo Connect server.
visited This flag indicates whether the transaction has already been marked as visited by the user.

Transaction types

Transaction type constants
Transfer
Standing order
Direct debit
Salary or rent
Electronic cash
GeldKarte
ATM
Charges or interest
Unknown

Synchronization status

Field Description
code Internal figo Connect status code
message Human-readable error message. The figo Connect server tries to localize the message as requested by the Accept-Language HTTP header.
sync_timestamp Timestamp of last synchronization.
success_timestamp Timestamp of last successful synchronization.

Status codes

Code Description
1 Success
-1 General error
-2 PIN error

Registered notification object

Field Description
notification_id Internal figo Connect notification ID from the notification registration response.
observe_key Notification key
notify_uri Notification messages will be sent to this URL.
state The state parameter from the notification registration request.