Links API

Endpoints

List Links

This endpoint returns all your Links

https://api.flanks.io/v0/links/list-links

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Create Link

Create a new Link, which will be available at the URL http://platform.flanks.io/link?token=<token>

https://api.flanks.io/v0/links/create-link

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`redirect_uri` *	String	URI where the user will be redirected after the credentials are created.
`name`	String \| null	A unique name to identify the Link. If it's not provided, it will be equal to the Link's token.
`company_name`	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.
`terms_and_conditions_url`	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.
`privacy_policy_url`	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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

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 .

https://api.flanks.io/v0/links/edit-link

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`token` *	String	Unique identifier for the Link.
`redirect_uri`	String	URI where the user will be redirected after the credentials are created.
`name`	String \| null	A unique name to identify the Link. If it's set to null, it will be equal to the Link's token.
`company_name`	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.
`terms_and_conditions_url`	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.
`privacy_policy_url`	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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Delete Link

Delete a Link. Note that only Links with no pending link codes can be deleted.

https://api.flanks.io/v0/links/delete-link

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`token` *	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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Pause Link

A paused Link cannot be accessed to add new credentials, but it can be edited and their pending codes can be exchanged.

https://api.flanks.io/v0/links/pause-link

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`token` *	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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Resume Link

Resume a Link so it can be used again to add new credentials.

https://api.flanks.io/v0/links/resume-link

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`token` *	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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

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.

https://api.flanks.io/v0/platform/link

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Query Parameters

Parameter	Type	Value
`link_token`	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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

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.

https://api.flanks.io/v0/platform/link

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`code` *	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"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.