NAV Navbar
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/

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 GET /v1/sign/attachments/:token/signed-url

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 only audit-company and bank are valid scopes, and they will be validated when you create your API user.

Get Access token

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

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'

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
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> List of VAT numbers for any associated daughter companies 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'
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"
  },
  "clientEmail": "arthur@dent-industries.org",
  "company": 123456789,
  "confirmation": [
    "56c435b336636c15d712c6a58090380aa0b27223928f3129ac534d8c6c60d6f3"
  ],
  "cutOffDate": "2019-31-12",
  "daughterCompanies": [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

Get all third party Audit Requests

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

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
cutOffDate Date The end of the fiscal year for the associated audit client
daughterCompanies List<Integer> List of VAT numbers for any associated daughter companies for the audit client
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

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",
  "daughterCompanies": [223456789, 334567899, 445678999],
  "manualReview": false
}

Auditor

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

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.

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": "nordea",
            "cutOffDate": "2019-12-31"
        },
                {
            "bank": "nordea",
            "cutOffDate": "2019-12-31"
        },
                {
            "bank": "nordea",
            "cutOffDate": "2019-12-31"
        }],
    "client": "nicolay@brevio.com",
    "language": "nb",
    "user": "nicolay@brevio.com",
    "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": "dnb","cutOffDate": "2019-12-31"}, {"bank": "danske bank", "cutOffDate": "2019-12-31"},{"bank": "nordea","cutOffDate": "2019-12-31"}], "client": "nicolay@brevio.com",  "language": "nb",   "user": "nicolay@brevio.com", "vatNo": 989891332}'
import request from "superagent";

