NAV
http shell javascript

Introduction

Brevio API

Welcome to the developer documentation for Brevio's APIs.

Currently our APIs offer insight into data from the following services:

After registering you have instant access to our staging environment.

Once you have tested and verified your integration, you are ready to go through the process of accessing our production environment and your data. To begin this process, please contact us.

Parameters

For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

GET https://api.brevio.com/v1/some-endpoint?param=value&param=value

For POST requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json

curl "https://api.brevio.com/v1/some-endpoint' \
  -- request POST \
  --header 'content-type: application/json' \
  --data '{"param": "value", "param": "value"}'

Environments

The Brevio APIs are available in two separate environments:

To test your integration you should first authenticate against the staging environment - the production environment won't be available to your registered user until you have signed an API license deal. To begin this process, please contact us.

About the Brevio Confirm API

The Confirm API grants your authorized API client access to data associated with its entity in the Brevio Confirm service, whether you represent a bank or an audit company.

Through the API you can accomplish the following:

Endpoints

GET /v1/confirm/audit-requests/

GET /v1/confirm/audit-requests/third-party

POST /v1/confirm/audit-requests/

GET /v1/confirm/banks-full/

POST /v1/confirm/attachments/:token/signed-url

POST /v1/confirm/audit-requests/:token/confirmation

About the Brevio Sign API

The Sign API grants an authorized API client access to data associated with its entity in the Brevio Sign service.

Through the API you can accomplish the following:

Endpoints

GET /v1/sign/sign-requests

POST /v1/sign/sign-requests

GET /v1/sign/attachments/:token/signed-url

About the Brevio Signature-right API

The Signature-right API grants your authorized API client access to data associated with a person's signature right in a given company. This also includes Prokura for Norwegian companies.

Through the API you can accomplish the following:

Endpoints

GET /v1/signature-right

Authentication

To ensure the Brevio APIs adhere to the latest security standards we utilise Oauth 2.0 to authenticate and authorize API clients.

We use the "client_credentials" grant flow from the Oauth 2.0 specification to authorize access to API endpoints.

If you want to authenticate against our staging environment all you have to do is register a new API user to begin the process described below.

Credentials

Once you've registered a new user you will be given a client_id and a client_secret. These will be used to retrieve access tokens, based upon which scope you have access to.

Currently audit-company, bank, signature-right and signee-pid are valid scopes. Scopes audit-company, bank will be validated when you create your API user.
signature-right and signee-pid requires specific access, please contact us for more information.

Get Access token

URL: https://api.brevio.com/v1/auth/token
Method: POST
Allowed scopes: audit-company, bank, signature-right, signee-pid

To retrieve an access token you need to base64 encode your client_id and client_secret and pass them to the Basic authentication scheme.

You also need to specify the grant_type to be client_credentials, as well as specify the scope your client has access to.

Request Parameters

Parameter Type Description
grant_type String Must be 'client_credentials'
scope String Valid values: 'audit-company', 'bank', 'signature-right', 'signee-pid'

API Request

# base64 <<< client_id:client_secret
# => ZmhzYWtqZmxoa2FoZmFqOmRzaHNrYWpsaGRrbGpzYWhkYQ==

POST /v1/auth/token HTTP/1.1
Host: api.brevio.com
Authorization: Basic ZmhzYWtqZmxoa2FoZmFqOmRzaHNrYWpsaGRrbGpzYWhkYQ==
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "scope": "bank"
}

curl "https://api.brevio.com/v1/auth/token" \
  --request POST \
  --user "client_id:client_secret" \
  --header 'Content-Type: application/json' \
  --data '{"grant_type": "client_credentials", "scope": "bank" }

import request from "superagent";

request
  .post("https://api.brevio.com/v1/auth/token")
  .auth(clientId, clientSecret)
  .send({ grant_type: "client_credentials", scope: "bank" });

API Response

{
  "access_token": "78d5c959cbed6a582a68ec58284e711caf8ed7b57cd07e02c6585e969242b3ed",
  "token_type": "Bearer"
}

Once you have received your access_token you can access the Confirm and Sign APIs.

Brevio Confirm API

The Confirm API is used to interact with audit requests and their associated attachments and confirmations. All dates and datetime values adhere to the ISO8601 standard and are stored in UTC.

Get all Audit Requests for audit client

URL: /v1/confirm/audit-requests
Method:: GET
Allowed scopes: audit-company

This endpoint returns all audit requests for the entity associated with an authorized API client, filtered by the VAT number of the audit requests' associated audit client (named company in the API response).

The payload contains at most 50 requests. To access all associated audit requests (in cases where there are more than 50) you have to paginate through the results.

Request Parameters

Parameter Type Required Description
vatNo Integer (9 digits) true The VAT number for the audit requests' associated audit client
requestType RequestType false The desired request type you wish to filter the results by (see Audit Request attribute description below for a list of valid values)

API Request

GET /v1/confirm/audit-requests HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "vatNo": 123456789
}

curl "https://api.brevio.com/v1/confirm/audit-requests" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{ "vatNo": 123456789 }'

import request from "superagent";

request
  .get("https://api.brevio.com/v1/confirm/audit-requests")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
    vatNo: 123456789,
  });

Response

