faire.ai Platform (1.0.0)

Download OpenAPI specification:Download

faire.ai: info@faire.ai URL: https://faire.ai

The following document contains the documentation of faire.ai Platform.

Please, contact us at info@faire.ai if you want to try the Platform and get the credentials to call the API in test or production environments.

Authentication

openId

The API use OpenID Connect to authenticate and authorize the requests. Using curl, getting a token can be done calling the following endpoint with:

curl -X POST https://platform-dev.faire.ai/openid-connect/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<SECRET>

where CLIENT_ID and SECRET are the partner credentials provided by faire.ai.

Security Scheme Type	Open ID Connect
Connect URL	https://faireai-platform-docs.s3.eu-central-1.amazonaws.com/openid-dev-configuration.html

persons

Persons operations.

Create a person.

Authorizations:

openId (email profile)

Request Body schema: application/json

personId required	string Unique identifier of a person.
firstName required	string First name.
lastName required	string Last name.
emailAddress required	string <email> Email address.
dateOfBirth required	string <date> Date of birth.
placeOfBirth required	object (Place of birth)
gender	string Enum: "MALE" "FEMALE" Gender.
citizenship required	string 2 characters Citizenship represented with ISO 3166-1 alpha-2 code of the coutry.
fiscalCode required	string Fiscal code.
homeAddress	object (Address)
domicileAddress	object (Address)
phoneNumber	string Phone number represented with E.164 standard.

Responses

201

Person created.

default

Error occurred.

post /persons

Development environment

https://platform-dev.faire.ai/persons

Production environment

https://platform.faire.ai/persons

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"personId": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"dateOfBirth": "2000-07-21",
"placeOfBirth": 
{"city": "Rome",
"country": "IT"
},
"gender": "MALE",
"citizenship": "IT",
"fiscalCode": "RSSPPP00L21H501U",
"homeAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"domicileAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"phoneNumber": "+39XXXXXXXXXX"
}

Response samples

201
default

Content type

application/json

Copy

Expand all Collapse all


{"personId": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"dateOfBirth": "2000-07-21",
"placeOfBirth": 
{"city": "Rome",
"country": "IT"
},
"gender": "MALE",
"citizenship": "IT",
"fiscalCode": "RSSPPP00L21H501U",
"homeAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"domicileAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"phoneNumber": "+39XXXXXXXXXX"
}

Get all persons.

Return all the data of the persons registered by the partner to the Platform.

Authorizations:

openId (email profile)

Responses

200

Persons retrieved.

default

Error occurred.

get /persons

Development environment

https://platform-dev.faire.ai/persons

Production environment

https://platform.faire.ai/persons

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"persons": 
[
{"personId": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"dateOfBirth": "2000-07-21",
"placeOfBirth": 
{"city": "Rome",
"country": "IT"
},
"gender": "MALE",
"citizenship": "IT",
"fiscalCode": "RSSPPP00L21H501U",
"homeAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"domicileAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"phoneNumber": "+39XXXXXXXXXX"
}
]
}

Get a person.

Return the data of a single person registered by the partner to the Platfom.

Authorizations:

openId (email profile)

path Parameters

personId

required

string <uuid>

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier of a person.

Responses

200

Person retrieved.

default

Error occurred.

get /persons/{personId}

Development environment

https://platform-dev.faire.ai/persons/{personId}

Production environment

https://platform.faire.ai/persons/{personId}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"personId": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"dateOfBirth": "2000-07-21",
"placeOfBirth": 
{"city": "Rome",
"country": "IT"
},
"gender": "MALE",
"citizenship": "IT",
"fiscalCode": "RSSPPP00L21H501U",
"homeAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"domicileAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"phoneNumber": "+39XXXXXXXXXX"
}

Update a person.

Update the data of an existing person.

Authorizations:

openId (email profile)

path Parameters

personId

required

string <uuid>

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier of a person.

Request Body schema: application/json

personId required	string Unique identifier of a person.
firstName required	string First name.
lastName required	string Last name.
emailAddress required	string <email> Email address.
dateOfBirth required	string <date> Date of birth.
placeOfBirth required	object (Place of birth)
gender	string Enum: "MALE" "FEMALE" Gender.
citizenship required	string 2 characters Citizenship represented with ISO 3166-1 alpha-2 code of the coutry.
fiscalCode required	string Fiscal code.
homeAddress	object (Address)
domicileAddress	object (Address)
phoneNumber	string Phone number represented with E.164 standard.

Responses

200

Person's data updated.

default

Error occurred.

put /persons/{personId}

Development environment

