Introduction

The Brevio API is organized around REST.

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)
Signature rights (available for banks)

Once you have registered a new API user, you'll have access to our staging environment after a validation of your associated bank or audit company.

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:

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

All parameters are noted as such.

Dates and DateTimes

All responses from our APIs are native values (e.g. integers, strings, and arrays of native values). Response attributes defined as Date or DateTime are ISO8601 compliant string representations for these values. e.g. 2022-01-01 and 2022-01-01T00:00:00Z respectively.

$ curl "https://api.brevio.com/v1/some-endpoint"
  -H "Content-Type: application/json"
  -d '{ "param": "value", "param2": "value2" }'

Query string

$ curl "https://api.brevio.com/v1/some-endpoint?param=value&param=value2"
  -H "Content-Type: application/json"

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.

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 2023-10-04. To see all API updates, view the changelog.

All requests use your account API settings, unless you override the API version. To set the API version for a specific request, send a Brevio-Version header.

Unless otherwise noted, all documentation examples use the latest API version. If your payload differs from the documentation, you have a different API version in your account API settings.

After using the Brevio-Version header to test your integration against the latest API version, please contact us to upgrade your account API settings.

Specifying version header

$ curl "https://api.brevio.com/v1/some-endpoint"
  -H "Content-Type: application/json"
  -H "Brevio-Version: 2023-10-04"
  -d '{ "param": "value", "param2": "value2" }'

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.

Scopes

Name	Note
`audit_company`	Can access both Brevio Confirm and Brevio Sign.
`bank`	Can only access Brevio Confirm.
`signature_right`	Grants access to the Signature Rights API.
`signee_pid`	Grants access to view the personal ID (PID) of a signee.
`vendor`	Grants access to create sign requests on behalf of a costumer.

All scopes are validated by when creating an API client.

The signature_right, signee_pid, and vendor scopes require specific access. Please contact us for more information.

Access tokens

We use bearer tokens to verify access to all Brevio API endpoints. Access tokens are generated by passing a base64 encoded valid client_id and client_secret combination to the access token creation endpoint.

Create access token

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.

Parameters

Name	Type	Description
grant_type	String	Must be `client_credentials`
scope	Scope	`audit_company`, `bank`, `signature_right`, `signee_pid`, `vendor`

Remember to replace client_id and client_secret with the generated keys after you register your API user, and to separate them with a colon character (:) before encoding, as per the HTTP spec.

Returns

Returns a valid access token for the given scope(s). The access token will indicate which API version the token is valid for.

POST /auth/token

$ curl "https://api.brevio.com/auth/token"
  -H "Authorization: Basic ${base64_encoded_client_id_and_secret}"
  -d '{ "grant_type": "client_credentials", "scope": "bank" }'

Response

{
  "access_token": "tLUowHOUa2dmanlU_pr9WazuI_ubjRNoXMBeg_jzCo0",
  "token_type": "Bearer",
  "expires_in": 1209600,
  "scope": "audit_company signature_right",
  "created_at": 1665131755,
  "api_version": "2023-10-04"
}

Brevio Confirm API

The Confirm API grants your authorized API client access to data associated with its entity (e.g. bank or audit company) in the Brevio Confirm service.

Confirm API core resources

Below are listed all the core resources for the Brevio Confirm API.

Audit request

This object represents a single request for a confirmation from a third party for a particular audit client. A third party can be either a bank, lawyer, supplier, or client.

Each audit request pertains to exactly one audit client (company), and any number of subsidiaries (subsidiaries).

Attribute	Type	Description
token	String	Unique identifier
acccountNumbers	List<AccountNumber>	List of account numbers associated with the audit request.
attachments	List<String>	List of tokens used to uniquely identify an attachment associated with the audit request (includes the digitally signed pdf after the audit request has been signed by all signees).
auditCompany	String	Name of the audit company to which the associated auditor of the audit request belongs
bank	Bank	The bank associated with this audit request.
company	Company	The main audit client.
confirmation	Confirmation	Confirmation for the audit request. This field is `null` if the audit request has not been confirmed.
cutOffDate	Date	The end of the fiscal year for the associated audit client.
invoiceReference	String	ID used for internal reference at the audit company. This field is `null` if the audit company does not have this setting enabled.
language	String	The language used for the audit request. Adheres to the ISO 639-1 standard. Valid values: `da`, `en`, `nb`, `sv`.
lastUpdate	DateTime	When was the audit request last updated?
lastingPowerOfAttorney	LastingPowerOfAttorney	Lasting power of attorney (LPA) associated with this request. This field is `null` if the audit request has no associated LPA, or if the request is not a `bank` request.
requestType	String	Valid valies: `bank`, `client`, `lawyer`, `supplier`.
sentToClientAt	Date	Date the audit request was first sent its signees.
signees	List<Signee>	List of signees associated with the audit request.
step	String	Valid values: `started`, `client`, `needs-validation`, `third-party`, `received`, `cancelled`, `archived`, `post`.
subsidiaries	List<Company>	List of subsidiaries associated with the audit request.
subType	String	Valid values: `completeness`, `existence`. This field is `null` unless the audit request has the `client` or `supplier` request type.
thirdParty	String	Name of the audit request's associated third party.
user	User	The auditor associated with the audit request.

