Securibox ParseXtract:API

ReDoc documentation

Securibox Cloud Agents REST API (1.7)

Download OpenAPI specification:Download

API Support: support@securibox.eu License: SCA Document API

Introduction

The SCA API is built on HTTP. Our API is RESTful. It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can use your favorite HTTP/REST library for your programming language to use Cloud Agents's API, or you can use one of our SDKs

Authentication

In order to secure the Securibox Cloud Agents API, three mechanisms have been implemented. Here is a brief overview of the three mechanisms as well as code snippets to help you integrate the correct mechanism in order to call the APIs.

Basic API Authentication w/ TLS

Basic API authentication is the easiest of the three to implement offering the lowest security options of the common protocols. This mechanism is usually advised for testing purposes in order to test the APIs and only requires Securibox to provide a username and password as a Base64-encoded header or as parameters in an HTTP client.

When you pass your credentials in the header, you must Base64-encode them. The following is an example of an encoded HTTP Basic Authentication header:

Authorization: Basic YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo

SSL Client Certificate Authentication

The SSL client certification is a mechanism allowing your application to authenticate itself with the Securibox Cloud Agents (SCA) servers. In this case, your application will send its SSL certificate after verifing the SCA server identity. Then, the client and server use both certificates to generate a unique key used to sign requests sent between them. This kind of authentication is implemented when the customer call your servers that will then call the Securibox Cloud Agents API. In order to use this type of authentication, Securibox will provide a PEM certificate file containing a passphrase protected private key and a public key.

JSON Web Token Authentication (JWT)

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a public/private key pair using RS256 (RSA PKCS#1 signature with SHA-256). This kind of authentication is implemented when the customer calls directly the Securibox Cloud Agents API together with cross-origin resource sharing (CORS). In order to use this type of authentication, Securibox will provide a passphrase protected RSA private key in PEM file (.pem).

SDKs

These libraries allow quick integration between SendGrid and your project, and are available for a variety of languages and frameworks.
Securibox maintains the following official libraries:

Accounts

Create and manage cloud agent's accounts.

List all accounts

This endpoint allows you to retreive all accounts.

You can filter the list with the query parameters to be able to list the accounts belonging to a specific user or/and agent.

query Parameters
agentId
string
Example: "30fca371-e3a0-4e14-84a8-26e49b1bd68e"

The identifier of the agents to be able to filter by agent.

customerUserId
string
Example: "Account_123"

The customer user identifier to be able to filter accounts by user.

skip
integer <int32>
Default: 0

The number of accounts to skip.

take
integer <int32> [ 0 .. 50 ]
Default: 50

The maximum number of accounts to be returned.

Responses

200

A list of accounts.

400

take, skip or agent id parameters are invalid

404

The agent associated to the account could not be found

get /accounts

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    }
]

Create an account

This endpoint allows you to create an account for a specific agent and user.

You can also specify if you want to synchronize the account immediatly after the creation.
If no customerAccountId is provided, the platform will generate a random identifier for the create account.

Request Body schema: application/json

The API account creation request.

synchronize
required
boolean

Indicates whether the account has to be immediately synchronized.

account
required
object (Account)

Defines how is an object model of account.\n An account is a set of access credentials used by an agent to get documents or other data from Internet. An account is associated an agent by its agentId. Each account is identified by an unique customerAccountId. The identification of accounts created by the same user is according to its customerUserId. The list of all attributes are described in the table below.

Responses

200

The account has been successfully created.

400

Invalid request body

403

Agent related errors

409

Account already exists

post /accounts

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts

Request samples

application/json
Copy
Expand all Collapse all
{
  • "account":
    {
    },
  • "synchronize": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "agentId": "4a428680-050d-4609-811e-ebbd2d15eef0",
  • "customerAccountId": "Account_123",
  • "credentials":
    [
    ],
  • "name": "Jamie's account",
  • "customerUserId": "User1",
  • "mode": "Enabled",
  • "additionalAuthenticationData": null
}

Search accounts

This endpoint allows you to search accounts by customer user identifier and/or by agent identifier.

query Parameters
customerUserId
string
Example: "Account_123"

The customer user identifier.

agentId
string
Example: "30fca371-e3a0-4e14-84a8-26e49b1bd68e"

The agent identifier.

skip
integer <int32>
Default: 0

The number of accounts to skip.

take
integer <int32> [ 0 .. 50 ]
Default: 50

The maximum number of accounts to be returned.

Responses

200

A list of accounts.

400

One or more parameters are missing or invalid.

404

The requested agent was not found.

get /accounts/search

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/search

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/search

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get a specific account

This endpoint allows you to get an account by customerAccountId.

path Parameters
customerAccountId
required
string
Example: "Account_234"

The customer account identifier.

Responses

