Links API
Endpoints
List Links
This endpoint returns all your Links
Headers
Header |
Value |
---|---|
|
|
|
|
Responses
200 OK
{
"success": true,
"count": int,
"items": [
{
"token": str,
"name": str,
"redirect_uri": str,
"company_name": str,
"terms_and_conditions_url": str | null,
"privacy_policy_url": str | null,
"active": bool,
"pending_code_count": int,
},
...
],
}
List of Links.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
500 Internal Error
{
"error": "Internal Error"
}
Create Link
Create a new Link, which will be available at the URL
http://platform.flanks.io/link?token=<token>
Headers
Header |
Value |
---|---|
|
|
|
|
Body (JSON encoded)
Parameter |
Type |
Value |
---|---|---|
|
String |
URI where the user will be redirected after the credentials are created. |
|
String | null |
A unique name to identify the Link. If it's not provided, it will be equal to the Link's token. |
|
String | null |
The name of the company is the owner of the data and their agreements (Terms and Conditions and Privacy Policy). If not set, it will default to the name of your Company in Flanks. |
|
String | null |
A custom URL for the Terms and Conditions to be accepted by the end user. If not set, it will default to Flank's default document. |
|
String | null |
A custom URL for the Privacy Policy to be accepted by the end user. If not set, it will default to Flank's default document. |
(*) Mandatory Parameters
Responses
200 OK
{
"success": true,
"data": {
"token": str,
"name": str,
"redirect_uri": str,
"company_name": str,
"terms_and_conditions_url": str | null,
"privacy_policy_url": str | null,
"active": bool,
"pending_code_count": int,
}
}
Returns the newly created Link.
400 Validation Error
{
"success": false,
"error": {
"code": "ValidationError",
"details": [
{ "error_type": str, "field": str },
...
],
},
"trace_id": str,
}
Some fields are missing or incorrect.
400 Duplicated Name
{
"success": false,
"error": {
"code": "DuplicatedName",
},
"trace_id": str,
}
The name provided for the Link already exists.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
500 Internal Error
{
"error": "Internal Error"
}
Edit Link
Edit the attributes of a Link. All the attributes are optional, and only the ones provided will
be updated. To delete an attribute, set it to null
.
Headers
Header |
Value |
---|---|
|
|
|
|
Body (JSON encoded)
Parameter |
Type |
Value |
---|---|---|
|
String |
Unique identifier for the Link. |
|
String |
URI where the user will be redirected after the credentials are created. |
|
String | null |
A unique name to identify the Link. If it's set to null, it will be equal to the Link's token. |
|
String | null |
The name of the company is the owner of the data and their agreements (Terms and Conditions and Privacy Policy). If set to null, it will default to the name of your Company in Flanks. |
|
String | null |
A custom URL for the Terms and Conditions to be accepted by the end user. If set to null, it will default to Flank's default document. |
|
String | null |
A custom URL for the Privacy Policy to be accepted by the end user. If set to null, it will default to Flank's default document. |
(*) Mandatory Parameters
Responses
200 OK
{
"success": true,
"data": {
"token": str,
"name": str,
"redirect_uri": str,
"company_name": str,
"terms_and_conditions_url": str | null,
"privacy_policy_url": str | null,
"active": bool,
"pending_code_count": int,
}
}
Returns the updated values for the Link.
400 Validation Error
{
"success": false,
"error": {
"code": "ValidationError",
"details": [
{ "error_type": str, "field": str },
...
],
},
"trace_id": str,
}
Some fields are missing or incorrect.
400 Duplicated Name
{
"success": false,
"error": {
"code": "DuplicatedName",
},
"trace_id": str,
}
The name provided for the Link already exists.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
404 Link Not Found
{
"success": false,
"error": {
"code": "LinkNotFound",
},
"trace_id": str,
}
There's no link with the given token.
500 Internal Error
{
"error": "Internal Error"
}
Delete Link
Delete a Link. Note that only Links with no pending link codes can be deleted.
Headers
Header |
Value |
---|---|
|
|
|
|
Body (JSON encoded)
Parameter |
Type |
Value |
---|---|---|
|
String |
Unique identifier for the Link. |
(*) Mandatory Parameters
Responses
200 OK
{
"success": true,
"data": {
"token": str,
}
}
400 Pending Codes to Exchange
{
"success": false,
"error": {
"code": "PendingCodesToExchange",
},
"trace_id": str,
}
The Link cannot be deleted because it has pending codes to exchange.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
404 Link Not Found
{
"success": false,
"error": {
"code": "LinkNotFound",
},
"trace_id": str,
}
There's no Link with the given token.
500 Internal Error
{
"error": "Internal Error"
}
Pause Link
A paused Link cannot be accessed to add new credentials, but it can be edited and their pending codes can be exchanged.
Headers
Header |
Value |
---|---|
|
|
|
|
Body (JSON encoded)
Parameter |
Type |
Value |
---|---|---|
|
String |
Unique identifier for the Link. |
(*) Mandatory Parameters
Responses
200 OK
{
"success": true,
"data": {
"token": str,
"name": str,
"redirect_uri": str,
"company_name": str,
"terms_and_conditions_url": str | null,
"privacy_policy_url": str | null,
"active": bool,
"pending_code_count": int,
}
}
Returns the updated values for the Link.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
404 Link Not Found
{
"success": false,
"error": {
"code": "LinkNotFound",
},
"trace_id": str,
}
There's no Link with the given token.
500 Internal Error
{
"error": "Internal Error"
}
Resume Link
Resume a Link so it can be used again to add new credentials.
Headers
Header |
Value |
---|---|
|
|
|
|
Body (JSON encoded)
Parameter |
Type |
Value |
---|---|---|
|
String |
Unique identifier for the Link. |
(*) Mandatory Parameters
Responses
200 OK
{
"success": true,
"data": {
"token": str,
"name": str,
"redirect_uri": str,
"company_name": str,
"terms_and_conditions_url": str | null,
"privacy_policy_url": str | null,
"active": bool,
"pending_code_count": int,
}
}
Returns the updated values for the Link.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
404 Link Not Found
{
"success": false,
"error": {
"code": "LinkNotFound",
},
"trace_id": str,
}
There's no Link with the given token.
500 Internal Error
{
"error": "Internal Error"
}
Get Unused Link Codes
This endpoint allows you to retrieve your unused link codes.
A link_token
can be optionally supplied to filter only the codes generated from
a particular link. If no filter is used, all the pending codes will be retrieved.
Also with every code, there will be the extra
dict. The keys and values correspond
to the extra
parameters added to the link.
You can then exchange those link codes for a credentials_token
using the
Exchange Link Code for Credentials Token
endpoint.
Headers
Header |
Value |
---|---|
|
|
|
|
Query Parameters
Parameter |
Type |
Value |
---|---|---|
|
String |
The token (identifier) of a given link. |
(*) Mandatory Parameters
Responses
200 OK
[
{
"code": "<LINK_CODE>",
"extra": {},
"link_token": "<LINK_TOKEN>",
},
{
"code": "<LINK_CODE>",
"extra": {
"<EXTRA_PARAMETER_1>": "<PARAMETER_1_VALUE>",
...
"<EXTRA_PARAMETER_N>": "<PARAMETER_N_VALUE>",
}
"link_token": "<LINK_TOKEN>",
},
...
]
List of unused link codes.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
500 Internal Error
{
"error": "Internal Error"
}
Exchange Link Code for Credentials Token
This endpoint allows you to exchange a link code for their associated credentials_token.
The code is single-use, and once the exchange has been finished, it will no longer be valid.
You can set extra query-string parameters before sending a Link to your clients. These parameters will be available in the response, under the extra
attribute.
Headers
Header |
Value |
---|---|
|
|
|
|
Body (JSON encoded)
Parameter |
Type |
Value |
---|---|---|
|
String |
The link code received as a parameter in a redirect URI, or retrieved via the Get Unused Link Codes endpoint. |
(*) Mandatory Parameters
Responses
200 OK
{
"message": "Successfully retrieved",
"credentials_token": "<END_USER_CREDENTIALS_TOKEN>",
"extra": {
"<EXTRA_PARAMETER_1>": "<PARAMETER_1_VALUE>",
"<EXTRA_PARAMETER_2>": "<PARAMETER_2_VALUE>",
},
"link_token": "<LINK_TOKEN>",
}
Successful retrieval. This code will be invalid from now on.
400 Invalid Code
{
"error": "Invalid code",
"error_code": 40001,
}
The provided code
is not valid. Please note that codes are only usable once.
401 Invalid Credentials
{
"error": "Invalid credentials"
}
The Authorization
header is either empty or contains an invalid or expired access_token
.
500 Internal Error
{
"error": "Internal Error"
}