Attribute Type Description
count Integer The number of audit requests returned in the query
offset Integer The offset used for the query
next Integer The next offset to be used for further pagination
total Integer The total number of audit requests filtered by passed VAT number (and request type)
requests List<AuditRequest> List of audit requests

API Response

{
  "count": 50,
  "offset": 0,
  "next": 50,
  "total": 131,
  "requests": [
    // ...
  ]
}

API Response (offset = 50)

{
  "count": 50,
  "offset": 50,
  "next": 100,
  "total": 131,
  "requests": [
    // ...
  ]
}

Audit Request

All audit requests in the requests attribute in the API response have the following structure.

Attribute Type Description
token String Unique identifier
attachments List<String> List of tokens used to uniquely identify an attachment
auditCompany String Name of the audit company to which the associated auditor of the audit request belongs
auditor Auditor The auditor associated with the request
bankStatements List<BankStatement> If the audit request is of type bank, and the confirmation has been sent by the associated bank, then a list of bank statements containing additional account information is available for certain banks.
clientEmail String The email supplied by the auditor for the contact person in the associated audit client
company Integer Audit client VAT number, validated against the Norwegian company register
confirmation List<String> / null List of tokens used to uniquely identify an attachment (these attachments are uploaded as part of the confirmation, the field is null if the audit request has not been confirmed)
cutOffDate Date The end of the fiscal year for the associated audit client
daughterCompanies List<Integer> DEPRECATED - USE SUBSIDIARIES INSTEAD List of VAT numbers for any associated subsidiaries for the audit client
lastUpdate DateTime Last time step was updated
requestType String The type of the audit request. Valid values: 'bank', 'client', 'lawyer', 'supplier'
sentToClient DateTime Date and time the audit request was sent to the audit client
signee String/null The name of the person that has digitally signed the audit request, received from BankID. Null if the request has not been signed
step String The step in the audit request process request is currently at. Valid values: 'started', 'client', 'needs-validation', 'third-party', 'received', 'cancelled', 'archived', 'post'
subsidiaries List<Integer> List of VAT numbers for any associated subsidiaries for the audit client
thirdParty String Name of the audit request's associated third party

Audit Request

{
  "token": "9ff3501c5709b5211bca67013e7f051202fd3fe5099b63391c134eedecb5d3e9",
  "attachments": [
    "7c1a0413672e8e135b9c550e6b20691630e621b5001e602827e0a37a50571f82",
    "a8dd78be4ebb41af5936ae5d6eda64718207ce878db20bf30c9bab1c69513f19"
  ],
  "auditCompany": "Beeblebrox Audit AS",
  "auditor": {
    "address": "Jernbanetorget 1, 0154 Oslo",
    "name": "Zaphod Beeblebrox"
  },
  "bankStatements": [
    {
      "vatNo": "123456789",
      "companyName": "ACME Company",
      "cutOffDate": "2019-12-31",
      "accountInformation": [
        {
          "account": "1234.56.78912",
          "accountType": "Valutakonto",
          "balance": {
            "currency": "USD",
            "amount": "3018952.35",
            "localCurrencyAmount": "30189523.50"
          }
        }
      ]
    }
  ],
  "clientEmail": "[email protected]",
  "company": 123456789,
  "confirmation": [
    "56c435b336636c15d712c6a58090380aa0b27223928f3129ac534d8c6c60d6f3"
  ],
  "cutOffDate": "2019-12-31",
  "subsidiaries": [223456789, 334567899, 445678999],
  "lastUpdate": "2019-10-14 13:06:15",
  "requestType": "bank",
  "sentToClient": "2019-10-01 23:00:00",
  "signee": "Arthur Dent",
  "step": "received",
  "thirdParty": "Dent Industries AS"
}

Auditor

Attribute Type Description
address String The address of the auditor's associated office
name String The auditor's name, supplied by Norwegian BankID

Bank Statement

The Bank Statements are generated on the basis of the provided XML-attachments in the confirmation field. In cases where XML-attachments is not provided by the bank, this field will be null.

Attribute Type Description
vatNo string Should match company in AuditRequest, if not the auditor should contact the bank to clarify
companyName string Company name in the bank's records
cutOffDate string The date demarcating the end of the period for the associated account information. If this does not match cutOffDate in the Audit Request, the auditor should contact the bank to verify
accountInformation List<AccountInformation> List of bank accounts with associated metadata and recorded balance per the cutOffDate

Account Information

Attribute Type Description
account string The bank's internal ID for the bank account, i.e. bank account number
accountType string The bank's internal name for the type of bank account, e.g. "Valutakonto"
balance Balance The account balance at cutOffDate.

Balance

Attribute Type Description
currency string The currency code for the balance in balanceAmount, e.g. "USD", "EUR", "NOK" etc.
amount string The account balance amount in the currency from balanceCurrency
localCurrencyAmount string The account balance amount in the local currency of the bank. The amount in NOK for Norwegian banks.

Get all third party Audit Requests

URL: /v1/confirm/audit-requests/third-party
Method:: GET
Allowed scopes: bank
Optional scopes: signee-pid

This endpoint returns all associated audit requests which have been sent to their respective third parties for an associated API client.