https://platform-dev.faire.ai/persons/{personId}

Production environment

https://platform.faire.ai/persons/{personId}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"personId": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"dateOfBirth": "2000-07-21",
"placeOfBirth": 
{"city": "Rome",
"country": "IT"
},
"gender": "MALE",
"citizenship": "IT",
"fiscalCode": "RSSPPP00L21H501U",
"homeAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"domicileAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"phoneNumber": "+39XXXXXXXXXX"
}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"personId": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"dateOfBirth": "2000-07-21",
"placeOfBirth": 
{"city": "Rome",
"country": "IT"
},
"gender": "MALE",
"citizenship": "IT",
"fiscalCode": "RSSPPP00L21H501U",
"homeAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"domicileAddress": 
{"line1": "3972 Eagles Nest Drive",
"line2": "Apt. 123",
"postalCode": "00152",
"city": "Placerville",
"country": "IT",
"state": "Italy"
},
"phoneNumber": "+39XXXXXXXXXX"
}

Delete a person.

Delete a person and all its data persisted on the Platform.

Authorizations:

openId (email profile)

path Parameters

personId

required

string <uuid>

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier of a person.

Responses

204

Person has been deleted.

default

Error occurred.

delete /persons/{personId}

Development environment

https://platform-dev.faire.ai/persons/{personId}

Production environment

https://platform.faire.ai/persons/{personId}

Response samples

default

Content type

application/json

Copy

Expand all Collapse all


{"errors": 
[
{"code": "PERSON_NOT_FOUND",
"message": "Could not find person '1234'"
}
]
}

accounts

Accounts operations.

Create new account.

Authorizations:

openId (email profile)

Request Body schema: application/json

accountId	string
personId	string UUID value
iban	string
currency	string
bookedBalance	string Booked balance.
holders	Array of strings

Responses

201

Account created

default

Error occurred.

post /accounts

Development environment

https://platform-dev.faire.ai/accounts

Production environment

https://platform.faire.ai/accounts

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"accountId": "a1b2c3",
"personId": "c6a7fe4e-5fc0-11eb-ae93-0242ac130002",
"iban": "BE71096123456769",
"currency": "EUR",
"bookedBalance": "1500.00",
"holders": 
["holder1",
"holder2"
]
}

Response samples

201
default

Content type

application/json

Copy

Expand all Collapse all


{"accountId": "a1b2c3",
"personId": "c6a7fe4e-5fc0-11eb-ae93-0242ac130002",
"iban": "BE71096123456769",
"currency": "EUR",
"bookedBalance": "1500.00",
"holders": 
["holder1",
"holder2"
],
"operativity": "OPERATIVE"
}

Get accounts of a person.

Return all the bank accounts data of a person registered on the Platform.

Authorizations:

openId (email profile)

query Parameters

personId

required

string

Example: personId=123e4567-e89b-12d3-a456-426614174000

Responses

200

Account

default

Error occurred.

get /accounts

Development environment

https://platform-dev.faire.ai/accounts

Production environment

https://platform.faire.ai/accounts

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"accounts": 
[
{"accountId": "a1b2c3",
"personId": "c6a7fe4e-5fc0-11eb-ae93-0242ac130002",
"iban": "BE71096123456769",
"currency": "EUR",
"bookedBalance": "1500.00",
"holders": 
["holder1",
"holder2"
],
"operativity": "OPERATIVE"
}
]
}

Get account.

Return all the data of a bank account.

Authorizations:

openId (email profile)

path Parameters

accountId

required

string

Example: a1b2c3

Responses

200

Account created

default

Error occurred.

get /accounts/{accountId}

Development environment

https://platform-dev.faire.ai/accounts/{accountId}

Production environment

https://platform.faire.ai/accounts/{accountId}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"accountId": "a1b2c3",
"personId": "c6a7fe4e-5fc0-11eb-ae93-0242ac130002",
"iban": "BE71096123456769",
"currency": "EUR",
"bookedBalance": "1500.00",
"holders": 
["holder1",
"holder2"
],
"operativity": "OPERATIVE"
}

Update account operativity.

Set the operativity of the bank account.

Authorizations:

openId (email profile)

path Parameters

accountId

required

string

Example: a1b2c3

Request Body schema: application/json

operativity

required

string

Describes account operativity.

OPERATIVE means the account is operative.
NOT_OPERATIVE means the account is not operative.
UNKNOWN means that it is unknown if the account is operative.

Responses

202

Account operativity updated

default

Error occurred.

put /accounts/{accountId}/operativity

Development environment

https://platform-dev.faire.ai/accounts/{accountId}/operativity

