API Reference / Accounts REST

Actions

Creates a new account for an identity.

POST/accounts

Create Account

Headers

Authorizationstringrequired

Bearer access token returned by the authentication endpoint.

x-api-keystringrequired

The API key used for authentication when making requests to the API Gateway.

conomyhq-api-versionstring

API version selector for Conomy endpoints. Use 24-04-2025 for the current version.

User-Agentstringrequired

Identifies the application making the request.

Request body

identityIdstringrequired

Identifier linking the internal account to an organization or user.

externalIdstring

External reference identifier for integrations.

typestringrequired

CHECKINGASSETSAVINGSESCROWFEE

custodystringrequired

Indicates the custody type managing the internal account.

currencystringrequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

namestringrequired

A friendly name assigned to the internal account.

parentIdstring

Identifier of the parent account if this is a sub-account.

custodyBankAccountobject

Details of the custody bank account linked to this internal account.

accountNumberstringrequired

The bank account number.

bankstringrequired

The name of the bank where the account is held.

currencystringrequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

typeAccountstring

The type of bank account. CHECKING_ACOUNT, SAVINGS

countrystringrequired

Country of operations for the entity, specified using the ISO 3166-1 alpha-3 standard (e.g., CHL, USA, MEX). Go to the countries page for the complete list of supported values.

Responses

201Resource created successfully.

idstringrequired

Unique identifier for the internal service.

identityIdstringrequired

Identifier linking the internal account to an organization or user.

externalIdstringrequired

External reference identifier for integrations.

typestringrequired

CHECKINGFiat liquid account used for spending, withdrawals, or operations.

ASSETTracks non-operational or financial assets.

SAVINGSHolds funds intended for savings or long-term storage.

ESCROWTemporary routing account for incoming funds.

FEEHolds all fees collected via FEE or FEE_INVOICE.

custodystringrequired

Indicates the custody type managing the internal account.

balancestring/^\d+(\.\d+)?$/required

Total balance available in the internal account.

availableFundsstring/^\d+(\.\d+)?$/required

Amount of funds available for transactions.

currencystringrequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

namestringrequired

A friendly name assigned to the internal account.

accountNumberstringrequired

Internal reference number for the account.

accountHolderstringrequired

Name of the entity or user owning the internal account.

statusstringrequired

The current status of the account (e.g., PENDING, ACTIVE, BLOCKED).

parentIdstringrequired

Identifier of the parent account if this is a sub-account.

subAccountsobjectshow 2 properties

Details of sub-accounts associated with this internal account.

custodyBankAccountobjectshow 5 properties

Details of the custody bank account linked to this internal account.

400Invalid request parameters or payload.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

500Unexpected internal server error.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

Request

HTTPcurlTypeScriptPythonGoRust

POST /sandbox/accounts HTTP/1.1
Host: api.conomyhq.com
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {YOUR_API_KEY}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json

{
  "identityId": "069b63ba-a8cd-4b0e-bb2f-ffc7d71f2dac",
  "externalId": "1",
  "type": "real",
  "currency": "PKR",
  "name": "Auto Loan Account",
  "parentId": "a3f87719-1dd7-46c7-9953-e0f3a71542a3"
}

curl -X POST \
  'https://api.conomyhq.com/sandbox/accounts' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityId": "069b63ba-a8cd-4b0e-bb2f-ffc7d71f2dac",
    "externalId": "1",
    "type": "real",
    "currency": "PKR",
    "name": "Auto Loan Account",
    "parentId": "a3f87719-1dd7-46c7-9953-e0f3a71542a3"
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/accounts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "identityId": "069b63ba-a8cd-4b0e-bb2f-ffc7d71f2dac",
    "externalId": "1",
    "type": "real",
    "currency": "PKR",
    "name": "Auto Loan Account",
    "parentId": "a3f87719-1dd7-46c7-9953-e0f3a71542a3"
  }),
});

const data = await response.json();

import requests

payload = {
    "identityId": "069b63ba-a8cd-4b0e-bb2f-ffc7d71f2dac",
    "externalId": "1",
    "type": "real",
    "currency": "PKR",
    "name": "Auto Loan Account",
    "parentId": "a3f87719-1dd7-46c7-9953-e0f3a71542a3"
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/accounts',
    headers={
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    },
    json=payload
)

data = response.json()

package main

import (
	"encoding/json"
	"net/http"
	"bytes"
)

func main() {
	payload, _ := json.Marshal(	{
	  "identityId": "069b63ba-a8cd-4b0e-bb2f-ffc7d71f2dac",
	  "externalId": "1",
	  "type": "real",
	  "currency": "PKR",
	  "name": "Auto Loan Account",
	  "parentId": "a3f87719-1dd7-46c7-9953-e0f3a71542a3"
	})
	body := bytes.NewBuffer(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/accounts", body)
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let resp = client
        .post("https://api.conomyhq.com/sandbox/accounts")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .json(&json!({
        "identityId": "069b63ba-a8cd-4b0e-bb2f-ffc7d71f2dac",
        "externalId": "1",
        "type": "real",
        "currency": "PKR",
        "name": "Auto Loan Account",
        "parentId": "a3f87719-1dd7-46c7-9953-e0f3a71542a3"
}))
        .send()
        .await?;

    let data: serde_json::Value = resp.json().await?;
    Ok(())
}

Response

201 400 401 403 404 422 500

{
  "id": "string",
  "identityId": "string",
  "externalId": "string",
  "type": "CHECKING",
  "custody": "string",
  "balance": "string",
  "availableFunds": "string",
  "currency": "string",
  "name": "string",
  "accountNumber": "string"
}

{
  "error": {
    "type": "bad_request",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "unauthorized",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "forbidden",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "not_found",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "validation_error",
    "info": {
      "field": "string",
      "message": "string"
    }
  },
  "message": null
}

{
  "error": {
    "type": "internal_error",
    "info": null
  },
  "message": null
}