BIN lookup API, the free api service from bintable.com to lookup card information using it's BIN. the service maintains updated database based on the comunity and other third party services to make sure all BINs in the database are accurate and up to date.
Code against the Bitbucket API to automate simple tasks, embed Bitbucket data into your own site, build mobile or desktop apps, or even add custom UI add-ons into Bitbucket itself using the Connect framework.
Get the latest business news articles.
Live API Documentation
Containers are virtual software objects that include all the elements that an app needs to run. A container has the benefits of resource isolation and allocation but is more portable and efficient than, for example, a virtual machine.
This documentation describes the IBM Containers API, which is based on the Docker Remote API. The API provides endpoints that you can use to create and manage your single containers and container groups in Bluemix. Endpoints are summarized under the following tags:
- **Authentication**: Retrieve and refresh your TLS certificates.
- **Private Docker images registry**: Create your own private Docker images registry in Bluemix by setting a namespace for your organization.
- **Images**: View, build, and push your images to your private Bluemix registry so you can use them with IBM Containers. You can also scan your container images with the Vulnerability Advisor against standard policies set by the organization manager and a database of known Ubuntu issues.
- **Single Containers**: Create and manage single containers in Bluemix. Use a single container to implement short-lived processes or to run simple tests as you develop an app or service. To make your single container available from the internet, review the `Public IP addresses` endpoints.
- **Container Groups**: Create and manage your container groups in Bluemix. A container group consists of multiple single containers that are all created from the same container image and as a consequence are configured in the same way. Container groups offer further options at no cost to make your app highly available. These options include in-built load balancing, auto-recovery of unhealthy container instances, and auto-scaling of container instances based on CPU and memory usage. Map a public route to your container group to make your app accessible from the internet.
- **Public IP addresses**: Use these endpoints to request public IP addresses for your space. You can bind this IP address to your container to make your container accessible from the internet.
- **File shares**: Create, list and delete file shares in a space. A file share is a NFS storage system that hosts Docker volumes.
- **Volumes**: Create and manage container volumes in your space to persist the data of your containers.
Each API request requires an HTTP header that includes the 'X-Auth-Token’ and 'X-Auth-Project-Id’ parameter.
- **X-Auth-Token**: The JSON web token (JWT) that you receive when logging into the Bluemix platform. It allows you to use the IBM Containers REST API, access services, and resources. Run `cf oauth-token` to retrieve your access token information.
- **X-Auth-Project-Id**: The unique ID of your organization space where you want to create or work with your containers. Run `cf space
Botify Saas API
[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.
Welcome to the official API of the brainbi platform. Using this API you can freely integrate our analytics platform with any other solution. Please refer to the following documentation and in case of any issues, please contact us at service@brainbi.net. Please note: for this API you will use your email and password from the brainbi.net platform to gather a Bearer Token for any API calls (use Login and get token). Once you are finished with your calls, please do a logout to remove your token and keep your account safe (use logout).
Allows sellers to: 1) Load products definitions to the BrandLovers marktplace. 2) Receive and update orders status. 3) Receive and update shipping information. 4) Receive and update customer tickets. All requests consume and return application/json content. All request must be authenticated and use HTTPS.
# Braze API Overview
Braze provides a high performance REST API to allow you to track users, send messages, export data, and more.
A REST API is a way to programmatically transfer information over the web using a predefined schema. Braze has created many different endpoints with specific requirements that will perform various actions and/or return various data. API access is done using HTTPS web requests to your company's REST API endpoint (this will correspond to your Dashboard URL as shown in the table below).
Customers using Braze's EU database should use `https://rest.fra-01.braze.eu/`. For more information on REST API endpoints for customers using Braze's EU database see our [EU/US Implementation Differences documentation](https://www.braze.com/docs/developer_guide/eu01_us3_sdk_implementation_differences/overview/).
## Braze Instances
Instance | Dashboard URL | REST Endpoint
----------- |---------------- | --------------------
US-01 | `https://dashboard.braze.com` or
`https://dashboard-01.braze.com` | `https://rest.iad-01.braze.com`
US-02 | `https://dashboard-02.braze.com` | `https://rest.iad-02.braze.com`
US-03 | `https://dashboard-03.braze.com` | `https://rest.iad-03.braze.com`
US-04 | `https://dashboard-04.braze.com` | `https://rest.iad-04.braze.com`
US-06 | `https://dashboard-06.braze.com` | `https://rest.iad-06.braze.com`
EU-01 | `https://dashboard.braze.eu` or
`https://dashboard-01.braze.eu` | `https://rest.fra-01.braze.eu`
# Using Braze's Postman Collection
If you have a Postman account (MacOS, Windows, and Linux versions can be downloaded from their website located [here](https://www.getpostman.com)), you can go to our Postman documentation and click the orange `Run in Postman` button in the top, right corner. This will allow you to [create an environment](#setting-up-your-postman-environment), as well as edit the available `POST` and `GET` requests to suit your own needs.
## Setting Up Your Postman Environment
The Braze Postman Collection uses a templating variable, `{{instance_url}}`, to substitute the REST API URL of your Braze instance into the pre-built requests. Rather than having to manually edit all requests in the Collection, you can set up this variable in your Postman environment. To do so, please follow the steps below:
1. Click on the gear icon in the top right corner of the Postman app.
2. Select "Manage Environments" to open a modal window which displays your active environments.
3. In the bottom right corner of the modal window, click "Add" to create a new environment.
4. Give this environment a name (e.g. "Braze API Requests") and add keys for `instance_url` and `api_key` with values corresponding to [your Braze instance](https://www.braze.com/docs/api/basics/#endpoints) and [Braze REST API Key](https://www.braze.com/docs/api/basics/#app-group-rest-api-keys), as pictured below.
As of April, 2020 Braze has changed how we read App Group API keys. Instead of passing them in the request body or through url parameters, we now read the App Group Rest`api_key` through the HTTP Authorization header. API keys not passed through the HTTP Authorization Header will coninue to work until they have been sunset.
## Using the Pre-Built Requests from the Collection
Once you have configured your environment. You can use any of the pre-built requests in the collection as a template for building new API requests. To start using one of the pre-built requests, simply click on it within the 'Collections' menu on the left side of Postman. This will open the request as a new tab in the main window of the Postman app.
In general, there are two types of requests that Braze's API endpoints accept - `GET` and `POST`. Depending on which `HTTP` method the endpoint uses, you'll need to edit the pre-built request differently.
### Edit a POST Request
When editing a `POST` request, you'll need to open the request and navigate to the `Body` section in the request editor. For readability, select the `raw` radio button to format the `JSON` request body.
### Edit a GET Request
When editing a `GET` request, you will need to edit the parameters passed in the request URL. To edit these easily, select the `Params` button next to the URL bar and edit the key-value pairs in the fields that will appear below the URL bar.
## Send Your Request
Once your API request is ready to send, click on the 'Send' button next to the URL bar. The request will be sent and the response data will be populated in a section underneath the request editor. From here, you can view the raw data returned from Braze's API, see the HTTP response code, see how long the request took to process, and view header information.
API Interface to retrieve company data and products from business registers
An Orchestration Layer that takes ISL services and packages them in a more targeted way for front-end applications. This in turn makes client integration easier and reduces the complexity and size of front-end applications. Rocket is also customisable - allowing UI engineers to ‘remix’ the existing back-end services into something that best suits the application they are developing.
Take screenshots of any website in real time
Social media management for marketers and agencies
## Overview The JSON REST API allows you to submit and receive [BulkSMS](https://www.bulksms.com/) messages. You can also get access to past messages and see your account profile. The base URL to use for this service is `https://api.bulksms.com/v1`. The base URL cannot be used on its own; you must append a path that identifies an operation and you may have to specify some path parameters as well. [Click here](/developer/) to go to the main BulkSMS developer site. In order to give you an idea on how the API can be used, some JSON snippets are provided below. Have a look at the [messages section](#tag/Message) for more information. Probably the most simple example ``` { "to": "+27001234567", "body": "Hello World!" } ``` You can send unicode automatically using the `auto-unicode` query parameter. Alternatively, you can specify `UNICODE` for the `encoding` property in the request body. Please note: when `auto-unicode` is specified and the value of the `encoding` property is `UNICODE`, the message will always be sent as `UNICODE`. Here is an example that sets the `encoding` explicitly ``` { "to": "+27001234567", "body": "Dobrá práce! Jak se máš?", "encoding": "UNICODE" } ``` You can also specify a from number ``` { "from": "+27007654321", "to": "+27001234567", "body": "Hello World!" } ``` Similar to above, but repliable ``` { "from": { "type": "REPLIABLE" }, "to": "+27001234567", "body": "Hello World!" } ``` A message to a group called Everyone ``` { "to": { "type": "GROUP", "name": "Everyone" }, "body": "Hello World!" } ``` A message to multiple recipients ``` { "to": ["+27001234567", "+27002345678", "+27003456789"], "body": "Happy Holidays!" } ``` Sending more than one message in the same request ``` [ { "to": "+27001234567", "body": "Hello World!" }, { "to": "+27002345678", "body": "Hello Universe!" } ] ``` **The insecure base URL `http://api.bulksms.com/v1` is deprecated** and may in future result in a `301` redirect response, or insecure requests may be rejected outright. Please use the secure (`https`) URI above. ### HTTP Content Type All API methods expect requests to supply a `Content-Type` header with the value `application/json`. All responses will have the `Content-Type` header set to `application/json`. ### JSON Formatting You are advised to format your JSON resources according to strict JSON format rules. While the API does attempt to parse strictly invalid JSON documents, doing so may lead to incorrect interpretation and unexpected results. Good JSON libraries will produce valid JSON suitable for submission, but if you are manually generating the JSON text, be careful to follow the JSON format. This include correct escaping of control characters and double quoting of property names. See the [JSON specification](https://tools.ietf.org/html/rfc4627) for further information. ### Date Formatting Dates are formatted according to ISO-8601, such as `1970-01-01T10:00:00+01:00` for 1st January 1970, 10AM UTC+1. See the [Wikipedia ISO 8601 reference](https://en.wikipedia.org/wiki/ISO_8601) for further information. Specifically, calendar dates are formatted with the 'extended' format `YYYY-MM-DD`. Basic format, week dates and ordinal dates are not supported. Times are also formatted in the 'extended' format `hh:mm:ss`. Hours, minutes and seconds are mandatory. Offset from UTC must be provided; this is to ensure that there is no misunderstanding regarding times provided to the API. The format we look for is `yyyy-MM-ddThh:mm:ss[Z|[+-]hh:mm]` Examples of valid date/times are`2011-12-31T12:00:00Z` `2011-12-31T12:00:00+02:00` ### Entity Format Modifications It is expected that over time some changes will be made to the request and response formats of various methods available in the API. Where possible, these will be implemented in a backwards compatible way. To make this possible you are required to ignore unknown properties. This enables the addition of information in response documents while maintaining compatibility with older clients. ### Optional Request Entity Properties There are many instances where requests can be made without having to specify every single property allowable in the request format. Any such optional properties are noted as such in the documentation and their default value is noted.
These endpoints constitute the functionality exposed by Bungie.net, both for more traditional website functionality and for connectivity to Bungie video games and their related functionality.
***UPDATE:*** *We have released a [beta version of the new bunq API documentation.](https://beta.doc.bunq.com)*
***NOTICE:*** *We have updated the sandbox base url to `https://public-api.sandbox.bunq.com/v1/`. Please update your applications accordingly. Check here:
```json
{
"amount": {
"value": "12.50",
"currency": "EUR"
},
"counterparty_alias": {
"type": "EMAIL",
"value": "bravo@bunq.com"
},
"description": "Payment for drinks."
}
```
Let's sign that request. First create a variable `$dataToSign` containing the body of the request:
```json
{
"amount": {
"value": "12.50",
"currency": "EUR"
},
"counterparty_alias": {
"type": "EMAIL",
"value": "bravo@bunq.com"
},
"description": "Payment for drinks."
}
```
Next, create the signature of `$dataToSign` using the SHA256 algorithm and the private key `$privateKey` of the Installation's key pair. In PHP, use the following to create a signature. The signature will be passed by reference into `$signature`.
`openssl_sign($dataToSign, $signature, $privateKey, OPENSSL_ALGO_SHA256);`
Encode the resulting `$signature` using base64, and add the resulting value to the request under the `X-Bunq-Client-Signature` header. You have just signed your request, and can send it!
## Response verifying example
The response to the previous request is as follows (the JSON is formatted with newlines and indentations to make it more readable):
Header
Value
Cache-Control:
no-cache
User-Agent:
bunq-TestServer/1.00 sandbox/0.17b3
X-Bunq-Client-Authentication:
f15f1bbe1feba25efb00802fa127042b54101c8ec0a524c36464f5bb143d3b8b
```json
{
"Response": [
{
"Id": {
"id": 1561
}
}
]
}
```
We need to verify that this response was sent by the bunq server and not from a man-in-the-middle:
- Create a `$dataToSign` variable containing the body of the request.
**NOTE:** We started to only sign the response body on April 28, 2020. Please make sure you validate our new response signature.
So for our example above the response to sign will look like this:
```
{"Response":[{"Id":{"id":1561}}]}
```
Now, verify the signature of `$dataToVerify` using the SHA256 algorithm and the public key `$publicKey` of the server. In PHP, use the following to verify the signature.
`openssl_sign($dataToVerify, $signature, $publicKey, OPENSSL_ALGO_SHA256);`
## Troubleshooting
If you get an error telling you "The request signature is invalid", please check the following:
- There are no redundant characters (extra spaces, trailing line breaks, etc.) in the data to sign.
- Make sure the body is appended to the data to sign exactly as you're adding it to the request.
- You have added the full body to the data to sign.
- You use the data to sign to create a SHA256 hash signature.
- You have base64 encoded the SHA256 hash signature before adding it to the request under `X-Bunq-Client-Signature`.
# Headers
HTTP headers allow your client and bunq to pass on additional information along with the request or response.
While this is already implemented in our [SDKs](https://github.com/bunq), please follow these instructions to make sure you set appropriate headers for calls if using bunq API directly.
## Request headers
### Mandatory request headers
#### Cache-Control
`Cache-Control: no-cache`
The standard HTTP Cache-Control header is required for all requests.
#### User-Agent
`User-Agent: bunq-TestServer/1.00 sandbox/0.17b3`
The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.
#### X-Bunq-Client-Signature
**⚠️ UPCOMING CHANGE:** Header and URL signature will stop being validated on April 28, 2020. Please [sign the request body](https://doc.bunq.com/#/signing) only.
`X-Bunq-Client-Signature: XLOwEdyjF1d+tT2w7a7Epv4Yj7w74KncvVfq9mDJVvFRlsUaMLR2q4ISgT+5mkwQsSygRRbooxBqydw7IkqpuJay9g8eOngsFyIxSgf2vXGAQatLm47tLoUFGSQsRiYoKiTKkgBwA+/3dIpbDWd+Z7LEYVbHaHRKkEY9TJ22PpDlVgLLVaf2KGRiZ+9/+0OUsiiF1Fkd9aukv0iWT6N2n1P0qxpjW0aw8mC1nBSJuuk5yKtDCyQpqNyDQSOpQ8V56LNWM4Px5l6SQMzT8r6zk5DvrMAB9DlcRdUDcp/U9cg9kACXIgfquef3s7R8uyOWfKLSNBQpdVIpzljwNKI1Q`
#### X-Bunq-Client-Authentication
`X-Bunq-Client-Authentication: 622749ac8b00c81719ad0c7d822d3552e8ff153e3447eabed1a6713993749440`
The authentication *token* is used to authenticate the source of the API call. It is required by all API calls except for `POST /v1/installation`.
It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call:
- Pass the **installation *Token*** you get in the response to the `POST /installation` call in the `/device-server` and `/session-server` calls.
- Pass the **session *Token*** you get in the response to the `POST /session-server` call in all the other calls.
### Optional request headers
#### X-Bunq-Language
`X-Bunq-Language: en_US`
`en_US` is the default language setting for responses and error descriptions.
The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.
Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.
#### X-Bunq-Region
`X-Bunq-Region: en_US`
`en_US` is the default region for localization formatting.
The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.
#### X-Bunq-Client-Request-Id
`X-Bunq-Client-Request-Id: a4f0de`
This header has to specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.
#### X-Bunq-Geolocation
`X-Bunq-Geolocation: 4.89 53.2 12 100 NL`
`X-Bunq-Geolocation: 0 0 0 0 000` *(if no geolocation is available or known)*
This header has to specify the geolocation of the device. It makes it possible for bunq to map the geolocation with the payment.
The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.
### Attachment headers
#### Content-Type
`Content-Type: image/jpeg`
This header should be used when uploading an attachment to pass its MIME type. Supported types are: image/png, image/jpeg and image/gif.
#### X-Bunq-Attachment-Description
X-Bunq-Attachment-Description: Check out these cookies.
This header should be used when uploading an Attachment's content to give it a description.
## Response headers
### All Responses
#### X-Bunq-Client-Request-Id
`X-Bunq-Client-Request-Id: a4f0de`
The same ID that was provided in the request's X-Bunq-Client-Request-Id header. Is included in the response (and request) signature, so can be used to ensure this is the response for the sent request.
#### X-Bunq-Client-Response-Id
`X-Bunq-Client-Response-Id: 76cc7772-4b23-420a-9586-8721dcdde174`
A unique ID for the response formatted as a UUID. Clients can use it to add extra protection against replay attacks.
#### X-Bunq-Server-Signature
`X-Bunq-Server-Signature: XBBwfDaOZJapvcBpAIBT1UOmczKqJXLSpX9ZWHsqXwrf1p+H+eON+TktYksAbmkSkI4gQghw1AUQSJh5i2c4+CTuKdZ4YuFT0suYG4sltiKnmtwODOFtu1IBGuE5XcfGEDDSFC+zqxypMi9gmTqjl1KI3WP2gnySRD6PBJCXfDxJnXwjRkk4kpG8Ng9nyxJiFG9vcHNrtRBj9ZXNdUAjxXZZFmtdhmJGDahGn2bIBWsCEudW3rBefycL1DlpJZw6yRLoDltxeBo7MjgROBpIeElh5qAz9vxUFLqIQC7EDONBGbSBjaXS0wWrq9s2MGuOi9kJxL2LQm/Olj2g==`
The server's signature for this response. See the signing page for details on how to verify this signature.
### Warning header
#### X-Bunq-Warning
`X-Bunq-Warning: "You have a negative balance. Please check the app for more details."`
Used to inform you on situations that might impact your bunq account and API access.
# Errors
Familiar HTTP response codes are used to indicate the success or failure of an API request.
Generally speaking, codes in the 2xx range indicate success, while codes in the 4xx range indicate an error having to do with provided information (e.g. a required parameter was missing, insufficient funds, etc.).
Finally, codes in the 5xx range indicate an error with bunq servers. If this is the case, please stop by the support chat and report it to us.
## Response codes
Header
Value
Access-Control-Allow-Origin:
*
Content-Type:
application/json
Date:
Thu, 07 Apr 2016 08:32:04 GMT
Server:
APACHE
Strict-Transport-Security:
max-age=31536000
Transfer-Encoding:
chunked
X-Bunq-Client-Response-Id:
89dcaa5c-fa55-4068-9822-3f87985d2268
X-Bunq-Client-Request-Id:
57061b04b67ef
X-Bunq-Server-Signature:
ee9sDfzEhQ2L6Rquyh2XmJyNWdSBOBo6Z2eUYuM4bAOBCn9N5vjs6k6RROpagxXFXdGI9sT15tYCaLe5FS9aciIuJmrVW/SZCDWq/nOvSThi7+BwD9JFdG7zfR4afC8qfVABmjuMrtjaUFSrthyHS/5wEuDuax9qUZn6sVXcgZEq49hy4yHrV8257I4sSQIHRmgds4BXcGhPp266Z6pxjzAJbfyzt5JgJ8/suxgKvm/nYhnOfsgIIYCgcyh4DRrQltohiSon6x1ZsRIfQnCDlDDghaIxbryLfinT5Y4eU1eiCkFB4D69S4HbFXYyAxlqtX2W6Tvax6rIM2MMPNOh4Q==
X-Frame-Options:
SAMEORIGIN
All errors 4xx code errors will include a JSON body explaining what went wrong.
## Rate limits
If you are receiving the error 429, please make sure you are sending requests at rates that are below our rate limits.
Our rate limits per IP address per endpoint:
- GET requests: 3 within any 3 consecutive seconds
- POST requests: 5 within any 3 consecutive seconds
- PUT requests: 2 within any 3 consecutive seconds
- Callbacks: 2 callback URLs per notification category
We have a lower rate limit for `/session-server`: 1 request within 30 consecutive seconds.
# API conventions
Make sure to follow these indications when using the bunq API or get started with our SDKs.
## Responses
All JSON responses have one top level object. In this object will be a Response field of which the value is always an array, even for responses that only contain one object.
Example response body
```json
{
"Response": [
{
"DataObject": {}
}
]
}
```
## Errors
- Error responses also have one top level Error object.
- The contents of the array will be a JSON object with an error_description and error_description_translated field.
- The error_description is an English text indicating the error and the error_description_translated field can be shown to end users and is translated into the language from the X-Bunq-Language header, defaulting to en_US.
- When using bunq SDKs, error responses will be always raised in form of an exception.
Example response body
```json
{
"Error": [
{
"error_description": "Error description",
"error_description_translated": "User facing error description"
}
]
}
```
## Object Type indications
When the API returns different types of objects for the same field, they will be nested in another JSON object that includes a specific field for each one of them. Within bunq SDKs a BunqResponse object will be returned as the top level object.
In this example there is a field content, which can have multiple types of objects as value such as — in this case — ChatMessageContentText. Be sure to follow this convention or use bunq SDKs instead.
```json
{
"content": {
"ChatMessageContentText": {
"text": "Hi! This is an automated security message. We saw you just logged in on an My Device Description. If you believe someone else logged in with your account, please get in touch with Support."
}
}
}
```
## Time formats
Times and dates being sent to and from the API are in UTC. The format that should be used is `YYYY-MM-DD hh:mm:ss.ssssss`, where the letters have the meaning as specified in ISO 8601. For example: `2017-01-13 13:19:16.215235`.
# Callbacks
Callbacks are used to send information about events on your bunq account to a URL of your choice, so that you can receive real-time updates.
## Notification Filters
To receive notifications for certain activities on a bunq account, you have to create notification filters. It is possible to send the notifications to a provided URL and/or the user’s phone as push notifications.
Use the `notification-filter-push` resource to create and manage push notification filters. Provide the type of events you want to receive notifications about in the `category` field.
```json
{
"notification_filters":[
{
"category":"SCHEDULE_RESULT"
}
]
}
```
Use the `notification-filter-url` resource to create and manage URL notification filters. The callback URL you provide in the `notification_target` field must use HTTPS.
```json
{
"notification_filters":[
{
"category":"PAYMENT",
"notification_target":"{YOUR_CALLBACK_URL}"
}
]
}
```
### Callback categories
Code
Error
Description
200
OK
Successful HTTP request
399
NOT MODIFIED
Same as a 304, it implies you have a local cached copy of the data
400
BAD REQUEST
Most likely a parameter is missing or invalid
401
UNAUTHORISED
Token or signature provided is not valid
403
FORBIDDEN
You're not allowed to make this call
404
NOT FOUND
The object you're looking for cannot be found
405
METHOD NOT ALLOWED
The method you are using is not allowed for this endpoint
429
RATE LIMIT
Too many API calls have been made in a too short period
466
REQUEST SIGNATURE REQUIRED
Request signature is required for this operation.
490
USER ERROR
Most likely a parameter is missing or invalid
491
MAINTENANCE ERROR
bunq is in maintenance mode
500
INTERNAL SERVER ERROR
Something went wrong on bunq's end
### Mutation category
A Mutation is a change in the balance of a monetary account. So, for each payment-like object, such as a request, iDEAL-payment or a regular payment, a Mutation is created. Therefore, the `MUTATION` category can be used to keep track of a monetary account's balance.
### Receiving callbacks
Callbacks for the sandbox environment will be made from different IP's at AWS.
Callbacks for the production environment will be made from `185.40.108.0/22`.
*The IP addresses might change*. We will notify you in a timely fashion if such a change would take place.
### Retry mechanism
When the execution of a callback fails (e.g. if the callback server is down or the response contains an error) it is tried again for a maximum of 5 times, with an interval of one minute between each try. If your server is not reachable by the callback after the 6th total try, the callback is not sent anymore.
### Removing callbacks
To remove callbacks for an object, send a PUT request to the *user-person*, *user-company*, *monetary-account* or *cash-register* resource with the `notification_filters` field of the JSON request body unset.
```
{
"notification_filters": []
}
```
## Certificate pinning
We recommend you use certificate pinning as an extra security measure. With certificate pinning, we check the certificate of the server on which you want to receive callbacks against the pinned certificate that has been provided by you and cancel the callback if that check fails.
### How to set up certificate pinning
Retrieve the SSL certificate of your server using the following command:
1. `openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem`
2. `POST` the certificate to the certificate-pinned endpoint.
Now every callback that is made will be checked against the pinned certificate that you provided. Note that if the SSL certificate on your server expires or is changed, our callbacks will fail.
# Pagination
In order to control the size of the response of a `LIST` request, items can be paginated. A `LIST` request is a request for every one of a certain resources, for instance all payments of a certain monetary account `GET /v1/user/1/monetary-account/1/payment`). You can decide on the maximum amount of items of a response by adding a `count` query parameter with the number of items you want per page to the URL. For instance:
`GET /v1/user/1/monetary-account/1/payment?count=25`
When no `count` is given, the default count is set to 10. The maximum `count` you can set is 200.
With every listing, a `Pagination` object will be added to the response, containing the URLs to be used to get the next or previous set of items. The URLs in the Pagination object can be used to navigate through the listed resources. The Pagination object looks like this given a count of 25:
```json
{
"Pagination": {
"future_url": null,
"newer_url": "/v1/user/1/monetary-account/1/payment?count=25&newer_id=249",
"older_url": "/v1/user/1/monetary-account/1/payment?count=25&older_id=224"
}
}
```
The `newer_url` value can be used to get the next page. The `newer_id` is always the ID of the last item in the current page. If `newer_url` is `null`, there are no more recent items before the current page.
The `older_url` value can be used to get the previous page. The `older_id` is always the ID of the first item in the current page. If `older_url` is `null`, there are no older items after the current page.
The `future_url` can be used to refresh and check for newer items that didn't exist when the listing was requested. The `newer_id` will always be the ID of the last item in the current page. `future_url` will be `null` if `newer_id` is not also the ID of the latest item.
# Sandbox
*The sandbox base URL is https://public-api.sandbox.bunq.com/v1/*
We do not use real money and do not allow external transactions in the sandbox environment.
## Sandbox user accounts
You need to create a sandbox user to test the bunq API. The easiest way to do it is by using [our developer portal](https://developer.bunq.com/):
1. Log in using your bunq account or [create a free developer account](https://developer.bunq.com/portal/signup) with sandbox-only access.
1. Go to Sandbox Users.
1. Generate up to 5 users.
1. Use the sandbox API key to create an API context and/or use the user credentials to log in to the [sandbox bunq app](https://doc.bunq.com/#/android-emulator).
### Alternative ways to generate sandbox API keys
There are 3 other ways you can generate a bunq sandbox API key:
* connect to [Tinker](https://lexy.gitbook.io/bunq/quickstart/tinker) *(it will also return login credentials for the sandbox app)*;
* create it in the [sandbox app](https://doc.bunq.com/#/android-emulator) *(you need to be logged in as a sandbox user)*;
* call the sandbox user endpoints directly, using [our Postman collection](https://github.com/bunq/postman), or by running a cURL command (change `sandbox-user-person` to `sandbox-user-company` to generate a business user):
```
curl https://public-api.sandbox.bunq.com/v1/sandbox-user-person -X POST --header "Content-Type: application/json" --header "Cache-Control: none" --header "User-Agent: curl-request" --header "X-Bunq-Client-Request-Id: $(date)randomId" --header "X-Bunq-Language: nl_NL" --header "X-Bunq-Region: nl_NL" --header "X-Bunq-Geolocation: 0 0 0 0 000"
```
⚠️ **NOTE:** An API key can only be assigned to an IP within 1 hour after its creation. After the 1 hour, it will become invalid if not assigned. API keys that are created via the sandbox app are wiped with each sandbox reset.
Once you have a sandbox API key, create more sandbox users to use as test customer accounts, and start playing with the API.
The sandbox base URL is https://public-api.sandbox.bunq.com/v1/.
## Sandbox money
Without money, it's not always sunny in the sandbox world. Fortunately, getting money on the bunq sandbox is easy. All you need to do is ask Sugar Daddy for it.
Send a `POST v1/request-inquiry` request passing sugardaddy@bunq.com in the counterparty_alias field. Specify the type for the alias and set the `allow_bunqme` field. Request up to €500 at a time.
```
{
"amount_inquired": {
"value": "100",
"currency": "EUR"
},
"counterparty_alias": {
"type": "EMAIL",
"value": "sugardaddy@bunq.com",
"name": "Sugar Daddy"
},
"description": "You're the best!",
"allow_bunqme": false
}
```
# Android Emulator
In case you do not own an Android device on which you can run our Sandbox app for end-to-end testing, you can set up an emulator to run the bunq Sandbox app for Android.
## Things you will need
- The [bunq Sandbox App APK](https://appstore.bunq.com/api/android/builds/bunq-android-sandbox-master.apk) that's optimised for emulating;
- [Android Studio](https://developer.android.com/studio/index.html).
## Starting the Android Virtual Device (AVD) Manager
1. Open Android Studio.
2. From the top menu, select “Tools” > "Android" > "AVD Manager".
## Setting up a new virtual device
1. Start the wizard by clicking on "+ Create Virtual Device".
2. Select a device (recommendation: "Pixel 5.0" or "Nexus 6") and press "Next".
3. Select an x86 system image (recommendation: Nougat, API Level 25, Android 7.1.1 with Google APIs) and press "Next". The image needs to have Google Play Services 10.0.1 or higher.
4. In the bottom left corner, select "Show Advanced Settings".
5. Scroll to "Memory and Storage".
6. Change "Internal Storage" to "2048 MB".
7. Change "SD card" to "200 MB".
8. Press "Finish".
## Starting the virtual device
1. On the right side under "Actions", select the green "Play" button.
2. Wait for the device to boot, this may take a few minutes.
## Installing the bunq Sandbox App APK
1. Open the command line.
2. Navigate to your Android SDK platform tools directory (e.g. `cd ~/Library/Android/sdk/platform-tools` on macOS).
3. Make sure that the virtual device is started and has fully booted.
4. Run `./adb install ~/Downloads/bunq-android-sandboxEmulator-public-api.apk`, this may take a few minutes, and should finish with "Success".
## Creating an account or logging in
1. Create a sandbox account in the [developer portal](https://developer.bunq.com/).
1. Log in to the sandbox app using the sandbox user credentials.
ℹ️ *You will be asked to verify your phone number when you open the app for the first time. Sandbox does not send actual SMS messages. Enter any valid phone number and use the default verification code `992266`*.
If you couldn't generate a sandbox account in the developer portal, use Tinker:
1. Install [Tinker](https://beta.doc.bunq.com/quickstart/tinker).
1. Run `tinker/user-overview` to create a sandbox account. The output of the command will include the login credentials for the sandbox account.
⚠️ **NOTE:** It is **not** possible to create accounts using the regular signup in the app, bunq is not reviewing Sandbox applications.
# Moving to Production
Have you tested your bunq integration to the fullest and are you now ready to introduce it to the world? Then the time has come to move it to a production environment!
To get started you'll need some fresh API keys for the production environment, which you can create via your bunq app. You can create these under "Profile" by tapping the "Security" menu. We do, however, highly recommend using a standard API Key instead of a Wildcard API Key. The former is significantly safer and it protects you from intrusions and possible attacks.
There's only a few things to do before your beautiful bunq creation can be moved to production. You're going to have to change your API Key and redo the sequence of calls to open a session.
The bunq Public API production environment is hosted at `https://api.bunq.com`.
Do you have any questions or remarks about the process, or do you simply want to show off with your awesome creations? Don't hesitate to drop us a line on [together.bunq.com](https://together.bunq.com).
Please be aware that if you will gain access to account information of other bunq users or initiate a payment for them, you maybrequire a PSD2 permit.
# Quickstart: Opening a Session
## Goal
So, you want to start using the bunq API, awesome! To do this, you have to open a session in which you will be making those calls.
## Getting an API key
To connect to the API, you have to make sure you have received an API key.
**For production:**
1. create an app in the [developer portal](http://developer.bunq.com/), or
1. generate it in the bunq app *(Profile → Security & Settings → Developers → API keys)*.
**For sandbox**
You can use one of the following ways:
- create a sandbox user in the [developer portal](http://developer.bunq.com/);
- generate an API key in the [sandbox app](#android-emulator) *(Profile → Security & Settings → Developers → API keys)*;
- get an API key from [Tinker](https://beta.doc.bunq.com/quickstart/tinker);
- run a cURL request: `curl https://public-api.sandbox.bunq.com/v1/sandbox-user-person -X POST --header "Content-Type: application/json" --header "Cache-Control: none" --header "User-Agent: curl-request" --header "X-Bunq-Client-Request-Id: $(date)randomId" --header "X-Bunq-Language: nl_NL" --header "X-Bunq-Region: nl_NL" --header "X-Bunq-Geolocation: 0 0 0 0 000"`. Use `sandbox-user-company` to generate a business user.
Note that production API key is only usable on production and sandbox key is only usable on sandbox. Sandbox key has a `sandbox_` prefix while production key does not have any noticeable prefixes.
## Call sequence
The calls you need to perform to set up a session from scratch are the following:
### 1. POST installation
Each call needs to be signed with your own private key. An Installation is used to tell the server about the public key of your key pair. The server uses this key to verify your subsequent calls.
Start by generating a 2048-bit RSA key pair. You can find examples by looking at the source code of the sdk's located at github.
#### Headers
On the headers page you can find out about the mandatory headers. Take care that if you are in the sandbox environment, you set an `Authorization` header. Specific to the `POST /installation` call, you shouldn't use the `X-Bunq-Client-Authentication` or the `X-Bunq-Client-Signature` headers.
#### Body
Post your public key to the Installation endpoint (use `\n` for newlines in your public key).
#### Response
Save the Installation token and the bunq API's public key from the response. This token is used in the `Authentication` header to register a `DeviceServer` and to start a `SessionServer`. The bunq API's public key should be used to verify future responses received from the bunq API.
### 2. POST device-server
Further calls made to the server need to come from a registered device. `POST /device-server` registers your current device and the IP address(es) it uses to connect to the bunq API.
#### Headers
Use the token you received from `POST /installation` in the `X-Bunq-Client-Authentication` header. Make sure you sign your call, passing the call signature in `X-Bunq-Client-Signature` header.
#### Body
For the secret, use the API key you received. If you want to create another API key, you can do so in the bunq sandbox app (or production app for the production environment). Login, go to Profile > Security and tap 'API keys'. The freshly created API key can be assigned to one or multiple IP addresses using `POST device-server` within 4 hours before becoming invalid. As soon as you start using your API key, it will remain valid until the next sandbox reset.
For the secret, use the API key you received.
### 3. POST session-server
To make any calls besides `installation` and `device-server`, you need to open a session.
#### Headers
Use the token you received from `POST /installation` in the `X-Bunq-Client-Authentication` header. Make sure you sign your call, passing the call signature in `X-Bunq-Client-Signature` header.
#### Body
For the secret, use the API key you received.
#### Response
The token received in the response to `POST /session-server` should be used to authenticate your calls in this session. Pass this session's token in the `X-Bunq-Client-Authentication` header on every call you make in this session.
# Quickstart: Payment Request
## Goal
You want to offer bunq payments on a website or in an application.
## Scenario
In this use case the consumer and the merchant both have a bunq account. The consumer wants to pay with bunq and enters their alias in the bunq payment field at checkout. The merchant sends the request for payment to the consumer when the consumer presses enter. The consumer agrees to the request in the bunq mobile app and the merchant has immediate confirmation of the payment. Please be aware that if you will gain access to account information of other bunq users or initiate a payment for them, you require a PSD2 permit.
## Before you start
Make sure that you have opened a session and that for any call you make after that, you pass the session’s token in the X-Bunq-Client-Authentication header.
## Call Sequence
The consumer is at checkout and selects the bunq payment method. This would be a logical time to open a session on the bunq server.
### 1. LIST monetary-account
When a request for payment is accepted, the money will be deposited on the bank account the request for payment is connected to. Let’s start by finding all your available bank accounts. Pick one of them to make the request for payment with and save its `id`.
### 2. POST monetary-account attachment (optional)
Optionally, you can attach an image to the request for payment.
#### Headers
Make sure you set the `Content-Type` header to match the MIME type of the image. It’s also required you pass a description of the image via the `X-Bunq-Attachment-Description` header.
#### Body
The payload of this request is the binary representation of the image file. Do not use any JSON formatting.
#### Response
Save the `id` of the posted attachment. You’ll need it to attach it to the request for payment.
### 3. POST request-inquiry
Next, create a request inquiry. A request inquiry is the request for payment that your customer can respond to by accepting or rejecting it.
#### Body
Pass the customer’s email address, phone number or IBAN in the `counterparty_alias`. Make sure you set the correct `type` for the alias, depending on what you pass. When providing an IBAN, a name of the `counterparty_alias` is required. You can provide the `id` of the created attachment.
#### Response
You will receive the `id` of the created request inquiry in the response. Save this `id`. You will need it to check if the customer has responded to the request yet.
### 4. GET request-inquiry
After you’ve sent the request for payment, its status can be checked.
#### Response
When the `status` is `ACCEPTED`, the customer has accepted and paid the request, and you will have received the money on the connected monetary account. If the `status` is `REJECTED`, the customer did not accept the request.
# Quickstart: Create a Tab payment
## Goal
You will create a tab that can be paid once by a single user, a so called TagUsageSingle, and explore three different ways to make the Tab visible to your customers:
- QR code from the CashRegister
- QR code from the Tab.
## Before you start
Make sure that you have opened a session and that for any call you make after that, you pass the session’s token in the `X-Bunq-Client-Authentication` header.
## Call sequence
### 1. POST attachment-public
Start by creating an attachment that will be used for the avatar for the cash register.
#### Header
Make sure you set the `Content-Type` header to match the MIME type of the image. It is also required you pass a description of the image via the `X-Bunq-Attachment-Description` header.
#### Body
The payload of this request is the binary representation of the image file. Do not use any JSON formatting.
#### Response
Save the `uuid` of the posted attachment. You'll need it to create the avatar in the next step.
### 2. POST avatar
Make an avatar using the public attachment you've just created.
#### Body
The payload of this request is the `uuid` of the attachment public.
#### Response
In response, you’ll receive the UUID of the avatar created using the attachment. Save this UUID. You’ll use it as the avatar for the cash register you're about to create.
### 3. LIST monetary-account
Get a listing of all available monetary accounts. Choose one, and save the id of the monetary account you want your cash register to be connected to. Each paid tab for the cash register will transfer the money to this account.
### 4a. POST cash-register
Create a cash register. Use the `id` of the monetary account you want to connect the cash register to in the URL of the request.
#### Body
In the body provide the `uuid` of the avatar you created for this cash register. Also make sure to provide a unique name for your cash register. Set the status to `PENDING_APPROVAL`.
#### Response
The response contains the `id` of the cash register you created. Save this `id`. You will need it to create subsequent tabs and tab items.
### 4b. Wait for approval
On the production environment, a bunq admin will review and approve your cash register. In the sandbox environment, your cash register will be automatically approved.
### 5. POST tab-usage-single
Create a new tab that is connected to your cash register. Use the id of the cash register you want to connect this tab to in the URL of your request.
#### Body
Give the tab a name in `merchant_reference`. Create the tab with status `OPEN`, and give the tab a starting amount. You can update this amount later.
#### Response
The response contains the uuid of the tab you created.
### 6. POST tab-item (optional)
You can add items to a tab. For instance, if a customer will be paying for multiple products via this tab, you can decide to add an item for each of these. Adding items to a tab is optional, and adding them will not change the total amount of the tab itself. However, if you've added any tab items the sum of the amounts of these items must be equal to the `total_amount` of the tab when you change its status to `WAITING_FOR_PAYMENT`.
### 7. PUT tab-usage-single
Update the status of the tab to `WAITING_FOR_PAYMENT` if you want the costumer to pay the tab, and you're done adding any tab items. You can use this request to make the tab visible for your costumers.
#### Visibility
To decide how you are going to make your tab visible, pass a visibility object in the payload.
Setting `cash_register_qr_code` to true will connect this tab to the QR code from the cash register. If this cash register does not have a QR code yet, one will be created. Only one Tab can be connected to the cash register’s QR code at any given time.
Setting `tab_qr_code` to true will create a QR code specifically for this tab. This QR code can not be linked to anything else.
# Quickstart: Create a TransferWise payment
## Goal
You want to send a payment in currency other than euro outside the SEPA zone.
## Before you start
Make sure that you have opened a session and that for any call you make after that, you pass the session’s token in the `X-Bunq-Client-Authentication` header.
ℹ️ *bunq relies on TransferWise for international, so you need to create a TransferWise account linked to a bunq account to be able to create international transfers. You can do it either from the bunq app or using our API as described below.*
## Get the up-to-date exchange rate (optional)
You might want to check the latest currency exchange rate before making a transfer. Here’s how you can do it using the bunq API:
1. Check the list of supported currencies via `GET /user/{userID}/transferwise-currency`. Copy the needed currency code.
2. Create a temporary quote for the currency of your choice via `POST /user/{userID}/transferwise-quote-temporary`.
ℹ️ *A quote is the exchange rate at the exact timestamp. Temporary quotes carry solely informative value and cannot be used for creating a transfer.*
3. Read the temporary quote via `GET /user/{userID}/transferwise-quote-temporary/{transferwise-quote-temporaryID}`.
## Create a TransferWise account
You need a TransferWise account linked to your bunq account to make TransferWise payments via the bunq API. Create one via `POST /user/{userID}/transferwise-user`, and save its ID.
ℹ️ *You cannot use an existing TransferWise account.*
## Create a quote
1. Create a quote via POST /user/{userID}/transferwise-quote and save its ID.
ℹ️ *Use amount_target to indicate the sum the recipient must get. Amount_source, on the other hand, will indicate the sum you want to send, but it will not necessarily be the final sum the recipient gets.*
ℹ️ *Quotes are valid for 30 minutes so if you do not manage to create a transfer within this time, you will need to create another quote.*
2. Get the exchange rate by reading the quote via GET /user/{userID}/transferwise-quote/(transferwise-quoteID).
## Create a recipient
If you have sent money via the TransferWise account linked to your bunq account, you can reuse the recipients. You can list their IDs via `GET /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient`.
To create a new, previously unused recipient, follow these steps:
1. Retrieve the fields required for creating the recipient as the requirements vary for the type of recipient in each country. Iterate sending the following request pair till there are no more required fields:
- `GET /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient-requirement`
- `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient-requirement`
2. Create a recipient account using the final request body from the previous step with `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient-requirement`
## Create a transfer
Finally, having both the quote ID and the recipient ID, you can create a transfer. 🎉
1. Check if there are any additional transfer requirements via `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-transfer-requirement`.
2. Create a transfer via `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-transfer`. You need to specify the ID of the monetary account from which you want the payment to be made.
# Quickstart: Downloading attachments
## Goal
Export receipts and invoices attached to payments to your application.
## The scenario you want to achieve
0. The bunq user has accepted the authorization request and your application can read the bunq user’s account information.
1. Your application imports all the transactions and attachments.
2. The bunq user sees the transactions matched with the receipts and invoices in your application.
## Before you start
* Make sure that you have opened a session
* Make sure you pass the session Token in the X-Bunq-Client-Authentication header in all the following requests of the session.
## Call sequence
1. List the payments of the user via GET /user/{userID}/monetary-account/{monetary-accountID}/payment.
2. Check if the payments have attachments via GET /user/{userID}/monetary-account/{monetary-accountID}/payment/{paymentID}/note-attachment. Save the attachment IDs.
3. Export the raw content of the attachments via GET /user/{userID}/attachment/{attachmentID}/content.
***HINT:** You can use [callbacks](https://doc.bunq.com/#/callbacks) to make sure you don’t miss anything happening on the bunq account.*
Category
Description
BILLING
notifications for all bunq invoices
CARD_TRANSACTION_SUCCESSFUL
notifications for successful card transactions
CARD_TRANSACTION_FAILED
notifications for failed card transaction
CHAT
notifications for received chat messages
DRAFT_PAYMENT
notifications for creation and updates of draft payments
IDEAL
notifications for iDEAL-deposits towards a bunq account
SOFORT
notifications for SOFORT-deposits towards a bunq account
MUTATION
notifications for any action that affects a monetary account’s balance
OAUTH
notifications for revoked OAuth connections
PAYMENT
notifications for payments created from, or received on a bunq account (doesn’t include payments that result out of paying a Request, iDEAL, Sofort or Invoice). Outgoing payments have a negative value while incoming payments have a positive value
REQUEST
notifications for incoming requests and updates on outgoing requests
SCHEDULE_RESULT
notifications for when a scheduled payment is executed
SCHEDULE_STATUS
notifications about the status of a scheduled payment, e.g. when the scheduled payment is updated or cancelled
SHARE
notifications for any updates or creation of Connects (ShareInviteBankInquiry)
TAB_RESULT
notifications for updates on Tab payments
BUNQME_TAB
notifications for updates on bunq.me Tab (open request) payments
SUPPORT
notifications for messages received from us through support chat
This document provides the documentation for the Market Intelligence API by Automata. Get your API Key at https://apis.byautomata.io and check out our Postman Collection.
The root API endpoint is https://api.byautomata.io. Please refer to the code samples for examples of how to call the Market Intelligence API. The ContentPro endpoints (/contentpro-search and /contentpro-similar-text) are not included in the standard Market Intelligence API plans. Please contact support@byautomata.io for access.