Production environment

https://platform.faire.ai/accounts/{accountId}/operativity

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"operativity": "OPERATIVE"
}

Response samples

202
default

Content type

application/json

Copy

Expand all Collapse all

"string"

Delete account.

Delete a bank account and all its data.

Authorizations:

openId (email profile)

path Parameters

accountId

required

string

Example: a1b2c3

Responses

204

Account deleted

default

Error occurred.

delete /accounts/{accountId}/operativity

Development environment

https://platform-dev.faire.ai/accounts/{accountId}/operativity

Production environment

https://platform.faire.ai/accounts/{accountId}/operativity

Response samples

204
default

Content type

application/json

Copy

Expand all Collapse all

"string"

Add transaction to existing account.

Add a transaction to an existing bank account.

Authorizations:

openId (email profile)

path Parameters

accountId

required

string

Example: a1b2c3

Request Body schema:
application/json

transactionId required	string
bookingDate	string <date-time>
valueDate required	string <date-time>
currency required	string
amount required	string
description required	string
mainCategory	string Default: "OTHER"
subCategory	string Default: "OTHER"
recurrenceType required	string Enum: "NONE" "UNKNOWN" "DEFINED" Describes this transaction's recurrence. `NONE` means that transaction is not recurrent. `UNKNOWN` means that it is unknown if the transaction is recurrent. `DEFINED` means that transaction is recurrent and `recurrencePeriod` can be specified.
recurrencePeriod	string Can be specified only if `recurrenceType` is set to `DEFINED`
merchantName	string

Responses

201

Transaction added

207

Bulk registration of transactions completed. This is the response in case of request with application type application/json-seq.

default

Error occurred.

post /accounts/{accountId}/transactions

Development environment

https://platform-dev.faire.ai/accounts/{accountId}/transactions

Production environment

https://platform.faire.ai/accounts/{accountId}/transactions

Request samples

Payload

Content type

Copy

Expand all Collapse all


{"transactionId": "121212",
"bookingDate": "2021-01-21T08:17:06.432Z",
"valueDate": "2021-01-21T08:17:06.432Z",
"currency": "EUR",
"amount": "22.0",
"description": "Rent bill",
"mainCategory": "BILLS_SUBSCRIPTIONS",
"subCategory": "BILLS",
"recurrenceType": "DEFINED",
"recurrencePeriod": "P1M",
"merchantName": "Merchant"
}

Response samples

201
207
default

Content type

application/json

Copy

Expand all Collapse all


{"accountId": "a1b2c3",
"partnerId": "c6a7fe4e-5fc0-11eb-ae93-0242ac130002",
"transactionId": "121212",
"bookingDate": "2021-01-21T08:17:06.432Z",
"valueDate": "2021-01-21T08:17:06.432Z",
"currency": "EUR",
"amount": "150.00",
"description": "Car rent bill",
"mainCategory": "BILLS_SUBSCRIPTIONS",
"subCategory": "BILLS",
"recurrenceType": "DEFINED",
"recurrencePeriod": "PT10H",
"merchantName": "Merchant"
}

Get transactions by accounts.

Return all the transactions of the bank account(s) specified by accountId parameter.

Authorizations:

openId (email profile)

path Parameters

accountId

required

Array of strings

Example: a1b2c3

Responses

200

Transactions

default

Error occurred.

get /accounts/{accountId}/transactions

Development environment

https://platform-dev.faire.ai/accounts/{accountId}/transactions

Production environment

https://platform.faire.ai/accounts/{accountId}/transactions

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"transactions": 
[
{"accountId": "a1b2c3",
"partnerId": "c6a7fe4e-5fc0-11eb-ae93-0242ac130002",
"transactionId": "121212",
"bookingDate": "2021-01-21T08:17:06.432Z",
"valueDate": "2021-01-21T08:17:06.432Z",
"currency": "EUR",
"amount": "150.00",
"description": "Car rent bill",
"mainCategory": "BILLS_SUBSCRIPTIONS",
"subCategory": "BILLS",
"recurrenceType": "DEFINED",
"recurrencePeriod": "PT10H",
"merchantName": "Merchant"
}
]
}

Update transaction recurrence.

Set/Update the recurrency of a transaction.

Authorizations:

openId (email profile)

path Parameters

accountId required	string Example: a1b2c2
transactionId required	string Example: 121212

Request Body schema: application/json

recurrenceType required	string Enum: "NONE" "UNKNOWN" "DEFINED" Describes this transaction's recurrence. `NONE` means that transaction is not recurrent. `UNKNOWN` means that it is unknown if the transaction is recurrent. `DEFINED` means that transaction is recurrent and `recurrencePeriod` can be specified.
recurrencePeriod	string

