Letters API

An authorization letter is a signed document by which an end client authorizes Flanks to establish a connection with a financial institution (custodian) and receive their financial data on their behalf. Each letter goes through a lifecycle that culminates in an active connection delivering data.

A letter can be created from two entry points:

New request — Flanks generates the authorization letter for the end client to sign and tracks it from there.
Signed — you submit a document that has already been signed by the end client.

Info

This API currently covers the signed entry point only: you submit already-signed authorization letters, track their state, and discontinue them when needed.

Authentication

These endpoints follow the same authentication and authorization guidelines as the rest of the Flanks public API:

Create one or more applications
Store the generated credentials (client_id and client_secret) securely
Get access tokens (see Authentication)

Endpoints

Create from signed

Submit an already-signed authorization letter to start a connection with a custodian. Each call creates a new letter, which enters the Signed status (see Letter Statuses).

https://api.flanks.io/letters/v1/create-signed

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json; charset=utf-8`

Body (JSON encoded)

Parameter	Type	Description
`connector_id` *	string	The unique identifier of the connector
`data`*	string	The signed authorization letter as a Base64-encoded PDF.
`labels`	object	Key-value pairs for identification and filtering (see Labels).
`annex`	string	An optional additional PDF document as Base64. Stored by Flanks but not sent to the custodian.
`contact_info`	object	Optional contact information relevant for processing the connection (see Contact Info).

(*) Mandatory Parameters

Responses

200 OK

{
  "letter_id": "550e8400-e29b-41d4-a716-446655440000"
}

Returns the unique identifier (UUID) of the created letter.

401 Unauthenticated

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED"
    },
    "trace_id": "00000000000000000000000000000000"
}

The Authorization header is either empty or contains an invalid or expired access_token.

403 Unauthorized

{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED"
    },
    "trace_id": "00000000000000000000000000000000"
}

The principal is not authorized to perform this action.

400 Validation Error

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "details": [
            {
                "field": "connector_id",
                "error_type": "RequiredField"
            }
        ]
    },
    "trace_id": "00000000000000000000000000000000"
}

Some required fields are missing or contain invalid values.

500 Internal Error

{
    "success": false,
    "error": {
        "code": "INTERNAL_ERROR"
    },
    "trace_id": "00000000000000000000000000000000"
}

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

Search

Search and list authorization letters with optional filters. Use this endpoint to retrieve the current state of your letters, filter by status, connector, or labels, and paginate through results.

https://api.flanks.io/letters/v1/search-letters

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json; charset=utf-8`

Body (JSON encoded)

Parameter	Type	Description
`query` *	object	Filter criteria (see query below).
`page`	integer	Page number (default: `1`).
`page_size`	integer	Results per page (default: `20`, max: `100`).

(*) Mandatory Parameters

Query

All query fields are optional. When multiple fields are provided, they are combined with AND logic.

Field	Type	Description
`connector_id_in`	list	Filter by one or more `connector_id` values.
`status_in`	list	Filter by one or more letter statuses.
`id_in`	list	Filter by one or more letter IDs (UUIDs).
`labels`	object	Filter by label key-value pairs.
`creation_date`	object	Filter by creation date range. Object with optional `start` and `end` fields. Accepts ISO 8601 datetime (`2024-01-15T10:30:00Z`) or date (`2024-01-15`).
`last_update`	object	Filter by last update date range. Object with optional `start` and `end` fields. Accepts ISO 8601 datetime (`2024-01-15T10:30:00Z`) or date (`2024-01-15`).

Responses

200 OK

{
  "items": [{ Letter }],
  "page": 1,
  "page_size": 20,
  "pages": 1,
  "total": 1
}

Returns a paginated list of letters. See Letter Model.

401 Unauthenticated

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED"
    },
    "trace_id": "00000000000000000000000000000000"
}

The Authorization header is either empty or contains an invalid or expired access_token.

403 Unauthorized

{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED"
    },
    "trace_id": "00000000000000000000000000000000"
}

The principal is not authorized to perform this action.

400 Validation Error

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "details": [
            {
                "field": "query",
                "error_type": "RequiredField"
            }
        ]
    },
    "trace_id": "00000000000000000000000000000000"
}

