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/

POST /v1/confirm/audit-requests/finalize

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

POST /v1/confirm/audit-requests/

GET /v1/confirm/banks/

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

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

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

POST /v1/sign/attachments

POST /v1/sign/sign-requests

GET /v1/sign/sign-requests

GET /v1/sign/sign-requests/updates

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

GET /v1/sign/document-templates

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, signee_pid, and vendor are valid scopes. All scopes will be validated by Brevio upon the creation of an API client.

The signature_right and signee_pid scopes requires specific access, please contact us for more information.

The vendor scope allows an API client to perform API calls on behalf of a consumer, which is identified by a unique consumerKey passed with each API call. Please contact us for more information.

Get Access token

URL: /auth/token
Method: POST
Allowed scopes: audit_company, bank, signature_right, signee_pid, vendor

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', 'vendor'

API Request

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

POST /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/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/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.

All Confirm API endpoints

GET /v1/confirm/audit-requests/

POST /v1/confirm/audit-requests/finalize

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

POST /v1/confirm/audit-requests/

GET /v1/confirm/banks/

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

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

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

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 e-mail 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<String> 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.

Finalize Audit Requests

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

This endpoint allows the audit company to mark a set of audit requests (identified by their unique tokens) as received by the auditor outside Brevio. A total of 10 audit request tokens are allowed with each request.

Note that only audit requests that have been sent to their respective third parties can be finalized.

Request Parameters

Parameter Type Required Description
auditRequestTokens List<String> true The list of audit request tokens indicating which audit requests to finalize. NB A maximum of 10 tokens is allowed

API Request

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

{
  "auditRequestTokens": [
    "64626932a178531926b23cf09eb10f8dea2283108950e7ce106b689128ce9f2e",
    "d78021f0a0ff15d5690e767f46bbad407f8d9cd5ef99710258e2e95342f7d84a",
    "fde3589c53d55a04dd2b0c5bcabb66dc110649f9449e8b9441542439182f0e39"
  ]
}

curl "https://api.brevio.com/v1/confirm/audit-requests/finalize" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data
    '{
      "auditRequestTokens": [
        "64626932a178531926b23cf09eb10f8dea2283108950e7ce106b689128ce9f2e",
        "d78021f0a0ff15d5690e767f46bbad407f8d9cd5ef99710258e2e95342f7d84a",
        "fde3589c53d55a04dd2b0c5bcabb66dc110649f9449e8b9441542439182f0e39"
      ]
    }'

import request from "superagent";

request
  .get("https://api.brevio.com/v1/confirm/audit-requests/finalize")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
    auditRequestTokens: [
      "64626932a178531926b23cf09eb10f8dea2283108950e7ce106b689128ce9f2e",
      "d78021f0a0ff15d5690e767f46bbad407f8d9cd5ef99710258e2e95342f7d84a",
      "fde3589c53d55a04dd2b0c5bcabb66dc110649f9449e8b9441542439182f0e39",
    ],
  });

Response

Attribute Type Description
successful List<String> List of tokens which were successfully finalized
failed List<String> List of tokens which failed during finalization

API response

{
  "successful": [
    "64626932a178531926b23cf09eb10f8dea2283108950e7ce106b689128ce9f2e",
    "d78021f0a0ff15d5690e767f46bbad407f8d9cd5ef99710258e2e95342f7d84a"
  ],
  "failed": ["fde3589c53d55a04dd2b0c5bcabb66dc110649f9449e8b9441542439182f0e39"]
}

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 DEPRECATED - Use accountNumbers instead Bank account number formatted according to the country of the associated bank (e.g. 11 characters for Norwegian banks separated by dots). NB: This only represents the account number of the main company associated with the audit request. If there are multiple account numbers associated with the request, then these will be listed in the accountNumbers property and the manualReview flag will be set.
accountNumbers List<AccountNumber> List of all account numbers associated with the audit request
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 String 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 for instance 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<String> List of VAT numbers for any associated subsidiaries for the audit client

Audit Request