The payload contains at most 50 requests. To access all associated audit requests (in cases where there are more than 50) you have to paginate through the results.

Request Parameters

Parameter Type Required Description
offset Integer false The offset used for pagination

API Request

GET /v1/confirm/audit-requests/third-party HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "offset": 0
}

curl "https://api.brevio.com/v1/confirm/audit-requests/third-party" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{ "offset": 0 }'

import request from "superagent";

request
  .get("https://api.brevio.com/v1/confirm/audit-requests/third-party")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({ offset: 0 });

Response

Attribute Type Description
count Integer The number of sign requests returned in the query
offset Integer The offset used for the query
next Integer The next offset to be used for further pagination
total Integer The total number of audit requests
requests List<AuditRequest> List of audit requests

Audit Request

All audit requests in the requests attribute in the API response have the following structure.

Attribute Type Description
token String Unique identifier
accountNumber String 11 character valid Norwegian bank account number separated by dots.
attachments List<String> List of tokens used to uniquely identify an attachment
auditCompany String Name of the audit company to which the associated auditor of the audit request belongs
auditor Auditor The auditor associated with the request
company Integer Audit client VAT number, validated against the Norwegian company register
companyName String Audit client name, validated against the Norwegian company register
confirmation List<String> List of tokens used to uniquely identify an attachment uploaded as part of the confirmation
cutOffDate Date The end of the fiscal year for the associated audit client
daughterCompanies List<Integer> DEPRECATED - USE SUBSIDIARIES INSTEAD List of VAT numbers for any associated subsidiaries for the audit client
language Language Language of the audit request
manualReview Boolean Boolean flag indicating whether this request needs manual review. This occurs when the auditor or client has made changes to the standard template
signeePID String?/null Personal ID (PID) is the signee's personal number - NO: 11 digits, SE: 10 or 12 digits, DK: 10 digits. Only available with scope 'signee-pid'. Attribute is omitted if scope is not present in the access token.
subsidiaries List<Integer> List of VAT numbers for any associated subsidiaries for the audit client

Audit Request

{
  "token": "aaaa32cf6c3453bfc7923e00d33002ea7b5277767524639f0e09da561c380ade",
  "accountNumber": "1234.56.78912",
  "attachments": [
    "7c1a0413672e8e135b9c550e6b20691630e621b5001e602827e0a37a50571f82"
  ],
  "auditCompany": "Beeblebrox Audit AS",
  "auditor": {
    "name": "Zaphod Beeblebrox",
    "address": "Jernbanetorget 1, 0154 Oslo"
  },
  "company": 123456789,
  "cutOffDate": "2019-12-31",
  "subsidiaries": [223456789, 334567899, 445678999],
  "signeePID": "31120000767",
  "manualReview": false
}

Auditor

Attribute Type Description
address String The address of the auditor's associated office
email String The auditor's e-mail address
name String The auditor's name, supplied by Norwegian BankID

Language

Valid values: 'en' | 'nb' | 'sv'| 'da'

Create Batch of Audit Requests

URL: /v1/confirm/audit-requests
Method: POST
Allowed scopes: audit-company

This endpoint allows audit companies to create a new batch of audit requests associated with an audit client (identified by a VAT number). The API response is a list of tokens used to uniquely identify the created audit requests (ordered by creation date).

Currently only bank audit requests are allowed. To see all banks that are supported please consult the get all banks endpoint.

Request Parameters

All parameters are required.

Parameter Type Description
auditRequests List<AuditRequest> Audit requests that will be sent to the audit client
client String E-mail address for the audit client's contact
language String The language used for the e-mail sent to the audit client (also controls the language for the signing process)
user String E-mail address used to uniquely identify a user in the audit company making the API request. If the user is already registered in Brevio the audit request will instantly show up in her dashboard. If she is not registered she will receive an e-mail notifying her that she has been assigned to an audit request
vatNo Integer (9 digits) The VAT number for the audit requests' associated audit client 
GET /v1/confirm/audit-requests/third-party HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
    "auditRequests": [
        {
            "bank": "4d88918a739dc0407dba87260e0cacf36a534079f26ad590e5c7a5fc3281b1ac",
            "cutOffDate": "2019-12-31"
        },
                {
            "bank": "8c371a71baf24bd1b97663eb08a4478e69ccf6ea2d2d25beafedb657bd3016a3",
            "cutOffDate": "2019-12-31"
        },
                {
            "bank": "8c371a71baf24bd1b97663eb08a4478e69ccf6ea2d2d25beafedb657bd3016a3",
            "cutOffDate": "2019-12-31"
        }],
    "client": "[email protected]",
    "language": "nb",
    "user": "[email protected]",
    "vatNo": 989891332
}

curl "https://api.brevio.com/v1/confirm/audit-requests/third-party" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data '{"auditRequests": [{"bank": "4d88918a739dc0407dba87260e0cacf36a534079f26ad590e5c7a5fc3281b1ac","cutOffDate": "2019-12-31"}, {"bank": "8c371a71baf24bd1b97663eb08a4478e69ccf6ea2d2d25beafedb657bd3016a3", "cutOffDate": "2019-12-31"},{"bank": "8c371a71baf24bd1b97663eb08a4478e69ccf6ea2d2d25beafedb657bd3016a3","cutOffDate": "2019-12-31"}], "client": "[email protected]",  "language": "nb",   "user": "[email protected]", "vatNo": 989891332}'