Responses

202

Transaction recurrence updated

default

Error occurred.

put /accounts/{accountId}/transactions/{transactionId}/recurrence

Development environment

https://platform-dev.faire.ai/accounts/{accountId}/transactions/{transactionId}/recurrence

Production environment

https://platform.faire.ai/accounts/{accountId}/transactions/{transactionId}/recurrence

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"recurrenceType": "DEFINED",
"recurrencePeriod": "P1M"
}

Response samples

202
default

Content type

application/json

Copy

Expand all Collapse all

"string"

Update transaction category.

Set/Update the category of a transaction.

Authorizations:

openId (email profile)

path Parameters

accountId required	string Example: a1b2c3
transactionId required	string Example: 121212

Request Body schema: application/json

mainCategory required	string
subCategory required	string

Responses

202

Transaction category updated

default

Error occurred.

put /accounts/{accountId}/transactions/{transactionId}/category

Development environment

https://platform-dev.faire.ai/accounts/{accountId}/transactions/{transactionId}/category

Production environment

https://platform.faire.ai/accounts/{accountId}/transactions/{transactionId}/category

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"mainCategory": "BILLS_SUBSCRIPTIONS",
"subCategory": "BILLS"
}

Response samples

202
default

Content type

application/json

Copy

Expand all Collapse all

"string"

List all categories.

Return the list of all the categories that can be assigned to a transaction.

Authorizations:

openId (email profile)

Responses

200

get /accounts/transactions/categories

Development environment

https://platform-dev.faire.ai/accounts/transactions/categories

Production environment

https://platform.faire.ai/accounts/transactions/categories

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"categories": 
[
{"mainCategory": "BILLS_SUBSCRIPTIONS",
"subCategories": 
["BILLS",
"INTERNET_PHONE",
"OTHER",
"SUBSCRIPTIONS"
]
},
{"mainCategory": "CREDIT_CARDS",
"subCategories": 
["CREDIT_CARDS",
"OTHER"
]
},
{"mainCategory": "EATING_OUT",
"subCategories": 
["COFFEE_SHOPS",
"OTHER",
"RESTAURANTS",
"TAKEAWAY_RESTAURANTS"
]
},
{"mainCategory": "EDUCATION",
"subCategories": 
["COURSES",
"EDUCATIONAL_MATERIALS",
"KINDERGARTEN",
"OTHER",
"SCHOOLS",
"UNIVERSITIES"
]
},
{"mainCategory": "HEALTH_WELLNESS",
"subCategories": 
["AID_EXPENSES",
"DRUGS",
"GYMS",
"MEDICAL_EXPENSES",
"OTHER",
"SPORT",
"WELLNESS_RELAX"
]
},
{"mainCategory": "HOUSING_FAMILY",
"subCategories": 
["APPLIANCES",
"BABY_SITTING",
"CHILDHOOD",
"CONDO_EXPENSES",
"FURNITURE",
"GROCERIES",
"INSURANCES",
"LAUNDRY",
"MAINTENANCE_RENOVATION",
"NOURISHMENT",
"OTHER",
"RENTS",
"SERVANTS",
"VETERINARY"
]
},
{"mainCategory": "LEISURE",
"subCategories": 
["BOOKS",
"CINEMA",
"CLUB_ASSOCIATIONS",
"GAMBLING",
"MAGAZINES_NEWSPAPERS",
"MOVIES_MUSICS",
"MUSEUMS_PARKS",
"OTHER",
"SPORT_EVENTS",
"THEATERS_CONCERTS",
"VIDEOGAMES"
]
},
{"mainCategory": "MORTGAGES_LOANS",
"subCategories": 
["INSTALLMENT_PAYMENTS",
"LOANS",
"MORTGAGES",
"OTHER"
]
},
{"mainCategory": "OTHER",
"subCategories": 
["CASH",
"CHECKS",
"OTHER"
]
},
{"mainCategory": "PROFITS",
"subCategories": 
["OTHER",
"PROFITS"
]
},
{"mainCategory": "SHOPPING",
"subCategories": 
["ACCESSORIZE",
"CLOTHING",
"FOOTWEAR",
"HI_TECH",
"JEWELLERY",
"OTHER",
"SPORT_ARTICLES"
]
},
{"mainCategory": "TAXES_SERVICES",
"subCategories": 
["PROFESSIONAL_ACTIVITY",
"ACCOUNTANT",
"BANK_FEES",
"DEFAULT_PAYMENTS",
"EXPENSE_LEDGER",
"FINES",
"LEGAL_EXPENSES",
"MONEY_ORDERS",
"OFFICE",
"OTHER",
"PROFIT_DEDUCTION",
"TAXES"
]
},
{"mainCategory": "TRANSFERS",
"subCategories": 
["RENT_INCOMES",
"GIFTS_DONATIONS",
"BANK_TRANSFERS",
"SAVINGS",
"INVESTMENTS",
"REFUNDS",
"OTHER",
"WINNINGS"
]
},
{"mainCategory": "TRAVELS_TRANSPORTATION",
"subCategories": 
["BUSES",
"CAR_BIKE_SHARING",
"CAR_RENTAL",
"FLIGHTS",
"FUEL",
"HOTELS",
"OTHER",
"PARKING_URBAN_TRANSPORTS",
"SHIP_FERRIES",
"TAXIS",
"TOLLS",
"TRAINS",
"TRAVELS_HOLIDAYS",
"VEHICLE_MAINTENANCE"
]
},
{"mainCategory": "WAGES",
"subCategories": 
["OTHER",
"PENSION",
"PROFESSIONAL_COMPENSATION",
"SALARY"
]
}
]
}