request
  .post("https://api.brevio.com/v1/confirm/audit-requests/")
  .set("Authorization", `Bearer ${accessToken}`)
  .send({
   { auditRequests:
      [ { bank: 'dnb',
          cutOffDate: '2019-12-31' },
        { bank: 'danske bank',
          cutOffDate: '2019-12-31',
          language: 'en' },
        { bank: 'nordea',
          cutOffDate: '2019-12-31',
          daughterCompanies: [12345678912, 98765432198] }],
     client: 'arthur@dent-intustries.org',
     language: 'nb',
     user: 'zaphod@beeblebrox-audit.org',
     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 Name of the bank the audit request pertains to (see list of names below)
cutOffDate Date true ISO8601 date string representing the end of the fiscal year for the associated audit client
daughterCompanies List<Integer> List of VAT numbers for any associated daughter companies for the audit client
language Language Language for the audit request (valid values: nb, en). Defaults to nb (also controls the language for the confirmation process)
reminder Boolean 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

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.

Bank names

The following bank names are accepted by the API (name matching is case insensitive):

Aasen Sparebank, Andebu Sparebank, Arendal og Omegn Sparekasse, Askim og Spydeberg Sparebank, Aurland Sparebank, Aurskog Sparebank, BN Bank, BNP Paribas, Bank2, Berg Sparebank, Bien Sparebank, Birkenes Sparebank, Bjugn Sparebank, Blaker Sparebank, Cultura Bank, DNB, Danske Bank, DinBank, Drangedal og Tørdal Sparebank, Easybank, Eidsberg Sparebank, Eika Boligkreditt, Eika Gruppen, Eksportfinans, Eksportkreditt Norge, Etne Sparebank, Etnedal Sparebank, Evje og Hornnes Sparebank, Fana Sparebank, Flekkefjord Sparebank, Fornebubanken, Gildeskål Sparebank, Gjensidige Bank, Grong Sparebank, Grue Sparebank, Haltdalen Sparebank, Handelsbanken, Handelsbanken Arendal, Handelsbanken Asker, Handelsbanken Bergen Sentrum, Handelsbanken Bergen Vest, Handelsbanken Bodø, Handelsbanken Bryn, Handelsbanken Drammen, Handelsbanken Fana Bergen, Handelsbanken Fredrikstad, Handelsbanken Fyllingsdalen Bergen, Handelsbanken Grev Wedels Plass, Handelsbanken Halden, Handelsbanken Hamar, Handelsbanken Haugesund, Handelsbanken Heimdal, Handelsbanken Jessheim, Handelsbanken Jæren, Handelsbanken Kokstad Bergen, Handelsbanken Kolbotn, Handelsbanken Kongsberg, Handelsbanken Kristiansand, Handelsbanken Larvik, Handelsbanken Leangen, Handelsbanken Lillehammer, Handelsbanken Lillestrøm, Handelsbanken Lysaker, Handelsbanken Majorstuen, Handelsbanken Minde, Handelsbanken Mo i Rana, Handelsbanken Molde, Handelsbanken Moss, Handelsbanken Nydalen, Handelsbanken Olav Vs Gate, Handelsbanken Sandefjord, Handelsbanken Sandnes, Handelsbanken Sandvika, Handelsbanken Sarpsborg, Handelsbanken Ski, Handelsbanken Skien, Handelsbanken Skøyen, Handelsbanken Stavanger Sentrum, Handelsbanken Stavanger Straen, Handelsbanken Tromsø, Handelsbanken Trondheim, Handelsbanken Tønsberg, Handelsbanken Ålesund, Handelsbanken Åsane Bergen, Handelsbanken Økern, Harstad Sparebank, Haugesund Sparebank, Hegra Sparebank, Helgeland Sparebank, Hemne Sparebank, Hjartdal og Gransherad Sparebank, Hjelmeland Sparebank, Husbanken, Høland og Setskog Sparebank, Hønefoss Sparebank, Indre Sogn Sparebank, Innovasjon Norge, Jæren Sparebank, KLP, Klæbu Sparebank, Kommunalbanken Norge, Kvinesdal Sparebank, Landkreditt Bank, Larvikbanken Brunlanes Sparebank, Lillesand Sparebank, LillestrømBanken, Lofoten Sparebank, Luster Sparebank, Marker Sparebank, MelhusBanken, NORDirektebank, Nidaros Sparebank, Nordea, Norges Bank, Næringsbanken, OBOS-banken, Odal Sparebank, Ofoten Sparebank, Oppdalsbanken, Orkla Sparebank, Pareto bank, Resurs Bank, Rindal Sparebank, Romsdalsbanken, RørosBanken, SEB, SG Finans, Sandnes Sparebank, Santander Consumer Bank, Sbanken, Selbu Sparebank, Skagerak Sparebank, Skudenes og Aakra Sparebank, Skue Sparebank, Sogn Sparebank, Soknedal Sparebank, SpareBank 1 Buskerud-Vestfold, SpareBank 1 Factoring, SpareBank 1 Gudbrandsdal, SpareBank 1 Hallingdal Valdres, SpareBank 1 Lom og Skjåk, SpareBank 1 Modum, SpareBank 1 Nord-Norge, SpareBank 1 Nordvest, SpareBank 1 Ringerike Hadeland, SpareBank 1 SMN, SpareBank 1 Søre Sunnmøre, SpareBank 1 Telemark, SpareBank 1 Østfold Akershus, SpareBank 1 Østlandet, Sparebank 68 Nord, Sparebanken DIN, Sparebanken Møre, Sparebanken Narvik, Sparebanken Sogn og Fjordane, Sparebanken Sør, Sparebanken Vest, Sparebanken Øst, Spareskillingsbanken, Sparesmart.no, Stadsbygd Sparebank, Storebrand Bank, Strømmen Sparebank, Sunndal Sparebank, Surnadal Sparebank, Swedbank, Søgne og Greipstad Sparebank, Tinn Sparebank, Tolga-Os Sparebank, Totens Sparebank, Trøgstad Sparebank, Tysnes Sparebank, Valdres Sparebank, Valle Sparebank, Vekselbanken, Vik Sparebank, Voss Sparebank, Åfjord Sparebank, Ørland Sparebank, Ørskog Sparebank, Østre Agder Sparebank

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).

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

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

Response

Attribute Type Description
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"
}

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 \
  --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");

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.

Get all Sign Requests for audit client

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

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/null 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": "arthur-dent@company.com",
      "signed": false,
      "signedAt": null,
      "signedName": null
    },
    {
      "email": "ford-prefect@company.com",
      "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/null When was the sign request signed by this signee? (if at all)
signedName String/null Name retrieved from BankID upon completing the signature process

Signee

// Not yet signed
{
  "email": "ford-prefect@company.com",
  "signed": false,
  "signedAt": null,
  "signedName": null
}
// Signed
{
  "email": "ford-prefect@company.com",
  "signed": true,
  "signedAt": "2019-10-14 13:06:15",
  "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

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

Response

Attribute Type Description
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.

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"
}