import request from "superagent";

request
  .post("https://api.brevio.com/v1/confirm/audit-requests/")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
   { auditRequests:
      [ { bank: '4d88918a739dc0407dba87260e0cacf36a534079f26ad590e5c7a5fc3281b1ac',
          cutOffDate: '2019-12-31' },
        { bank: '8c371a71baf24bd1b97663eb08a4478e69ccf6ea2d2d25beafedb657bd3016a3',
          cutOffDate: '2019-12-31',
          language: 'en' },
        { bank: '8c371a71baf24bd1b97663eb08a4478e69ccf6ea2d2d25beafedb657bd3016a3',
          cutOffDate: '2019-12-31',
          subsidiaries: [12345678912, 98765432198] }],
     client: '[email protected]',
     language: 'nb',
     user: '[email protected]',
     vatNo: 989891332 },
  })

API Response

{
  "tokens": [
    "616f6a6e7c4c5a3067afff6e6cd4ab0b4b889dfc922ef0f767d8a4d7cb7eddb0",
    "11abefac8cc529470fc8f1b73db29598cc49e51e049e158b68e4fe8ce5fb8628",
    "1f8c6c2b24ea3b7d51ec802a6c1396ef1c35edc7d3cd184693dbf0a617824cfa"
  ],
  "sent": true // if false, the user has received an e-mail prompting her to register a Brevio account and authenticate through BankID
}

Audit Request

All audit requests in the auditRequests request parameter need to adhere to the following structure:

Attribute Type Required Description
bank String true Token of the bank the audit request pertains to (see endpoint for listing banks GET /v1/confirm/banks-full)
cutOffDate Date true ISO8601 date string representing the end of the fiscal year for the associated audit client
daughterCompanies List<Integer> false DEPRECATED - USE SUBSIDIARIES INSTEAD List of VAT numbers for any associated subsidiaries for the audit client
language Language false Language for the audit request (valid values: nb, en). Defaults to nb (also controls the language for the confirmation process)
reminder Boolean false Should the audit request generate reminder e-mails to the audit client and third party when they do not respond within predefined time intervals? Defaults to true
subsidiaries List<Integer> false List of VAT numbers for any associated subsidiaries for the audit client

Response

Attribute Type Description
sent Boolean Boolean flag indicating whether the audit requests were sent to the audit client or not. Only e-mails with an assoicated Brevio account authenticated through BankID are allowed to send audit requests. If this flag is false it means the supplied e-mail did not have an assoicated account. An e-mail has been sent to the provided e-mail to promt the user to authenticate through BankID, once this is completed the pending audit requests will be sent automatically
tokens List<String> List of unique identifiers for the created audit requests.

Get all Bank names

This endpoint only returns Norwegian banks, use the new endpoint to get a complete list.

URL: /v1/confirm/banks
Method: GET
Allowed scopes: audit-company

Audit requests are associated with banks by the bank's name. To see all banks that are supported the following endpoint can be used. Name matching in the API is case insensitive.

Request parameters

This endpoint doesn't allow any request parameters.

GET /v1/confirm/banks HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json

curl "https://api.brevio.com/v1/confirm/banks" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \

import request from "superagent";

request
  .get("https://api.brevio.com/v1/confirm/banks/")
  .set("Authorization", `Bearer ${accessToken}`);

API Response

{
  ["Aasen Sparebank", "Åfjord Sparebank", "Andebu Sparebank", "Arendal og Omegn Sparekasse", ... ] // and so forth
}

Get all Banks

URL: /v1/confirm/banks-full
Method: GET
Allowed scopes: audit-company

Audit requests are associated with banks through the bank's unique token. To see all banks that are supported the following endpoint can be used.

This list is continually expanded as Brevio offers to send requests to additional banks. When caching this data, the cache should be updated frequently. The name is subject to change, so deduplicating should be done using the token if you perform partial updates of the cache.

Request parameters

This endpoint doesn't allow any request parameters.

GET /v1/confirm/banks-full HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json

curl "https://api.brevio.com/v1/confirm/banks-full" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \

import request from "superagent";

request
  .get("https://api.brevio.com/v1/confirm/banks-full")
  .set("Authorization", `Bearer ${accessToken}`);

API Response

[
  {
    "token": "4d88918a739dc0407dba87260e0cacf36a534079f26ad590e5c7a5fc3281b1ac",
    "country": "no",
    "disabled": false,
    "name": "Nordea"
  },
  {
    "token": "8c371a71baf24bd1b97663eb08a4478e69ccf6ea2d2d25beafedb657bd3016a3",
    "country": "se",
    "disabled": false,
    "name": "Nordea"
  }
]

Response

The response is List<Bank>.

Bank

All banks in the API response have the following structure.