kpis

KPIs analytics operations.

Get person or account KPIs.

Return one or more KPIs of a person or account. By specifying includeHistory query parameter and a KPI name (parameter kpi), the operation returns the history of the KPI.

Authorizations:

openId (email profile)

query Parameters

personId	string Unique identifier of the person to retrieve the KPI of.
accountId	string Unique identifier of the account to retrieve the KPIs of.
kpi	string Example: kpi=MONTHLY_TOTAL_OUTFLOW_MEAN Name of the KPI to filter by.
includeHistory	boolean If `true`, then return the history of the KPI values.
from	string <date> Example: from=2021-04-29 History interval start date when `includeHistory` is set to `true`.
to	string <date> Example: to=2021-06-12 History interval end date when `includeHistory` is set to `true`.

Responses

200

Retrieve KPIs succeeded.

default

Error occurred.

get /kpis

Development environment

https://platform-dev.faire.ai/kpis

Production environment

https://platform.faire.ai/kpis

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"kpis": 
[
{"kpi": "AVERAGE_BALANCE",
"value": "700.00",
"referenceTimestamp": "2021-03-27T23:59:59.999+0000",
"status": "ALL_DATA_PROCESSED",
"isAssumed": false
}
]
}

List all available KPIs.

Return the list of all the KPIs that the Platform provides for persons and accounts grouped by the following categories:

person characterization;
account characterization;
wealth indicators;
spending indicators;
liabilities indicators;
risk indicators;
financial health indicators.

To know the list of the KPIs, please, contact us at info@faire.ai.

Authorizations:

openId (email profile)

Responses

200

List of available KPIs.

400

Retrieve KPIs failed for invalid inputs.

default

Error occurred.

get /kpis/list

Development environment

https://platform-dev.faire.ai/kpis/list

Production environment

https://platform.faire.ai/kpis/list

Response samples

200
400
default

Content type

application/json

Copy

Expand all Collapse all


{"kpis": 
[
{"name": "MONTHLY_TOTAL_OUTFLOW",
"description": "Sum of monthly expenses",
"category": "SPENDING_INDICATORS",
"types": 
["ACCOUNT",
"PERSON"
]
}
]
}

loan-products

Loan products operations.

Create a loan product.

Create a new loan product in the Platform.

Authorizations:

openId (email profile)

Request Body schema: application/json

name required	string Loan product name
currency required	string Currency of the loan product
status required	string Enum: "ACTIVE" "INACTIVE" Status of the loan product
conditions required	Array of objects (Contition)
fees	Array of objects (Fee)
scheduledActivation	object (Activation)

Responses

201

Loan product created.

default

Error occurred.

post /loan-products

Development environment

https://platform-dev.faire.ai/loan-products

Production environment

https://platform.faire.ai/loan-products

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"name": "Fast loan",
"currency": "EUR",
"status": "ACTIVE",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

Response samples

201
default

Content type

application/json

Copy

Expand all Collapse all


{"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Fast loan",
"currency": "EUR",
"status": "ACTIVE",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

Get all loan products.

Return all the loan products created by the partner in the Platform.

Authorizations:

openId (email profile)

query Parameters

loanProductStatus

string

Enum: "ACTIVE" "INACTIVE"

Example: loanProductStatus=ACTIVE

The status of th loan product

Responses

200

Loan products retrieved.

default

Error occurred.

get /loan-products

Development environment

https://platform-dev.faire.ai/loan-products

Production environment

https://platform.faire.ai/loan-products

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"loanProducts": 
[
{"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Fast loan",
"currency": "EUR",
"status": "ACTIVE",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}
]
}

