Introduction

Brevio API

Welcome to the developer documentation for Brevio's APIs.

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

• Brevio Confirm (available for banks and audit companies)
• Brevio Sign (available for audit companies)

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:

• https://api-dev.brevio.com (staging)
• https://api.brevio.com (production)

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:

• Retrieve data for audit requests: Access all audit requests associated with your entity
• Download signed PDFs: Download signed PDFs for audit requests associated with your entity
• Create new audit requests: Create new audit requests in batches to the same client
• Reply to audit requests: Upload confirmations for your entity's received audit requests

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:

• Retrieve data for sign requests: Programmatically access all sign requests (requests for digital signatures) associated with your entity

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

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

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

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.

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

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

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

Audit Request

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

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

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.

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:

Response

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

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

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

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

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

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

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

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

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.

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

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

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

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

RequestTemplate

I18n

Errors

The Brevio APIs use the following error codes:

Error response

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