Attribute Type Description
token String Unique identifier
country String Two character country code, as defined by ISO 3166-1 alpha-2. E.g. `'no'
disabled Boolean Disabled banks cannot receive new audit requests, but they can have existing requests sent before the disabling occurred
name String The name of the bank. Not guaranteed to be unique, so use token to deduplicate when updating the list.

Download Audit Request Attachment

URL: /v1/confirm/attachments/:attachment-token/signed-url
Method: POST
Allowed scopes: audit-company, bank

This endpoint returns a short-lived (24 hours) signed URL (in accordance with information security best practices) to download an attachment associated with an audit request. The :attachment-token part of the URL needs to be replaced with the attachment's token, retrieved in the API response for the audit request (in the attachments array).

The attachments can be PDFs, images, Microsoft Office files (.xlsx etc.) and XML. The valid content types are subject change without notice, so you should not make assumptions on which type of file you get back. The file extension in the name field will always match the content mime type.

Request Parameters

Parameter Type Description
attachment-token String Unique identifier for attachment 
POST /v1/confirm/attachments/7c1a0413672e8e135b9c550e6b20691630e621b5001e602827e0a37a50571f82/signed-url HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: application/json

curl "https://api.brevio.com/v1/confirm/attachments/${ATTACHMENT_TOKEN}/signed-url" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

import request from "superagent";

request
  .post(
    `https://api.brevio.com/v1/confirm/attachments/${attachmentToken}/signed-url`
  )
  .set("Authorization", `Bearer ${accessToken}`);

API Response

{
  "name": "document.pdf",
  "url": "https://example-url.com/document.pdf?expires=24hours"
}

Response

Attribute Type Description
name String The filename for the attachment shown to end users
url String The signed URL for the attachment (expires in 24 hours)

Upload Attachments to a Confirmation

URL: /v1/confirm/audit-requests/:token/upload
Method: POST
Allowed scopes: bank

This endpoint allows a bank to upload attachments for the confirmation of an audit request. In cases where the number of attachments for a confirmation exceeds five (which is the limit imposed on the confirmation endpoint to avoid network congestion) this endpoint can be used to batch-upload attachments (maximum 5 at at time here as well for the same reasons - i.e. to avoid congestion).

The Content-Type header needs to be set to multipart/form-data to successfully attach the files.

The :token part of the URL needs to be replaced with the audit request's token.

Request Parameters

Parameter Type Required Description
token String true Unique identifier for the audit request
attachments List<File> true List of files (at most five) 
POST /v1/confirm/audit-requests/aaaa32cf6c3453bfc7923e00d33002ea7b5277767524639f0e09da561c380ade/upload HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: multipart/form-data;

Content-Disposition: form-data; name="attachments"; filename="confirmation.pdf
Content-Disposition: form-data; name="attachments"; filename="confirmation-extra.pdf
Content-Disposition: form-data; name="attachments"; filename="confirmation-extra2.pdf
Content-Disposition: form-data; name="attachments"; filename="confirmation-extra3.pdf
Content-Disposition: form-data; name="attachments"; filename="confirmation-extra4.pdf

curl "https://api.brevio.com/v1/confirm/audit-requests/${REQUEST_TOKEN}/upload" \
  --request POST \
  --user "example:secret" \
  --header 'Content-Type: multipart/form-data' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
  --form attachments=@confirmation.pdf
  --form attachments=@confirmation-extra.pdf
  --form attachments=@confirmation-extra2.pdf
  --form attachments=@confirmation-extra3.pdf
  --form attachments=@confirmation-extra4.pdf

import request from "superagent";

request
  .post(
    `https://api.brevio.com/v1/confirm/audit-requests/${requestToken}/upload`
  )
  .set("Authorization", `Bearer ${accessToken}`)
  .attach("attachments", "confirmation.pdf")
  .attach("attachments", "confirmation-extra.pdf");
  .attach("attachments", "confirmation-extra2.pdf");
  .attach("attachments", "confirmation-extra3.ppdf");
  .attach("attachments", "confirmation-extra4.pdf");

Response

Attribute Type Description
message String Textual message indicating number of attachments successfully uploaded

API Response

{
  "message": "Uploaded 5 attachments"
}

Comment and finalize an erroneous Audit Request

URL: /v1/confirm/audit-requests/:token/confirmation-comment
Method: POST
Allowed scopes: bank

This endpoint allows a bank to post a comment and finalize an audit request sent in error. If an auditor has sent an audit request to the bank for a client which isn't a customer of the bank, this endpoint allows the bank to communciate to the auditor that the audit request has been sent in error with a required clarifying comment (maximum 200 characters).

Once the comment has been sent, the auditor will receive a notification that the audit request has been finalized.

The :token part of the URL needs to be replaced with the audit request's token.

POST /v1/confirm/audit-requests/aaaa32cf6c3453bfc7923e00d33002ea7b5277767524639f0e09da561c380ade/confirmation HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: application/json;
{
  "comment": "The client (987654321) is not a customer of our bank."
}

curl "https://api.brevio.com/v1/confirm/audit-requests/${REQUEST_TOKEN}/confirmation-comment" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{"comment": "The client (987654321) is not a customer of our bank."}'

import request from "superagent";

request
  .post(`https://api.brevio.com/v1/confirm/audit-requests/${REQUEST_TOKEN}/confirmation-comment`)
  .set("Authorization", `Bearer ${accessToken}`)
  .send({ comment: "The client (987654321) is not a customer of our bank"}}

Request Parameters

