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)
- Brevio Signature-right
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¶m=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
- Mark audit requests as finalized: If an auditor has received a confirmation outside Brevio the audit request can be finalized without user input
- Download attachments: Download attachments 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/
POST /v1/confirm/audit-requests/finalize
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-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:
- Create new sign requests: Programatically new sign requests without the need for human interaction through the web service.
- Retrieve data for sign requests: Access all sign requests associated with your audit company, conditionally filtered by document templates or update dates.
- Download signed documents: Download all digitally signed uploaded PDFs associated with a sign request.
Endpoints
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:
- Retrieve Signature Right information: Get information regarding a person's signature right for a given company.
Endpoints
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/
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 |
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
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 |
---|---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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:
- Norway: Retrieves signature right (or prokura) individually or in combination. Source: BRREG
- Sweden: Retrieves signature right (or administrative sign) individually or in combination. Source: Bolagsverket
- Denmark: Retrieves signature right individually. Source: Virk
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.
- ALONE means the signer has signing right as a sole signer on behalf of the company.
- GROUP means the signer has signing right in combination with others on behalf of the company.
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"
}