Audit request

{
  "token": "3ffad0ece7ba919e08a7a39b38666bb7fa4c121fae27551eb2877c7c0b96a127",
  "accountNumbers": [
    {
      "accountNumber": "1232.20.12313",
      "company": {
        "country": "no",
        "name": "ACME AS",
        "vatNo": "999999999"
      }
    }
  ],
  "attachments": [],
  "auditCompany": "Brevio AS",
  "bank": {
    "token": "042172ae-9e59-4b8e-910f-3f707a727659",
    "country": "no",
    "disabled": false,
    "hasLPA": true,
    "lpaType": "specific",
    "name": "DNB"
  },
  "company": {
    "name": "ACME AS",
    "vatNo": "999999999",
    "country": "no"
  },
  "confirmation": {
    "attachments": [
      "3ffad0ece7ba919e08a7a39b38666bb7fa4c121fae27551eb2877c7c0b96a127",
      "a4c60323af9e76bb9877a75631dd6a51d62db93929a223ac4d91eacabf2bda1a"
    ],
    "sentAt": "2023-01-01"
  },
  "cutOffDate": "2022-12-31",
  "language": "nb",
  "lastUpdate": "2022-10-02T11:53:23Z",
  "lastingPowerOfAttorney": null,
  "manualReview": false, // bank only
  "requestType": "bank",
  "sentToClientAt": "2022-10-01",
  "signatureReviews": [
    // bank only
    {
      "reviewedBy": "Bob Odenkirk",
      "verified": true,
      "reviewedAt": "2022-10-03T11:00:23Z",
      "company": {
        "name": "ACME AS",
        "vatNo": "999999999",
        "country": "no"
      }
    }
  ],
  "signees": [
    {
      "email": "[email protected]",
      "name": "Arthur Dent",
      "pid": null,
      "signed": true
    },
    {
      "email": "[email protected]",
      "name": "Guybrush Threepwood",
      "pid": null,
      "signed": true
    }
  ],
  "startedProcessing": true, // bank only
  "step": "received",
  "subsidiaries": [
    {
      "name": "ACME Doorknobs Oy",
      "vatNo": "99999988",
      "country": "fi"
    }
  ],
  "subType": null,
  "thirdParty": "DNB",
  "user": {
    "email": "[email protected]",
    "officeAddress": "Gatevei 1313, 0561 Oslo"
  }
}

Bank-only attributes

Attribute	Type	Description
manualReview	Boolean	An audit request requires manual review in cases where the auditor has made changes to the standard template.
signatureReviews	List<SignatureReview>	List of signature reviews for the audit request. Only available if the bank has enabled signature reviews.
startedProcessing	Boolean	A flag set by the bank, indicating they've started processing the audit request. Only available if the bank has enabled processing flags.

Bank

This object represents a bank. You can retrieve it to view information about the bank when creating new audit requests or lasting powers of attorney.

Attribute	Type	Description
token	String	Unique identifier
country	String	Two character country code, as defined by ISO 3166-1 alpha-2. Valid values: `dk`, `fi`, `no`,`se`.
disabled	Boolean	Disabled banks cannot receive new audit requests, but they can have existing requests sent before they were disabled.
hasLPA	Boolean	Does this bank support lasting powers of attorney (LPAs)?
lpaType	String	Valid values: `none`, `specific`, `generic`.
name	String	The name of the bank. Not guaranteed to be unique.

Bank

{
  "token": "042172ae-9e59-4b8e-910f-3f707a727659",
  "country": "no",
  "disabled": false,
  "hasLPA": true,
  "lpaType": "specific",
  "name": "DNB"
}

Confirmation

This object represents a confirmation for an audit request.

Attribute	Type	Description
attachments	List<String>	List of tokens used to uniquely identify an attachment associated with the confirmation.
sentAt	DateTime	Timestamp of when the third party sent the confirmation.

Confirmation

{
  "attachments": [
    "9e9f430c1d8e8716ae71d6311fb76e4534fd4959e8b2299d505afcfafd32c60d",
    "b82c013b8e3f9ae73352500d322a39538b269938bc9737e5f2a4d9df240d3e38"
  ],
  "sentAt": "2023-01-01T08:03:01Z"
}

Lasting power of attorney

This object represents a lasting power of attorney (LPA) - powers of attorney which remain valid for several audit seasons. Audit requests can use LPAs on behalf of audit clients for consecutive seasons until they are revoked.

LPAs must first be signed before they become active. When an audit request uses a signed LPA, the requests are sent directly to their respective third parties.

LPAs come in two distinct flavours:

Generic: generic LPAs are only associated with a company (and optional subsidiaries), and can be used with any bank which supports generic LPAs.
Specific: specific LPAs are associated with a specific bank, and can only be used for that particular bank.