Parameter Type Required Description
comment String true Comment clarifying why the audit request was sent in error (maximum 200 characters).

API Response

{ "message": "Audit request completed and notification sent to auditor" }

Send a Confirmation

URL: /v1/confirm/audit-requests/:token/confirmation
Method: POST
Allowed scopes: bank

This endpoint allows a bank to programmatically answer a received audit request. A confirmation needs an uploaded attachment to be valid. This can either be accomplished through the update endpoint, or by specifying one or more attachments in the attachments parameter (the API accepts a single file, or an array of files - though no more than five).

The Content-Type header needs to be set to multipart/form-data to successfully attach the files.

The :token part of the URL needs to be replaced with the audit request's token.

POST /v1/confirm/audit-requests/aaaa32cf6c3453bfc7923e00d33002ea7b5277767524639f0e09da561c380ade/confirmation HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: multipart/form-data;

Content-Disposition: form-data; name="attachments"; filename="confirmation.pdf
Content-Disposition: form-data; name="attachments"; filename="confirmation-extra.pdf

curl "https://api.brevio.com/v1/confirm/audit-requests/${REQUEST_TOKEN}/confirmation" \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
  --form attachments=@confirmation.pdf
  --form attachments=@confirmation-extra.pdf

import request from "superagent";

request
  .post(
    `https://api.brevio.com/v1/confirm/audit-requests/${requestToken}/confirmation`
  )
  .set("Authorization", `Bearer ${accessToken}`)
  .attach("attachments", "confirmation.pdf")
  .attach("attachments", "confirmation-extra.pdf");

Request Parameters

Parameter Type Required Description
token String true Unique identifier for the audit request
attachments List<File> false List of files (at most five) 
POST /v1/confirm/audit-requests/aaaa32cf6c3453bfc7923e00d33002ea7b5277767524639f0e09da561c380ade/confirmation HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: multipart/form-data;

Content-Disposition: form-data; name="attachments"; filename="confirmation.pdf
Content-Disposition: form-data; name="attachments"; filename="confirmation-extra.pdf

curl "https://api.brevio.com/v1/confirm/audit-requests/${REQUEST_TOKEN}/confirmation" \
  --request POST \
  --user "example:secret" \
  --header 'Content-Type: multipart/form-data' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
  --form attachments=@confirmation.pdf
  --form attachments=@confirmation-extra.pdf

import request from "superagent";

request
  .post(
    `https://api.brevio.com/v1/confirm/audit-requests/${requestToken}/confirmation`
  )
  .set("Authorization", `Bearer ${accessToken}`)
  .attach("attachments", "confirmation.pdf")
  .attach("attachments", "confirmation-extra.pdf");

Response

Attribute Type Description
token String Unique identifier for the audit request
step String The step in the audit request process request is currently at, should be 'received'

API Response

{
  "token": "aaaa32cf6c3453bfc7923e00d33002ea7b5277767524639f0e09da561c380ade",
  "step": "received"
}

Brevio Sign API

The Sign API is used to interact with requests for digital signatures (called sign requests), their associated signees, and the uploaded PDF documents intended for signature. All dates and datetime values adhere to the ISO8601 standard and are stored in UTC.

Create Sign Request for audit client

URL: /v1/sign/sign-requests
Method:: POST
Allowed scopes: audit-company

This endpoint is used to create sign requests with an attachment and a list of signees for a given VAT number associated with an audit client.

Request Parameters

Parameter Type Required Description
attachments List<Attachment> true List of Attachments for the sign request. Currently only one attachment is allowed per sign request
vatNo Integer (9 digits) true The VAT number for the sign request's associated audit client
language String true The language of the sign request. Valid values are nb, sv, da, en
signees List<String> true A list of signees(e-mail) whom are required to sign the sign request. Needs to contain at least one signee
title String true The title of the sign request (appears in the email and in the actual service)
user String true E-mail address used to uniquely identify a user in the audit company making the API request. If the user is already registered in Brevio the sign request will instantly show up in her dashboard. If she is not registered she will receive an e-mail notifying her that she has been assigned to a sign request
dueDays Integer false Valid values: (7, 14, 30). The number of days hence the sign request will no longer be available. Defaults to 30 if not present or an invalid value is passed.
message String false Message to be displayed in the sign request. Will overwrite message from request template
template String false Token of request template to be applied to the sign request. See get all request templates endpoint

API Request

POST /v1/sign/sign-requests HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: application/json;

{
    "vatNo": 123456789,
    "signees": ["[email protected]", "[email protected]"],
    "language": "nb",
    "title": "Title",
    "due_days": 14,
    "message": "Sign request message",
    "template": "0ad0fbadcf7c095a9ddcba740eeec559",
    "user": "[email protected]",
    "attachments": [{"filename": "File.pdf", "attachment": "JVBERi0..."}]
}

curl "https://api.brevio.com/v1/sign/sign-requests" \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --date '{"vatNo":123456789,"signees":["[email protected]","[email protected]"],"language":"nb","title":"Title","due_days":14,"message":"Sign request message","template":"0ad0fbadcf7c095a9ddcba740eeec559","user":"[email protected]","attachments":[{"filename":"File.pdf","attachment":"JVBERi0..."}]}'

import request from "superagent";