Get a loan product.

Return a loan product by its unique identifier.

Authorizations:

openId (email profile)

path Parameters

loanProductId

required

string <uuid>

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier of a loan product.

Responses

200

Loan product retrieved.

default

Error occurred.

get /loan-products/{loanProductId}

Development environment

https://platform-dev.faire.ai/loan-products/{loanProductId}

Production environment

https://platform.faire.ai/loan-products/{loanProductId}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Fast loan",
"currency": "EUR",
"status": "ACTIVE",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

Update loan product.

Update a loan product. The loan product can be updated if is not active or activated in the past.

Authorizations:

openId (email profile)

path Parameters

loanProductId

required

string <uuid>

Request Body schema: application/json

name required	string Loan product name
conditions required	Array of objects (Contition)
fees	Array of objects (Fee)
scheduledActivation	object (Activation)

Responses

200

Loan product updated.

default

Error occurred.

put /loan-products/{loanProductId}

Development environment

https://platform-dev.faire.ai/loan-products/{loanProductId}

Production environment

https://platform.faire.ai/loan-products/{loanProductId}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"name": "Fast loan",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Fast loan",
"currency": "EUR",
"status": "ACTIVE",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

Change loan product scheduled activation.

Authorizations:

openId (email profile)

path Parameters

loanProductId

required

string

Request Body schema: application/json

scheduledActivation

object (Activation)

Responses

200

Loan product schedule activation updated.

default

Error occurred.

patch /loan-products/{loanProductId}/scheduled-activation

Development environment

https://platform-dev.faire.ai/loan-products/{loanProductId}/scheduled-activation

Production environment

https://platform.faire.ai/loan-products/{loanProductId}/scheduled-activation

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Fast loan",
"currency": "EUR",
"status": "ACTIVE",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

Get loan simulation.

Given the amount and/or the number of instalments, return the monthly payments for a loan product.

Authorizations:

openId (email profile)

path Parameters

loanProductId

required

string

query Parameters

amountValue required	string Example: amountValue=1000
numberOfMonthlyInstalments	integer Example: numberOfMonthlyInstalments=6

Responses

200

Loan product simaulation calculated

default

Error occurred.

get /loan-products/{loanProductId}/simulation

Development environment

https://platform-dev.faire.ai/loan-products/{loanProductId}/simulation

Production environment

https://platform.faire.ai/loan-products/{loanProductId}/simulation

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"loanSimulations": 
[
{"numberOfInstalments": 7,
"grossAnnualRate": 6.83,
"instalments": 
[
{"amount": 34.26
}
]
}
]
}

Change loan product status to active or inactive.

Changes the status of a given loan product.

Authorizations:

openId (email profile)

path Parameters

loanProductId

required

string

Request Body schema: application/json

status

string

Enum: "ACTIVE" "INACTIVE"

Status of the loan product

Responses

200

Loan product status changed.

default

Error occurred.

patch /loan-products/{loanProductId}/status

Development environment

https://platform-dev.faire.ai/loan-products/{loanProductId}/status

Production environment

https://platform.faire.ai/loan-products/{loanProductId}/status

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"status": "ACTIVE"
}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Fast loan",
"currency": "EUR",
"status": "ACTIVE",
"conditions": 
[
{"lowerBound": "700",
"upperBound": "2000",
"lowerInclusive": true,
"upperInclusive": true,
"numberOfInstalments": 5,
"annualPercentageRate": "0.35"
}
],
"fees": 
[
{"description": "Annual fee",
"type": "ANNUAL",
"amount": "5",
"amountType": "FLAT"
}
],
"scheduledActivation": 
{"start": "2022-04-14T15:30:19Z",
"end": "2022-05-08T15:30:19Z"
}
}

loans

Loans operations.

Transaction categories

Main Category	Subcategory	Income	Expense
BILLS_SUBSCRIPTIONS	BILLS	false	true
	INTERNET_PHONE	false	true
	OTHER	false	true
	SUBSCRIPTIONS	false	true
CREDIT_CARDS	CREDIT_CARDS	false	true
CREDIT_CARDS	OTHER	false	true
EATING_OUT	COFFEE_SHOPS	false	true
	OTHER	false	true
	RESTAURANTS	false	true
	TAKEAWAY_RESTAURANTS	false	true
