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 apassword 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.

Field	Type	Description
`code`	`string`	A short string specifying the error code. Examples: `validation_error`, `server_error`
`description`	`string`	A human-readable message provides more details about the error.

Sample response

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