Quickstart Guide

Learn how to quickly integrate the Norman API and begin making API calls with minimal effort. To embed the Norman API and start offering it to your customers, follow these basic steps:

1. Obtain Your Auth Credentials 🔑

To access the core Institution API and onboard your customers, you’ll need to obtain your credentials: institution_id and secret_key. These credentials are passed in the custom authorization header, Institution, using the following pattern: institution_id:secret_key.

Example Request:

curl -X 'GET'  
  '<https://sandbox.norman.finance/api/v1/institution/users/'>  
  -H 'accept: application/json'  
  -H 'Institution: institution_id:secret_key'\`

📌

To obtain a set of client credentials, contact the Norman team here.

Keep your institution_id and secret_key secure. Never store your secret_key in plain text. Treat it like a password or any other sensitive API key, and always store it in encrypted storage. All API calls using the Institution auth header should be invoked from your server to prevent exposure on the client-side.

2. Server Side: Creating a Customer and Getting an Access Token 🔐

⚠️

The following steps should be performed on your backend to protect your credentials from exposure on the client-side.

2.1. Customer Creation and Onboarding

To use Norman’s products, you must create and onboard your users. Link them with your application via the external_id. When creating a user, you’ll receive access and refresh tokens, which allow you to make API calls on their behalf and start importing financial data. Each user has a Company entity where all transactions, taxes, invoices, etc., are stored. Norman automatically creates the associated company during user registration.

Example Endpoint Request:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/create/'>  
  -H 'accept: application/json'  
  -H 'Institution: institution_id:secret_key'  
  -H 'Content-Type: application/json'  
  -d '{  
      "username": "newuser",  
      "email": "[email protected]",  
      "external_id": "7573b746-0be5-434a-90c3-37c1edb062bb"  
    }'

2.2. Getting an Access Token

In the response, you will receive the user ID (publicId), accessToken, and refreshToken. With the accessToken, you can access the core API to update user data, import financial data, and more. Add the Authorization header to all requests using the pattern: Bearer <accessToken>.

Example Request to Get Current User Data:

curl -X 'GET'  
  '<https://sandbox.norman.finance/api/v1/institution/users/me/'>  
  -H 'accept: application/json'  
  -H 'Authorization: Bearer <accessToken>'

2.3. Handle Token Expiration ⏳

Access tokens are valid for 30 minutes (1800 seconds). When the token expires, Norman will respond with a 401 error. The response from /api/v1/institution/users/create/ also includes a refreshToken and expiresIn field. Calculate the expiration by adding the expiresIn value to the current time (UNIX Epoch time).

To refresh an expired token, use the /api/v1/institution/users/token/refresh/ endpoint.

2.4. Removing and Restoring a User 🚪

If a user deletes their account in your app, you may need to remove them from the Norman API. Use the /api/v1/institution/users/disable/{userId}/ endpoint to make their data inaccessible. After 30 days, the data will be permanently deleted from Norman.

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/disable/b273b746-0be5-434a-90c3-37c1edb062bb/'>  
  -H 'Institution: institution_id:secret_key'  
  -H 'Authorization: Bearer <accessToken>'

During the 30-day grace period, you can restore the user’s account using the /api/v1/institution/users/restore/{userId}/ endpoint.

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/restore/b273b746-0be5-434a-90c3-37c1edb062bb/'>  
  -H 'Institution: institution_id:secret_key'  
  -H 'Authorization: Bearer <accessToken>'

3. Client Side: Displaying Pre-Accounting, Taxes, Invoicing Interfaces in Your Product 📊

To fully utilize Norman, your customers need to provide company details and tax settings (such as VAT reporting frequency or exemption status) and start tracking expenses and revenues by importing transactions or creating invoices. These interfaces for should be implemented on the client side using Norman API calls with the accessToken (without the Institution header, which is only used for authentication and registration). Here are a few basic examples of common API calls:

3.1. Update Customer’s Company Details

Example:

curl -X 'PATCH'  
  '<https://sandbox.norman.finance/api/v1/companies/'>  
  -H 'accept: application/json'  
  -H 'Authorization: Bearer <accessToken>'  
  -H 'Content-Type: application/json'  
  -d '{  
       "phoneNumber":"+4915202870458",  
       "address":"Hauptstraße 18",  
       "city":"Berlin",  
       "zipCode":"33421",  
       "name":"Test test",  
       "profession":"Architekt",  
       "vatNumber":"DE811569869",  
       "taxNumber":"00/679/72099"  
  }'

3.2. Validate Tax Number (Steuernummer)

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/taxes/check-tax-number/'>  
  -H 'accept: application/json'  
  -H 'Authorization: Bearer <accessToken>'  
  -H 'Content-Type: application/json'  
  -d '{  
      "tax_number": "00/679/72099",  
      "region_code": "BE"  
    }'

3.3. Create a First Transaction 💰

To begin calculating and preparing tax reports, customers need to track their expenses and revenues by importing or creating transactions and issuing invoices. Norman offers several ways to create transactions, including

• Manually creating a transaction
• Importing a CSV bank statement
• Creating a transaction by uploading a receipt or invoice and extracting the data
• Connecting to OpenBanking (e.g., GoCardless or FinAPI) to automatically sync transactions from the last 90 days

Norman will automatically categorize transactions, calculate VAT, and assign them to the correct tax report lines (e.g., reverse charge).

We’ll cover the various methods for importing and creating transactions in separate topics.

For now, here’s how to manually create a transaction:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/companies/bec25987-a572-440f-8030-d4ddeaa05a73/accounting/transactions/'>  
  -H 'accept: application/json'  
  -H 'Authorization: Bearer <accessToken>'  
  -H 'Content-Type: application/json'  
  -d '{  
      "amount": "-50.00",  
      "company": "bec25987-a572-440f-8030-d4ddeaa05a73",  
      "cashflowType": "EXPENSE",  
      "description": "iPhone case - MediaMarkt",  
      "valueDate": "2024-10-08"  
    }'

3.4. Set Tax Settings and Retrieve Tax Reports 📄

Update Tax Settings:

curl -X 'PATCH'  
  '<https://sandbox.norman.finance/api/v1/companies/bec25987-a572-440f-8030-d4ddeaa05a73/taxes/tax-settings/f73d6fb6-e6bb-47c3-920b-1c151505d9e8/'>  
  -H 'accept: application/json'  
  -H 'Authorization: Bearer <accessToken>'  
  -d '{  
      "vatPercent": 19,  
      "vatType": "vat_subject",  
      "reportingFrequency": "monthly",  
      "taxType": "sales"  
    }'

Get List of Tax Reports:

curl -X 'GET'  
  '<https://sandbox.norman.finance/api/v1/companies/bec25987-a572-440f-8030-d4ddeaa05a73/taxes/reports/'>  
  -H 'accept: application/json'  
  -H 'Authorization: Bearer <accessToken>'

4. That’s It! 🎉

Welcome aboard! You’re now ready to embed the Norman API into your product. To learn more about leveraging Norman’s full capabilities, check out our other guides. If you have any questions or need assistance, feel free to contact our support team.