Attribute	Type	Description
token	String	Unique identifier.
attachment	String	Unique identifier for the signed power of attorney (PDF). `null` if the LPA is not signed.
bank	Bank	The bank associated with this LPA. This field is `null` if the LPA type is `generic`.
company	Company	The main company assocaited with this LPA.
fromDate	Date	The date which this LPA was activated. This field is `null` if the LPA is not signed.
language	String	The language used for the LPA. Adheres to the ISO 639-1 standard. Valid values: `da`, `en`, `nb`, `sv`.
lpaType	String	Valid values: `generic`, `specific`.
signed	Boolean	Has this LPA been signed?
signees	List<Signee>	List of signees associated with the LPA.
subsidiaries	List<Company>	List of subsidiaries associated with the LPA.

Lasting power of attorney

{
  "token": "b06178d5-8240-4150-ac57-cc2bc762c7b0",
  "attachment": null,
  "bank": {
    "token": "042172ae-9e59-4b8e-910f-3f707a727659",
    "country": "no",
    "disabled": false,
    "hasLPA": true,
    "lpaType": "specific",
    "name": "DNB"
  },
  "company": {
    "country": "no",
    "name": "ACME AS",
    "vatNo": "999999998"
  },
  "fromDate": null,
  "language": "en",
  "lpaType": "specific",
  "signed": false,
  "signees": [
    {
      "name": null,
      "signed": false,
      "email": "[email protected]"
    },
    {
      "name": null,
      "signed": false,
      "email": "[email protected]"
    }
  ],
  "subsidiaries": [
    {
      "name": "ACME Doors AS",
      "vatNo": "999999998",
      "country": "no"
    },
    {
      "name": "ACME Doorknobs AS",
      "vatNo": "999999997",
      "country": "no"
    }
  ]
}

Manual audit request

This object represents an audit request which is initiated outside of Brevio. Auditors without a Brevio account can create manual audit request through a web interface provided by banks.

The bank can then confirm received manual audit requests in a predictable manner.

When manual audit requests are confirmed by their respective banks, the external auditor receives an email with a link to a downloadable, password-protected ZIP file containing the confirmation. The password for the ZIP file is sent to the auditor by SMS.

Attribute	Type	Description
token	String	Unique identifier.
acccountNumbers	List<AccountNumber>	List of account numbers associated with the audit request.
attachments	List<String>	List of tokens used to uniquely identify an attachment associated with the audit request.
audtor	ManualUser	The auditor associated with the audit request.
bankStartedProcessing	Boolean	A flag set by the bank, indicating they've started processing the audit request. Only available if the bank has enabled processing flags.
company	Company	The main audit client.
completedAt	DateTime	When was the audit request completed?
cutOffDate	Date	The end of the fiscal year for the associated audit client.
language	String	The language used for the audit request. Adheres to the ISO 639-1 standard. Valid values: `da`, `en`, `nb`, `sv`.
sentToPaymentAt	DateTime	When was the audit request sent to payment?
sentToThirdPartyAt	DateTime	When was the audit request sent to the bank?
signatureReview	SignatureReview	Signature review for the audit request. Only available if the bank has enabled signature reviews.
step	String	Valid values: `started`, `awaiting_payment`, `sent_to_third_party`, `completed`.

Manual audit request

{
  "token": "5a697491-4eb1-47df-b01b-057075a4e1f8",
  "accountNumbers": [
    {
      "accountNumber": "1232.20.12313",
      "company": {
        "country": "no",
        "name": "ACME AS",
        "vatNo": "999999999"
      }
    }
  ],
  "attachments": [
    "228ed0e06e78413fdba88cea02cdce69eb339946b13af5dbb8172a7c92af76d7"
  ],
  "auditor": {
    "company": "Dent Audit Oy",
    "country": "fi",
    "email": "[email protected]",
    "firstName": "Arthur",
    "lastName": "Dent",
    "phone": "+358501234567"
  },
  "bankStartedProcessing": false,
  "company": {
    "country": "no",
    "name": "ACME AS",
    "vatNo": "999999999"
  },
  "completedAt": null,
  "cutOffDate": "2023-12-31",
  "language": "en",
  "sentToPaymentAt": null,
  "sentToThirdPartyAt": null,
  "signatureReview": null,
  "step": "started"
}

Other resources

Account number

This object represents a filled-in (by either the audit client or the auditor) account number which the associated bank uses to charge its fee for producing a confirmation.

Attribute	Type	Description
accountNumber	String	A single, verified bank account number for a particular company in a particular bank.
company	Company	The company associated with this account number.

Account number

{
  "accountNumber": "1232.20.12313",
  "company": {
    "country": "no",
    "name": "ACME AS",
    "vatNo": "999999999"
  }
}

Company

Attribute	Type	Description
country	String	Two character country code, as defined by ISO 3166-1 alpha-2. Valid values: `dk`, `fi`, `no`,`se`.
name	String	The company name as registered in the national registry for the company's country of operation.
vatNo	Stri