EDUCATION	COURSES	false	true
	EDUCATIONAL_MATERIALS	false	true
	KINDERGARTEN	false	true
	OTHER	false	true
	SCHOOLS	false	true
	UNIVERSITIES	false	true
HEALTH_WELLNESS	AID_EXPENSES	false	true
	DRUGS	false	true
	GYMS	false	true
	MEDICAL_EXPENSES	false	true
	OTHER	false	true
	SPORT	false	true
	WELLNESS_RELAX	false	true
HOUSING_FAMILY	APPLIANCES	false	true
	BABY_SITTING	false	true
	CHILDHOOD	false	true
	CONDO_EXPENSES	false	true
	FURNITURE	false	true
	GROCERIES	false	true
	INSURANCES	true	true
	LAUNDRY	false	true
	MAINTENANCE_RENOVATION	false	true
	NOURISHMENT	true	true
	OTHER	false	true
	RENTS	false	true
	SERVANTS	false	true
	VETERINARY	false	true
LEISURE	BOOKS	false	true
	CINEMA	false	true
	CLUB_ASSOCIATIONS	false	true
	GAMBLING	false	true
	MAGAZINES_NEWSPAPERS	false	true
	MOVIES_MUSICS	false	true
	MUSEUMS_PARKS	false	true
	OTHER	false	true
	SPORT_EVENTS	false	true
	THEATERS_CONCERTS	false	true
	VIDEOGAMES	false	true
MORTGAGES_LOANS	INSTALLMENT_PAYMENTS	false	true
	LOANS	true	true
	MORTGAGES	false	true
	OTHER	false	true
OTHER	CASH	true	true
	CHECKS	true	true
	OTHER	true	true
PROFITS	OTHER	true	false
PROFITS	PROFITS	true	false
SHOPPING	ACCESSORIZE	false	true
	CLOTHING	false	true
	FOOTWEAR	false	true
	HI_TECH	false	true
	JEWELLERY	false	true
	OTHER	false	true
	SPORT_ARTICLES	false	true
TAXES_SERVICES	PROFESSIONAL_ACTIVITY	false	true
	ACCOUNTANT	false	true
	BANK_FEES	false	true
	DEFAULT_PAYMENTS	false	true
	EXPENSE_LEDGER	false	true
	FINES	false	true
	LEGAL_EXPENSES	false	true
	MONEY_ORDERS	false	true
	OFFICE	false	true
	OTHER	false	true
	PROFIT_DEDUCTION	false	true
	TAXES	false	true
TRANSFERS	RENT_INCOMES	true	false
	GIFTS_DONATIONS	true	true
	BANK_TRANSFERS	true	true
	SAVINGS	false	true
	INVESTMENTS	false	true
	REFUNDS	true	false
	OTHER	true	true
	WINNINGS	true	false
TRAVELS_TRANSPORTATION	BUSES	false	true
	CAR_BIKE_SHARING	false	true
	CAR_RENTAL	false	true
	FLIGHTS	false	true
	FUEL	false	true
	HOTELS	false	true
	OTHER	false	true
	PARKING_URBAN_TRANSPORTS	false	true
	SHIP_FERRIES	false	true
	TAXIS	false	true
	TOLLS	false	true
	TRAINS	false	true
	TRAVELS_HOLIDAYS	false	true
	VEHICLE_MAINTENANCE	false	true
WAGES	OTHER	true	false
	PENSION	true	false
	PROFESSIONAL_COMPENSATION	true	false
	SALARY	true	false

Create a new loan.

Authorizations:

openId (email profile)

Request Body schema: application/json

loanId required	string <uuid> Unique identifier of a loan
personId required	string Unique identifier of a person
loanProductId required	string Unique identifier of a loan product
amount required	string The amount of the loan
currency required	string The currency of the loan
numberOfInstalments required	number The number of the instalments for the loan

Responses

201

Loan product created.

default

Error occurred.

post /loans

Development environment

https://platform-dev.faire.ai/loans

Production environment

https://platform.faire.ai/loans

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"loanId": "4049ab70-7a61-11eb-9439-0242ac130002",
"personId": "a1b2c3",
"loanProductId": "4049ab70-7a61-11eb-9439-0242ac130011",
"amount": "1000",
"currency": "EUR",
"numberOfInstalments": 6
}

Response samples

201
default

Content type

application/json

Copy

Expand all Collapse all


{"loanId": "4049ab70-7a61-11eb-9439-0242ac130002",
"personId": "a1b2c3",
"amount": 1000,
"numberOfInstalments": 6,
"loanStatus": "CREATED",
"instalments": 
[
{"amount": 130.66,
"dueDate": "2031-01-21",
"paidAt": "2022-05-05T12:12:13.124Z"
}
]
}

