Used to check the status of the API
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Symetrisk: For developers
Basic OAuth authorization and REST API
Getting an API client
Before calling the API, you need an API client on Symetrisk. The process differs depending on whether you are a bank or doing credit scoring.
For banks
- Log in to your Symetrisk account
- Go to the API page
- Click 'Create API client'
- An API client will now be created. Make sure to save the 'Client secret', as you will not be able to view this again.
For credit scoring
Contact us regarding getting access to the Symetrisk API for credit scoring, and we will be happy to help.
Getting an access token
The API requires a valid access token to be passed. This access token will also tell us which bank it is that is making the call.
- Make a POST request to https://symetrisk.auth.eu-central-1.amazoncognito.com/oauth2/token
- Include an Authorization header with value Basic CLIENT_ID:CLIENT_SECRET ('CLIENT_ID:CLIENT_SECRET' must be base64 encoded)
- Include a Content-Type header with value application/x-www-form-urlencoded
- In body, include grant_type: client_credentials, scope: scopes you want to include, seperated by spaces
- The response will include the access token (access_token), how long until it expires in seconds (expires_in) and the token type which will be Bearer (token_type).
- The access token lasts for 1 hour, after which it will become invalid. Keep track of how long the token is valid with the expires_in field, and request a new access token when the existing one has expired.
Scopes
- https://api.symetrisk.com/read - gives read access
- https://api.symetrisk.com/write - gives write access
Making calls to the API
To make calls to the API, you need to include the access token as a Bearer token in the Authorization header. The base url for the API is https://api.symetrisk.com/api/v1.
You can test out the API with a call like https://api.symetrisk.com/api/v1/ping, to check whether the auth process was successful and you are able to receive data from the API.
curl -X GET https://api.symetrisk.com/api/v1/ping \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"API documentation
Status
Used to check the status of the API
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Credit scoring
Self
Get info about partner integration and client
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Credit scoring
Intializes and creates a new credit-scorer company. This company will now be selectable by debtors during onboarding, and they can see view credit score on debtors that consent to share data.
Request body
{
"borrowers": [
{
"organization_number": "000000000"
}
]
}Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Ask for access to a debtors credit score. If the debtor already has an account and connected their accounting system, they just have to accept the new request in their dashboard. If they don't have an account yet, they can either log in through delregnskap.no or with the signup link that is returned. This will generate a signup link and create a relationship in state access_requested. Forward the link to the debtor, and after they have completed the onboarding they can accept the request. The relationship will then be set to access_approved, and you will be able to view data. Call GET /list-debtors to list all debtors who have consented to share data. Provide a list of debtors you want to request access to with their organization number in the body of this request.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| creditor_organization_number | string | path | Yes | The organization number of the creditor that is requesting access to debtors credit score. |
Request body
{
"debtors": [
{
"organization_number": "000000000"
},
{
"organization_number": "111111111"
}
]
}Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Get a list of all debtors of the creditor. To get credit score, use /get-credit-score/{creditor-organization-number}/{debtor-organization-number}, which will return the credit score for that specific debtor.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| creditor_organization_number | string | path | Yes | The organization number of the creditor to list debtors of |
| limit | integer | query | No | Max amount of items to return |
| skip | integer | query | No | Number of items to skip. |
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Get the credit score of a debtor.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| creditor_organization_number | string | path | Yes | The organization number of the creditor that the debtor has shared data with. |
| debtor_organization_number | string | path | Yes | The organization number of the debtor to get credit score of. |
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Banks
Self
Get info about own company and API client
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Accounting data
Get accounting data for borrower. Returns up to 100 instances of accounting data with a snapshot date as the last day of the month. Sorted by snapshot_date descending. You will only be able to call this endpoint with borrowers where you have a relationship in state 'access_approved' (consented_to_share_data in /borrower endpoint).
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| organization_number | string | path | Yes | The brreg organization number of the borrower to retrieve data from. |
| limit | integer | query | No | Max amount of items to return |
| skip | integer | query | No | Number of items to skip. |
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Borrowers and relationships
Get data about a borrower company.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| organization_number | string | path | Yes | The brreg organization number of the borrower to retrieve data from. |
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Request access to a borrower company. This will generate a signup link and create a relationship in state access_requested. Forward the link to the borrower, and after they have completed the onboarding they can accept the request. The relationship will then be set to access_approved, and you will be able to view data. Call GET /borrower/{organization_number} to see connection status and other data on the borrower.
Request body
{
"borrowers": [
{
"organization_number": "000000000"
}
]
}Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Get a list of all relationships. To get extended info about a borrower, make a call to /borrower/{organization_number}, with the brreg organization number of the borrower. You will only be able to call /accounting-data on borrowers in this list with 'relationship_state' access_approved.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| limit | integer | query | No | Max amount of items to return |
| skip | integer | query | No | Number of items to skip. |
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Notifications
Get notifications
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| limit | integer | query | No | Max amount of items to return |
| skip | integer | query | No | Number of items to skip. |
Responses
| Code | Description |
|---|---|
| 200 | OK Media type application/json |
Best practices when working with the API
- Endpoints that return an array of items will usually provide the option to paginate the response. To do this, use the 'limit' and 'skip' query parameters (these will be included in the 'parameters' section in API documentation for each endpoint where it is supported.)
- Every endpoint that supports pagination will also return a 'metadata' field with each response. This will include the applied pagination options, number of items returned, and the total amount of items that exists with the applied filters. Combine this data with 'limit' and 'skip' to retrieve all the records you need.
- For example, to get the first 100 items, use include these query parameters: '?limit=100&skip=0'. Now, if the 'total_items' field in the 'metadata' returns is 110, you can use these query parameters to get the remaining 10 items: '?limit=10&skip=100'.
- There is currently no rate-limit on any endpoints in the API, but we request unecessary load not to be placed on the API, and that you utilize paging and available queries to only receive as much data as is required.
API support
If you have questions, problems or feedback regarding the API, you can contact api support at support+api@symetrisk.com