200

The selected account.

404

The requested account was not found.

get /accounts/{customerAccountId}

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "application/json":
    {
    }
}

Update an account

This endpoint allows you to updates an account by specifying its customerAccountId. You can update the following fields:

  • Name
  • Mode
  • Credentials

In order to modify the other fields, you should delete this account and create a new one.

path Parameters
customerAccountId
required
string
Example: "Account_123"

The customer account identifier.

Request Body schema: application/json

The API account.

customerAccountId
string <= 128 characters

The customer account identifier.

customerUserId
string <= 128 characters

The customer user identifier.

name
string <= 64 characters

The account name.

agentId
required
string <guid>

The agent identifier.

mode
string
Default: "Disabled"
Enum:"Enabled" "Disabled" "NoAutomaticSynch"

The account mode

credentials
required
Array of objects (Credential)

The list of credentials associated to this account.

additionalAuthenticationData
object (AdditionalAuthData)

Responses

200

The updated account.

400

Request parameters or body errors

403

Account still synchronizing

404

Account not found

put /accounts/{customerAccountId}

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "customerAccountId": "Account_123",
  • "customerUserId": "User1",
  • "name": "Jamie's Account",
  • "agentId": "4a428680-050d-4609-811e-ebbd2d15eef0",
  • "mode": "Enabled",
  • "credentials":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "agentId": "4a428680-050d-4609-811e-ebbd2d15eef0",
  • "customerAccountId": "Account_123",
  • "credentials":
    [
    ],
  • "name": "Jamie's account",
  • "customerUserId": "User1",
  • "mode": "Enabled",
  • "additionalAuthenticationData": null
}

Delete an account

This endpoint allows you to delete an account by customerAccountId.

path Parameters
customerAccountId
required
string
Example: "Account_123"

The customer account identifier.

Responses

200

The account has been successfully deleted.

400

Invalid customer account id parameter

delete /accounts/{customerAccountId}

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "InvalidCustomerAccountIdParameter":
    {
    }
}

Get documents per account

This endpoint allows you to list all documents downloaded by the account specified by the customerAccountId.

You can specify if you want to list only those that haven't been acknowledged through the parameter pendingOnly and if you want to retreive the content of the document through the parameter includeContent.

path Parameters
customerAccountId
required
string

The customer account identifier.

query Parameters
pendingOnly
boolean
Default: false

It set to true returns only pending documents.

includeContent
boolean
Default: false

Is set to true includes the content fo the document in the response.

Responses

200

A list of documents.

400

Parameters are missing

404

Account not found

get /accounts/{customerAccountId}/documents

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}/documents

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}/documents

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

List synchronization per account

This endpoint allows you to list all synchronizations performed by the account specified through the customerAccountId parameter.

You can optionally filter the list of synchronzations using the startDate and endDate query parameters.

path Parameters
customerAccountId
required
string
Example: "Account_123"

The customer account identifier.

query Parameters
startDate
string <date>
Example: "2019-04-01"

The start date.

endDate
string <date>
Example: "2019-04-01"

The end date.

Responses

200

A list of synchronizations.

400

Parameters are missing

404

Account not found

get /accounts/{customerAccountId}/synchronizations

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}/synchronizations

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}/synchronizations

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    }
]

Synchronize an account

This endpoint allows you to launch a synchronization for the account specified throught the customerAccountId parameter.

You can specify if you want to force the synchronization (i.e. download all available documents regardless if they have already been downloaded by previous synchronizations) usign the isForced property in the request body.

path Parameters
customerAccountId
required
string
Example: "Account_123"

The customer account identifier.

Request Body schema: application/json

Specifies if the synchronization shoud download all available documents.

customerAccountId
required
string <= 128 characters

The customer account identifier.

customerUserId
string

The customer user identifier.

isForced
boolean
Default: false

A value indicating whether this request is forced.

Responses

200

Launches the synchronization for the specified account.

400

Request parameters or body errors

403

Account still synchronizing

404

Account not found

post /accounts/{customerAccountId}/synchronizations

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}/synchronizations

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}/synchronizations

Request samples

application/json
Copy
Expand all Collapse all
{
  • "customerAccountId": "Account_123",
  • "customerUserId": "User1",
  • "isForced": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accountId": 158672,
  • "customerAccountId": "Account_234",
  • "customerUserId": "User1",
  • "isForced": false,
  • "downloadedDocs": 4,
  • "detectedDocs": 4,
  • "creationDate": "2019-05-24T00:57:47.7965540Z",
  • "startDate": "2019-05-24T00:58:10.2791053Z",
  • "endDate": "2019-05-24T00:58:13.4001703Z",
  • "deliveryDate": "2019-05-24T00:58:13.7642680Z",
  • "acknowledgementDate": "2019-05-24T01:10:42.1101909Z",
  • "synchronizationState": "Completed",
  • "synchronizationStateDetails": "Completed",
  • "synchronizationMode": "Client",
  • "apiVersion": "V1",
  • "documents":
    [
    ],
  • "agentId": 12,
  • "agentIdentifier": "f9e5d1469861430692dbc53cb1a85bea"
}