{
  "token": "aaaa32cf6c3453bfc7923e00d33002ea7b5277767524639f0e09da561c380ade",
  "accountNumber": "1234.56.78912",
  "accountNumbers": [
    {
      "accountNumber": "1234.56.78912",
      "vatNo": "123456789"
    },
    {
      "accountNumber": "8080.66.48911",
      "vatNo": "334567899"
    }
  ],
  "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": true // since it has multiple account numbers present
}

Account Number

Attribute Type Description
accountNumber String The account number filled in by the audit client, formatted in accordance with the associated bank's country
vatNo String The VAT number of the company associated with the account number (will match either the main company of the audit request, or one of the subsidiaries)

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 String 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 Banks

URL: /v1/confirm/banks
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 HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json

curl "/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

[
  {
    "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 only accepts an array of files, containing no more than five attachments).

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)

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.

All Sign API endpoints

POST /v1/sign/attachments

POST /v1/sign/sign-requests

GET /v1/sign/sign-requests

GET /v1/sign/sign-requests/updates

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

GET /v1/sign/document-templates

Upload attachments

URL: /v1/sign/attachments
Method:: POST
Allowed scopes: audit_company, vendor

This endpoint is used to upload attachments (e.g. PDF files) to be used in a sign request. Currently a maximum of five attachments are allowed per API request (to avoid timeouts).

A vendor can use this endpoint to upload attachments on behalf of its consumers by passing a valid consumerKey.

Request Parameters

Parameter Type Required Description
attachments List true List of files (only PDF files allowed ATOW) to be uploaded to the Brevio platform (currently a maximum of five attachments per API request is allowed).
user String true The user (e.g. auditor) which should be associated with the uploaded attachment.
consumerKey String false The consumer key for the consumer you wish to create the attachment on behalf of. Required for vendor scopes.

API Request

POST /v1/sign/attachments HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <token>
Content-Type: multipart/form-data;
Content-Disposition: form-data; name="user"; [email protected]
Content-Disposition: form-data; name="consumerKey"; 2e34440d35d153820f6a7fd54e41dd1c (only vendors)
Content-Disposition: form-data; name="attachments[]"; filename="engagement_letter.pdf"
Content-Disposition: form-data; name="attachments[]"; filename="auditor_report.pdf"

curl "https://api.brevio.com/v1/sign/attachments" \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --form "[email protected]"
  --form "consumerKey=2e34440d35d153820f6a7fd54e41dd1c" # only vendors
  --form "attachments[][email protected]_letter.pdf"
  --form "attachments[][email protected]_report.pdf"

import request from "superagent";

request
  .post("https://api.brevio.com/v1/sign/sign-requests")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
    user: "[email protected]",
    consumerKey: "2e34440d35d153820f6a7fd54e41dd1c" // only vendors
  });
  .attach("attachments[]", "engagement_letter.pdf")
  .attach("attachments[]", "auditor_report.pdf")

Response

Attribute Type Description
tokens List List of unique identifiers (token) for the created attachments

API Response

{
  "tokens": [
    "9ff3501c5709b5211bca67013e7f051202fd3fe5099b63391c134eedecb5d3e9",
    "f0cc7f7e9ade1644913a32b3ba440a8ee019bd9a2c7f69bb3a3c97a484155a63"
  ]
}

Create Sign Request

URL: /v1/sign/sign-requests
Method:: POST
Allowed scopes: audit_company, vendor

This endpoint is used to create a sign request containing a list of attachments (e.g. PDFs) to be digitally signed by a list of supplied signees. Each sign request is associated with an audit client through a validated VAT number.

A vendor can use this endpoint to create a sign request on behalf of its consumers by passing a valid consumerKey.

Once the sign request is created, it is not sent directly, but placed in the 'Started' column for the associated auditor to be edited/verified before sending.

Request Parameters

Parameter Type Required Description
attachments List<Attachment> true List of Attachments for the sign request (currently a maximum of five attachments per sign request is allowed).
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
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
signees List<Signee> false List of Signees who are required to sign the 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 replace the default message).
consumerKey String false The consumer key for the consumer you wish to create the sign request on behalf of. Required for vendor scopes.