Retrieve the loans.

Return all the loans created by the partner.

Authorizations:

openId (email profile)

query Parameters

personId	string Example: personId=a1b2c3 Unique identifier of a person.
loanStatus	string Enum: "CLOSED" "REJECTED" "DEFAULTING" "CANCELLED" "DISBURSED" "APPROVED" "CREATED" Status of the loan.

Responses

200

Loans retrivied.

default

Error occurred.

get /loans

Development environment

https://platform-dev.faire.ai/loans

Production environment

https://platform.faire.ai/loans

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"loanProducts": 
[
{"loanId": "4049ab70-7a61-11eb-9439-0242ac130002",
"personId": "a1b2c3",
"amount": 1000,
"numberOfInstalments": 6,
"loanStatus": "CREATED",
"instalments": 
[
{"amount": 130.66,
"dueDate": "2031-01-21",
"paidAt": "2022-05-05T12:12:13.124Z"
}
]
}
]
}

Retrieve a loan.

Return a loan by its unique identifier.

Authorizations:

openId (email profile)

path Parameters

loanId

required

string

Example: d4618120-96d1-11eb-a8b3-0242ac130009

Unique identifier of a loan.

Responses

200

Loan retrivied.

default

Error occurred.

get /loans/{loanId}

Development environment

https://platform-dev.faire.ai/loans/{loanId}

Production environment

https://platform.faire.ai/loans/{loanId}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"loanId": "4049ab70-7a61-11eb-9439-0242ac130002",
"personId": "a1b2c3",
"amount": 1000,
"numberOfInstalments": 6,
"loanStatus": "CREATED",
"instalments": 
[
{"amount": 130.66,
"dueDate": "2031-01-21",
"paidAt": "2022-05-05T12:12:13.124Z"
}
]
}

Update loan.

Update the data of an existing loan.

Authorizations:

openId (email profile)

path Parameters

loanId

required

string

Example: d4618120-96d1-11eb-a8b3-0242ac130009

Unique identifier of a loan.

Request Body schema: application/json

status	string Enum: "CLOSED" "REJECTED" "DEFAULTING" "CANCELLED" "DISBURSED" "APPROVED" "CREATED" The status of the loan
amount	string The amount of the loan
numberOfInstalments	integer The number of instalments for the loan
instalmentsDueDates	Array of strings <date> Instalments due dates of the loan

Responses

200

Loan retrivied.

default

Error occurred.

patch /loans/{loanId}

Development environment

https://platform-dev.faire.ai/loans/{loanId}

Production environment

https://platform.faire.ai/loans/{loanId}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"status": "CREATED",
"amount": "1000",
"numberOfInstalments": 6,
"instalmentsDueDates": 
["2031-01-21",
"2031-02-21",
"2031-03-21",
"2031-04-21",
"2031-05-21",
"2031-06-21"
]
}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"loanId": "4049ab70-7a61-11eb-9439-0242ac130002",
"personId": "a1b2c3",
"amount": 1000,
"numberOfInstalments": 6,
"loanStatus": "CREATED",
"instalments": 
[
{"amount": 130.66,
"dueDate": "2031-01-21",
"paidAt": "2022-05-05T12:12:13.124Z"
}
]
}

Repay instalment.

Change the status of an instalment.

Authorizations:

openId (email profile)

path Parameters

loanId required	string Example: d4618120-96d1-11eb-a8b3-0242ac130009 Unique identifier of a loan.
instalmentReference required	string Example: 2031-02-21 Instalment due date.

Request Body schema: application/json

status required	string Enum: "NEW" "PENDING" "PAID" "DEFAULT" The status of the repayment
paid	string <date-time> Must be provided if status of the loan is `PAID`

Responses

200

Loan retrivied.

default

Error occurred.

patch /loans/{loanId}/instalments/{instalmentReference}

Development environment

https://platform-dev.faire.ai/loans/{loanId}/instalments/{instalmentReference}

Production environment

https://platform.faire.ai/loans/{loanId}/instalments/{instalmentReference}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"status": "PAID",
"paid": "2022-05-05T12:12:13.124Z"
}

Response samples

200
default

Content type

application/json

Copy

Expand all Collapse all


{"loanId": "4049ab70-7a61-11eb-9439-0242ac130002",
"personId": "a1b2c3",
"amount": 1000,
"numberOfInstalments": 6,
"loanStatus": "CREATED",
"instalments": 
[
{"amount": 130.66,
"dueDate": "2031-01-21",
"paidAt": "2022-05-05T12:12:13.124Z"
}
]
}