Get last synchronization per account

This endpoint allows you to retrieve the last synchronization for the account specified through the customerAccountId parameter.

It is specially usefull to poll the synchronization in order to display the evolution of the synchronization status for the specified account.

path Parameters
customerAccountId
required
string
Example: "Account_123"

The customer account identifier.

Responses

200

The last synchronization for the specified account.

400

Parameters are missing

404

Account not found

get /accounts/{customerAccountId}/synchronizations/last

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}/synchronizations/last

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}/synchronizations/last

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accountId": 158672,
  • "customerAccountId": "Account_123",
  • "customerUserId": "User1",
  • "isForced": false,
  • "downloadedDocs": 1,
  • "detectedDocs": 1,
  • "creationDate": "2019-05-18T16:44:25.4723465Z",
  • "startDate": "2019-05-18T16:56:25.4723465Z",
  • "endDate": "2019-05-18T16:56:55.9974978Z",
  • "deliveryDate": "2019-05-18T16:56:56.7573047Z",
  • "acknowledgementDate": "2019-05-18T16:59:56.2279031Z",
  • "synchronizationState": 6,
  • "synchronizationStateDetails": 1,
  • "synchronizationMode": 2,
  • "apiVersion"": "V1",
  • "documents": [ ]
}

Get multifactor authentication data

This endpoint allows you to know on which channel has the secret code been sent to the user when a synchronizationStateDetails reaches the AdditionalAuthenticationRequired status.

path Parameters
customerAccountId
required
string
Example: "Account_123"

The customer account identifier.

Responses

200

A list of synchronizations.

400

Parameters are missing

404

Account not found

get /accounts/{customerAccountId}/mfa

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}/mfa

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}/mfa

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accountId": 123,
  • "additionalAuthenticationType": "Mobile",
  • "expirationDate": "2019-05-18T16:56:51.7815169Z",
  • "message": "string"
}

Send secret code for multifactor authentication

This endpoint allows you to send the secret code that has been communicated to the user in case of a multifactor authentication.

path Parameters
customerAccountId
required
string
Example: "Account_123"

The customer account identifier.

Request Body schema: application/json

Sends the multifactor authentication secret code to be used to carry on with the synchronization.

customerAccountId
string <= 128 characters

The customer account identifier.

sbxSecretCode
string <= 128 characters

The customer account identifier.

Responses

200

The synchronization to continue.

400

Request parameters or body errors

403

Synchronization still running

404

Account not found

post /accounts/{customerAccountId}/mfa

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/accounts/{customerAccountId}/mfa

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/accounts/{customerAccountId}/mfa

Request samples

application/json
Copy
Expand all Collapse all
{
  • "customerAccountId": "Account_123",
  • "sbxSecretCode": 1234
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accountId": 158672,
  • "customerAccountId": "Account_234",
  • "customerUserId": "User1",
  • "isForced": false,
  • "downloadedDocs": 4,
  • "detectedDocs": 4,
  • "creationDate": "2019-05-24T00:57:47.7965540Z",
  • "startDate": "2019-05-24T00:58:10.2791053Z",
  • "endDate": "2019-05-24T00:58:13.4001703Z",
  • "deliveryDate": "2019-05-24T00:58:13.7642680Z",
  • "acknowledgementDate": "2019-05-24T01:10:42.1101909Z",
  • "synchronizationState": "Completed",
  • "synchronizationStateDetails": "Completed",
  • "synchronizationMode": "Client",
  • "apiVersion": "V1",
  • "documents":
    [
    ],
  • "agentId": 12,
  • "agentIdentifier": "f9e5d1469861430692dbc53cb1a85bea"
}

Agents

List and filter available agents.

List all agents

This endpoint allows you to list all agents.

Optionally, through the query parameters, you can specify if you want to include the agents logos or only list the agents from a specific culture.

query Parameters
culture
string
Example: "fr-fr"

The culture of the returned information.

includeLogo
boolean
Default: false
Example: true

Specifies if the response should include the agents logo in base64 enconding.

Responses

200

A list of agents.

400

Parameters are missing or invalid

get /agents

Optional server description, e.g. Main (production) server

https://sca-multitenant-prod.securibox.eu/api/v1/agents

Optional server description, e.g. Internal staging server for testing

https://sca-multitenant.securibox.eu/api/v1/agents

Response samples

application/json
Copy
Expand all Collapse all
[
  • {