API introduction

finmid API is organised around REST. Our API has resource-oriented URLs, accepts JSON‑encoded request bodies, returns JSON‑encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Making REST API calls

To make a REST API call, include the URL associated with the sandbox or live environment.

• Sandbox: https://sandbox.finmid.com
• Live: https://api.finmid.com

⚠️

Caution:

Including the live URL while calling finmid's API will affect your live data and might interact with the banking network. We recommend using the sandbox URL for testing.

Authentication

You can access an API by providing an API key using the HTTP request header X-API-Key.

Sample authenticated request:

curl \
    -X GET 'https://api.finmid.com/api/v2/sellers/:id' \
    -H "X-API-Key: <API-Key>"

API keys are generated per environment. Therefore, API keys generated for sandbox use will not have access to the live data and vice versa.

You can monitor and generate API keys through our Dashboard.

💡

If you don't have access to the dashboard, please reach out to our sales team to be able to access the live/sandbox API Keys.

⚠️

Caution:

Refrain from keeping any of your API keys public or in any version control system that you may be using. Save and store your API keys in a secure place, such as a password manager or secrets management service.

Errors

finmid API utilizes conventional HTTP response codes to indicate the success or failure of an API request.

Response code ranges

• 2XX success code range, confirms that your request worked as expected
• 4XX client side errors, indicates an error because of the information provided (for example, a required parameter was omitted)
• 5XX server side errors, indicates an error with finmid's servers

Error response object

Error responses usually contain additional JSON-encoded error information.

Sample response

{
    "code": "validation_error",
    "description": "The provided HTTP request body contains invalid data"
}