API Request

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

   {
    "vatNo": 999888777,
    "signees": [
      {
        "email": "[email protected]",
        "order": 1
      },
      {
        "email": "[email protected]",
        "order": 1
      },
      {
        "email": "[email protected]",
        "order": 2
      }
    ],
    "language": "nb",
    "dueDays": 14,
    "message": "Sign request message",
    "user": "[email protected]",
    "attachments": [
      {
        "token": "0126a84017de0e70b6440820decbb565",
        "title": "Auditor's report"
      },
      {
        "token": "95df519c2f4d5bf3040bab3e7a730f60",
        "title": "Engagement Letter",
        "template": "f7c2e7b859862ac29650bd098dfedfb6"
      }
    ],
    "consumerKey": "2e34440d35d153820f6a7fd54e41dd1c" # only for vendors
  })

curl "https://api.brevio.com/v1/sign/sign-requests" \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{"vatNo":999888777,"signees":[{ "email": "[email protected]", "order": 1}' \
  '{ "email": "[email protected]", "order": 1}, { "email": "[email protected]", order: 2}],"language":"nb","due_days":14,' \
  '"message":"Sign request message","user":"[email protected]",' \
  '"attachments": [{ "token": "0126a84017de0e70b6440820decbb565", title: "Auditors report"}, { "token": "95df519c2f4d5bf3040bab3e7a730f60", "title": "Engagement Letter", "template": "f7c2e7b859862ac29650bd098dfedfb6" }]' \
  '"consumerKey": "2e34440d35d153820f6a7fd54e41dd1c"' # only for vendors

import request from "superagent";

request
  .post("https://api.brevio.com/v1/sign/sign-requests")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
   {
    vatNo: 999888777,
    signees: [
      {
        email: "[email protected]",
        order: 1
      },
      {
        email: "[email protected]",
        order: 1
      },
      {
        email: "[email protected]",
        order: 2
      }
    ],
    language: "nb",
    dueDays: 14,
    message: "Sign request message",
    user: "[email protected]",
    attachments: [
      {
        token: "0126a84017de0e70b6440820decbb565",
        title: "Auditor's report"
      },
      {
        token: "95df519c2f4d5bf3040bab3e7a730f60",
        title: "Engagement Letter",
        template: "f7c2e7b859862ac29650bd098dfedfb6"
      }
    ],
    consumerKey: "2e34440d35d153820f6a7fd54e41dd1c" // only for vendors
  })

Attachment

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