Some fields are missing or contain invalid values.

500 Internal Error

{
    "success": false,
    "error": {
        "code": "INTERNAL_ERROR"
    },
    "trace_id": "00000000000000000000000000000000"
}

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

Discontinue

Discontinue a letter by its letter_id.

Depending on the letter's current state, it will transition to one of two statuses:

Cancelled — if the letter never reached Connected status.
Discontinued — if the letter had an active connection. The associated connection and data are removed. The letter will eventually transition to Revoked once we notify the custodian of the revocation.

This action is irreversible — a discontinued letter cannot be reactivated.

https://api.flanks.io/letters/v1/discontinue-letter

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json; charset=utf-8`

Body (JSON encoded)

Parameter	Type	Description
`letter_id` *	string	The identifier (UUID) of the letter to discontinue.

(*) Mandatory Parameters

Responses

200 OK

{
  "success": true
}

The letter has been discontinued.

400 Validation Error

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "details": [
            {
                "field": "letter_id",
                "error_type": "RequiredField"
            }
        ]
    },
    "trace_id": "00000000000000000000000000000000"
}

Some required fields are missing or contain invalid values. A 400 is also returned if the letter is already in Cancelled, Discontinued, or Revoked status.

401 Unauthenticated

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED"
    },
    "trace_id": "00000000000000000000000000000000"
}

The Authorization header is either empty or contains an invalid or expired access_token.

403 Unauthorized

{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED"
    },
    "trace_id": "00000000000000000000000000000000"
}

The principal is not authorized to perform this action.

404 Not Found

{
    "success": false,
    "error": {
        "code": "NOT_FOUND",
        "message": "LetterNotFound"
    },
    "trace_id": "00000000000000000000000000000000"
}

No letter was found for the given letter_id.

500 Internal Error

{
    "success": false,
    "error": {
        "code": "INTERNAL_ERROR"
    },
    "trace_id": "00000000000000000000000000000000"
}

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

Data Model

Letter Model

{
  "id": string
  "connector_id": string,
  "status": string,
  "labels": object,
  "connection_id": string | null,
  "observations": string | null,
  "created_at": string,            // ISO 8601, e.g. "2024-12-01T00:00:00Z"
  "updated_at": string             // ISO 8601, e.g. "2024-12-01T00:00:00Z"
}

The connection_id links the letter to the data connection it produced. It is null until the letter reaches Connected.

Appendix

Labels

Labels are key-value pairs attached to each letter. They serve two purposes:

Searchability: Labels can contain any identifier needed for operational purposes (e.g., the end user's ID). All letters are searchable by their labels.
Connection tagging: Labels are propagated to the resulting connection, allowing you to apply the same filters. This ensures consistent labeling throughout the data flow.

{
  "labels": {
    "end_user_id": "USR_12345"
  }
}

Contact Info

The contact_info object contains optional information relevant for processing the connection, such as who to contact at the custodian or where to send the letter.

{
  "contact_info": {
    "banker_email": "[email protected]"
  }
}

Letter Statuses

Each letter goes through a series of statuses during its lifecycle. The following table describes each status:

Status	Description
`NewRequest`	A new record has been created.
`UsersDetail`	Collecting user details to fill in the letter.
`Generated`	The letter has been generated in the required format.
`SentToUser`	The letter has been sent to the user for signing.
`Signed`	The letter has been signed by the user. Letters submitted via API enter at this status.
`SentToCustodian`	The letter has been sent to the custodian for review and acceptance.
`AcceptedByCustodian`	The custodian has accepted the letter.
`ConnectionSetup`	The connection is being set up in the Flanks platform.
`WaitingForData`	Waiting for the custodian to send data to Flanks.
`Connected`	The connection is active and receiving data.
`Cancelled`	The letter has been cancelled before reaching an active connection. Used when the letter never reached the `Connected` status (e.g., during processing or before custodian acceptance).
`Discontinued`	The authorization has been discontinued and the associated data has been removed. Used when the letter had reached `Connected` status and the credential has been deleted. Will transition to `Revoked` once the custodian confirms revocation.
`Revoked`	We informed the custodian to stop receiving data. This is a terminal status.