request
  .post("https://api.brevio.com/v1/sign/sign-requests")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
   { vatNo: 123456789,
    signees: ["[email protected]", "[email protected]"],
    language: "nb",
    title: "Title",
    dueDays: 14,
    message: "Sign request message",
    template: "0ad0fbadcf7c095a9ddcba740eeec559",
    user: "[email protected]",
    attachments: [{filename: "File.pdf", attachment: "JVBERi0..."}] },
  })

Attachment

All attachments in the attachments request parameter need to adhere to the following structure:

Attribute Type Required Description
filename String true filename of the attached file. We only support .pdf files
attachment String true base64 encoded string of the actual file

Response

Attribute Type Description
token String The token of the created sign request

API Response

{
  "token": "9ff3501c5709b5211bca67013e7f051202fd3fe5099b63391c134eedecb5d3e9"
}

Get all Sign Requests for audit client

URL: /v1/sign/sign-requests
Method:: GET
Allowed scopes: audit-company
Optional scopes: signee-pid

This endpoint returns all associated sign requests for an authorized API client, filtered by the VAT number of the sign requests' associated audit client (named company in the API response).

The payload contains at most 50 requests. To access all associated sign requests (in cases where there are more than 50) you have to paginate through the results.

Request Parameters

Parameter Type Required Description
vatNo Integer (9 digits) true The VAT number for the sign requests' associated audit client
templateToken string false The desired request template you wish to filter the results by. Use the endpoint below to find tokens and template titles for your Company
offset Integer false The offset used for pagination

API Request

GET /v1/sign/sign-requests HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "vatNo": 123456789
}

curl "https://api.brevio.com/v1/sign/sign-requests" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{"vatNo": 123456789 }'

import request from "superagent";

request
  .get("https://api.brevio.com/v1/sign/sign-requests")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
    vatNo: 123456789,
  });

Response

Attribute Type Description
count Integer The number of sign requests returned in the query
offset Integer The offset used for the query
next Integer The next offset to be used for further pagination
total Integer The total number of sign requests filtered by the passed VAT number (and template)
requests List<SignRequest> List of sign requests

API Response

{
  "count": 50,
  "offset": 0,
  "next": 50,
  "total": 131,
  "requests": [
    // ...
  ]
}

API Response (offset = 50)

{
  "count": 50,
  "offset": 50,
  "next": 100,
  "total": 131,
  "requests": [
    // ...
  ]
}

Sign Request

All sign requests in the requests attribute in the API response have the following structure.

Attribute Type  Description
token String Unique identifier
attachments List<String> List of tokens used to uniquely identify an attachment
company Integer Audit client VAT number
dueDate Date Date the current sign request is due (i.e. can no longer be signed)
dueDays Integer Deprecated Days between the due date and the sent date
lastUpdate DateTime Last time step was updated
templateToken String? The request template used for the sign request, if relevant. The title of the requestTemplate can be found through the request-template endpoint.
sent DateTime Date and time sign request was sent to all signees
signees List<Signee> List of all associated signees
step String The step in the signature process the request is currently at. Valid values: 'started', 'sign', 'completed', 'archived', 'cancelled'

Sign Request

{
  "token": "9ff3501c5709b5211bca67013e7f051202fd3fe5099b63391c134eedecb5d3e9",
  "attachments": [],
  "company": 123456789,
  "dueDate": "2019-11-13",
  "dueDays": 30,
  "lastUpdate": "2019-10-14 13:06:15",
  "sent": "2019-10-13 16:29:32",
  "signees": [
    {
      "email": "[email protected]",
      "signed": false,
      "signedAt": null,
      "signedName": null
    },
    {
      "email": "[email protected]",
      "signed": true,
      "signedAt": "2019-10-14 13:06:15",
      "signedName": "Ford Prefect"
    }
  ],
  "step": "sign",
  "template": "annual-report"
}

Signee

Attribute Type Description
email String The signee's email address (where all sign requests will be sent)
signed Boolean Has the signee signed the sign request?
signedAt DateTime? When was the sign request signed by this signee? (if at all)
signedName String? Name retrieved from BankID upon completing the signature process
signeePID String? Personal ID (PID) is the signee's personal number - NO: 11 digits, SE: 10 or 12 digits, DK: 10 digits. Only available with scope 'signee-pid'

Signee

// Not yet signed
{
  "email": "[email protected]",
  "signed": false,
  "signedAt": null,
  "signeePID": null,
  "signedName": null
}
// Signed
{
  "email": "[email protected]",
  "signed": true,
  "signedAt": "2019-10-14 13:06:15",
  "signeePID": "31120000767",
  "signedName": "Ford Prefect"
}

Download Sign Request Attachment

URL: /v1/sign/attachments/:attachment-token/signed-url
Method:: POST
Allowed scopes: audit-company

This endpoint returns a short-lived (24 hours) signed URL (in accordance with information security best practices) to download an attachment associated with a sign request. The :attachment-token part of the URL needs to be replaced with the attachment's token, retrieved in the API response for the sign request (in the attachments array).

Request Parameters

Parameter Type Description
attachment-token String Unique identifier for attachment 
POST /v1/confirm/attachments/7c1a0413672e8e135b9c550e6b20691630e621b5001e602827e0a37a50571f82/signed-url HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: application/json