Attribute Type Required Description
token String true Unique token identifying the attachment (received when uploading an attachment in the #UPLOAD_ATTACHMENT_ENDPOINT).
title String true Title for the uploaded attachment, shown in a comma-separated list in the sign request
template String false Token identifying an optional DocumentTemplate for this attachment

Signees

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

Attribute Type Required Description
email String true Email address for the signee which the sign request should be sent to
order Number false Signature order for the signee. Add this only if you want the particular signee to sign before or after other signees (signees with the same order will receive the sign request at the same time.)

Response

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

API Response

{
  "token": "9ff3501c5709b5211bca67013e7f051202fd3fe5099b63391c134eedecb5d3e9"
}

Get all Sign Requests

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 token of a desired document template you wish to filter the results by. If a sign request contains any attachments with the provided document template then it is included in the result.
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<Attachment> List of attachments
company Integer Audit client VAT number
dueDate Date Date the current sign request is due (i.e. can no longer be signed)
lastUpdate DateTime Last time step was updated
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'

Attachment

Attribute Type Description
token String Unique identifier for the attachment
filename String Filename for the attachment
signedPDF Boolean Boolean flag indicating whether this is a digitally signed PDF. NB: The signed PDFs will only be shown after all signees have signed the sign request
template String? Unique identifor for an optional associated document template
title String The title for the uploaded attachment

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'

Sign Request

{
  "token": "9ff3501c5709b5211bca67013e7f051202fd3fe5099b63391c134eedecb5d3e9",
  "attachments": [
    {
      "token": "21d2b46ae46b16845caad19c2d6aac34",
      "filename": "engagement-letter-2021.pdf",
      "signedPDF": false,
      "template": null,
      "title": "Engagement letter"
    },
    {
      "token": "181fddae6a0edbc880ffe4c189e02aa0",
      "filename": "auditor-report-2021.pdf",
      "signedPDF": false,
      "template": "5f7ea5f1501d289e04fb6f14a118bf80",
      "title": "Auditor's report"
    }
  ],
  "company": 123456789,
  "dueDate": "2019-11-13",
  "dueDays": 30,
  "lastUpdate": "2019-10-14 13:06:15",
  "sent": "2019-10-13 16:29:32",
  "signees": [
    // Not signed yet
    {
      "email": "[email protected]",
      "signed": false,
      "signedAt": null,
      "signedName": null
    },
    // Has signed
    {
      "email": "[email protected]",
      "signed": true,
      "signedAt": "2019-10-14 13:06:15",
      "signedName": "Ford Prefect"
    }
  ],
  "step": "sign"
}

Get updated Sign Requests

URL: /v1/sign/sign-requests/updates
Method:: GET
Allowed scopes: audit_company
Optional scopes: signee_pid

This endpoint returns all associated sign requests for an authorized API client, returning only those sign requests that have been created after the passed fromDate (inclusive, meaning that passing 2022-01-01 will return all sign requests created after 2202-01-01 00:01).

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
fromDate String true ISO8601 date string representing the inclusive start of the date filter
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

{
  "fromDate": "2022-01-01"
}

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

import request from "superagent";

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

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 date
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<Attachment> List of attachments
company Integer Audit client VAT number
dueDate Date Date the current sign request is due (i.e. can no longer be signed)
lastUpdate DateTime Last time step was updated
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'

Attachment

Attribute Type Description
token String Unique identifier for the attachment
filename String Filename for the attachment
signedPDF Boolean Boolean flag indicating whether this is a digitally signed PDF. NB: The signed PDFs will only be shown after all signees have signed the sign request
template String? Unique identifor for an optional associated document template
title String The title for the uploaded attachment

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'

Sign Request

{
  "token": "9ff3501c5709b5211bca67013e7f051202fd3fe5099b63391c134eedecb5d3e9",
  "attachments": [
    {
      "token": "21d2b46ae46b16845caad19c2d6aac34",
      "filename": "engagement-letter-2021.pdf",
      "signedPDF": false,
      "template": null,
      "title": "Engagement letter"
    },
    {
      "token": "181fddae6a0edbc880ffe4c189e02aa0",
      "filename": "auditor-report-2021.pdf",
      "signedPDF": false,
      "template": "5f7ea5f1501d289e04fb6f14a118bf80",
      "title": "Auditor's report"
    }
  ],
  "company": 123456789,
  "dueDate": "2019-11-13",
  "dueDays": 30,
  "lastUpdate": "2019-10-14 13:06:15",
  "sent": "2019-10-13 16:29:32",
  "signees": [
    // Not signed yet
    {
      "email": "[email protected]",
      "signed": false,
      "signedAt": null,
      "signedName": null
    },
    // Has signed
    {
      "email": "[email protected]",
      "signed": true,
      "signedAt": "2019-10-14 13:06:15",
      "signedName": "Ford Prefect"
    }
  ],
  "step": "sign"
}

Download Sign Request Attachments

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",
  "filename": "signed-pdf.pdf",
  "url": "https://example-url.com/signed-pdf.pdf?expires=24hours"
}

Response

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

Get all Document Templates

URL: /v1/sign/document-templates
Method:: GET
Allowed scopes: audit_company

This endpoint returns all associated document templates for an authorized API client. Each uploaded attachment part of a sign request can be assigned a document template.

A document template has a list of internationalizations (returned as i18ns in the response object). These internationalizations are managed by admins for the audit company and provide a legible title for auditors to choose from in the graphical user interface.

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/document-templates HTTP/1.1
Host: api.brevio.com
Authorization: Bearer <access_token>
Content-Type: application/json

curl "https://api.brevio.com/v1/sign/document-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/document-templates")
  .set("Authorization", `Bearer ${accessToken}`);

Response

API Response

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

Document Template

Attribute Type Description
token String Unique identifier for the document template.
i18ns List<Internationalization> List of all associated internationalizations.

Internationalization

Attribute Type Description
language String Language code adhereing to the ISO 639-1 standard.
title String Title for the internationalization visible to auditors in the graphical user interface.

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?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 e-mail, or try again later.

Error response

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