curl "https://api.brevio.com/v1/sign/attachments/${ATTACHMENT_TOKEN}/signed-url" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

import request from "superagent";

request
  .post(
    `https://api.brevio.com/v1/sign/attachments/${attachmentToken}/signed-url`
  )
  .set("Authorization", `Bearer ${accessToken}`);

API Response

{
  "name": "signed-pdf.pdf",
  "url": "https://example-url.com/signed-pdf.pdf?expires=24hours"
}

Response

Attribute Type Description
name String The filename for the attachment shown to end users
url String The signed URL for the attachment (expires in 24 hours)

Get all Request Templates for audit company

URL: /v1/sign/request-templates
Method:: GET
Allowed scopes: audit-company

This endpoint returns all associated request templates for an authorized API client.

There can be a maximum of 12 active request templates for an audit company, and an unlimited number of inactive templates. The maximum count should be considered subject to change. Inactive templates are no longer visible for end users.

For each request template we returns i18ns - internationalizations. These provide the user visible titles that are selected when sending sign requests. These are set by the admin in an audit company, and are provided so that you can coordinate any special meaning given to a specific template, or if you want to display the title of the template to your end users.

This endpoint does not use pagination.

The returned tokens can be used to filter sign requests by the templateToken attribute in the get all sign requests endpoint.

Request parameters

This endpoint does not accept parameters.

API Request

GET /v1/sign/request-templates HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json

curl "https://api.brevio.com/v1/sign/request-templates" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

import request from "superagent";

request
  .get("https://api.brevio.com/v1/sign/request-templates")
  .set("Authorization", `Bearer ${accessToken}`);

Response

API Response

{
  "templates": [
    {
      "token": "a0eaf8107e16f6af3a6d3659afc997d5",
      "active": true,
      "i18ns": [
        {
          "language": "nb",
          "title": "Revisjonsberetning"
        },
        {
          "language": "en",
          "title": "Auditor's report"
        }
      ]
    },
    {
      "token": "9a75bf516d7d26b55e96b97a648c566e",
      "active": false,
      "i18ns": [
        {
          "language": "nb",
          "title": "Årsregnskap"
        },
        {
          "language": "en",
          "title": "Annual report"
        }
      ]
    }
  ]
}
Attribute Type Description
templates List<RequestTemplate> List of request templates

RequestTemplate

Attribute Type Description
token String Unique token per RequestTemplate. Can be found in SignRequests named templateToken.
active Boolean Indicates whether new sign requests can be sent with this template. Inactive templates will never become active again.
i18ns List<I18n> List of the title of the RequestTemplate in different languages.

I18n

Attribute Type Description
language String Language following ISO 639-1.
title String User visible title of the RequestTemplate in the Brevio Sign application.

Brevio Signature-right API

The Signature-right API is used to verify whether a given national ID is allowed to digitally sign for a given company, either in combination with others or individually. All dates and datetime values adhere to the ISO8601 standard and are stored in UTC.

Signature-right sources are as follows:

Get signing right for a person on a given company

URL: /v1/signature-right
Method:: GET
Allowed scopes: signature-right

This endpoint returns signature-right information, filtered by the VAT number of the associated company and the National ID (SSN - Social Security Number of the associated person to verify signing-right for. Currently Swedish, Norwegian and Danish companies are supported using country code se for Sweden, no for Norway and dk for Denmark.

Request Parameters

Parameter Type Required Description
vatNo Integer (8-10 digits) true The VAT number for the company (8 digits for danish, 9 digits for Norwegian, and 10 digits for Swedish).
nationalId string true National id / SSN used to verify signing right
country string true Countries for which the check is performed. Valid countries: se no dk

API Request

GET /v1/signature-right?signature-right?vatNo=5564779444&nationalId=196805029268&country=se HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: application/json


curl "https://api.brevio.com/v1/signature-right?vatNo=${VAT_NO}&nationalId=${NATIONAL_ID}&country=${COUNTRY}" \
  --request GET \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \

import request from "superagent";

request
  .get(
    `https://api.brevio.com/v1/signature-right?vatNo=${vatNo}&nationalId=${nationalId}&country=${country}`
  )
  .set("Authorization", `Bearer ${accessToken}`);

Response

Attribute Type Description
changeDate string The date when signing rule was last changed(valid from) 'yyyy-mm-dd'
vatNo string VAT number of company which signing-right are checked
nationalId string National Id / Social security number of person which signing-right are checked
signingRight string SigningRight of person. Valid values are 'ALONE' or 'GROUP'.

An empty response is denoted by a 200 OK {} with empty json object returned.

API Response

{
  "changeDate": "2019-12-11",
  "vatNo": "5564779444",
  "nationalId": "196805029268",
  "signingRight": "ALONE"
}

SigningRight

A signingRight can either be ALONE or GROUP.

Errors

The Brevio APIs use the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API credentials or authentication token is wrong.
404 Not Found -- The specified resource could not be found.
500 Internal Server Error -- We had a problem with our server. Send us an email, or try again later.

Error response

{
  "status": 400,
  "error_description": "Bad request: vatNo is missing"
}
http shell javascript