The account holder, external account, and internal account Numeral objects enable you to manage your customers, suppliers, vendors, and partners and their accounts.

Object	Description
Account holder	An account holder is an individual or organization you need to send money to, receive money from or hold account on behalf of. It can be a customer, a supplier, a merchant, a partner, a group company, etc.
External account	An external account is a bank account in the name of the account holder. An account holder can have different external accounts, for distinct use cases, in different currencies, or at multiple banks.
Internal account	An internal account is a bank, payment, or electronic money account your organization holds on behalf of one of your customers. It is only applicable to financial institutions. An account holder can have different internal accounts.

Account holder

Create an account holder

To create an account holder, use the Create account holder API endpoint:

curl --request POST \
     --url https://sandbox.numeral.io/v1/account_holders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "name": "PartnerCo",
  "metadata": {
    "internal_id": "123"
  }
}
'

The API will return the account holder object:

#{
    "id": "de785fd3-da86-45c7-a185-719ebfb2122d",
    "object": "account_holder",
    "name": "PartnerCo",
    "metadata": {
      "internal_id": "123"
    },
    "created_at": "2022-09-05T14:54:11.76182Z",
    "disabled_at": null,
}

Disable an account holder

You can disable an account holder. Disabling an account holder also disables the associated external and internal accounts. A disabled account holder has a disabled_at timestamp. A disabled account holder can no longer be used to create an external or internal accounts and will trigger an error.

External accounts

Create external accounts

After an account holder has been created, you can add external accounts related to this account holder. An external account is the bank account of an account holder. It must have all the account details required to send a payment to this counterparty. Uou can create an external account with or without an account holder.

To create an external account, use the Create external account API endpoint:

curl --request POST \
     --url https://sandbox.numeral.io/v1/external_accounts \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
    "account_holder_id": "de785fd3-da86-45c7-a185-719ebfb2122d",
    "holder_name": "PartnerCo SAS",
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "holder_address": {
        "line_1": "1, rue de la Bourse",
        "line_2": "",
        "postal_code": "59000",
        "region_state": "",
        "city": "Lille",
        "country": "FR"
    },
}

The API will return the external account object:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object": "external_account",
  "account_holder_id": "de785fd3-da86-45c7-a185-719ebfb2122d",
  "holder_name": "PartnerCo SAS",
  "account_number": "FR7601234567891127967100082",
  "bank_code": "BNPAFRPPXXX",
  "holder_address": {
    "line_1": "1, rue de la Bourse",
    "line_2": "",
    "postal_code": "59000",
    "region_state": "",
    "city": "Lille",
    "country": "FR"
  },
  "metadata": {},
  "created_at": "2022-09-06T19:38:26.442Z",
  "disabled_at": "2022-09-06T19:38:26.442Z",
}

Create a payment order using an external account

To create a payment order using an external account, use its ID in the receiving_account_id body parameter of your Create payment order API request. The receiving account data will be populated with the related external account details. Creating an external account and using its ID simplifies your API requests as well as enables you to filter payment orders by external account or account holder.

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "connected_account": "711b414e-2d31-11ed-a261-0242ac120002",
  "type": "sepa",
  "direction": "credit",
  "amount": 1000,
  "currency": "EUR",
  "receiving_account_id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
  "reference": "Payment 85a7407c",
}

Create an expected payment using an external account

Similarly, you can create an expected payment using the ID of an external account in the external_account_id body parameter of your Create expected payment API request. The external account data will be populated with the related external account details. Creating a external account and using its ID simplifies your API requests as well as enables you to filter expected payments by external account or account holder.

curl --request POST \
     --url https://sandbox.numeral.io/v1/expected_payments \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "connected_account_id": "711b414e-2d31-11ed-a261-0242ac120002",
  "direction": "credit",
  "amount_from": 1000,
  "amount_to": 1000,
  "currency": "EUR",
  "start_date": "2022-09-05",
  "end_date": "2022-09-10",
  "external_account_id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
  "description": "Subscription 11eda261",
}

Internal accounts

An internal account is a bank, payment, or electronic money account your organization holds. It is only applicable to financial institutions. An internal can be one of two types:

own: your organization holds this account one behalf of one of its customers, it uses your BIC and an account number you generated
virtual: your organizations uses a virtual account number provided by your partner bank

Create an internal account

To create an internal account, use the Create internal account API endpoint with or without an account holder:

curl --request POST \
     --url https://sandbox.numeral.io/v1/internal_accounts \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
    "account_holder_id": "de785fd3-da86-45c7-a185-719ebfb2122d",
    "connected_account_ids":["a5d1f662-28ff-4215-9bdd-d735cdb5f8d7"],
    "type": "own",
    "name": "Account PartnerCo FR"
    "holder_name": "PartnerCo SAS",
    "account_number": "FR7601234567891127967100082",
    "bank_code": "YOURBICXXX",
    "holder_address": {
        "line_1": "1, rue de la Bourse",
        "line_2": "",
        "postal_code": "59000",
        "region_state": "",
        "city": "Lille",
        "country": "FR"
    },
}

Create a payment order using an internal account

To create a payment order using an internal account, use its ID in the originating_account_id body parameter of your Create payment order API request. The originating account data will be populated with the related external account details. Creating a internal account and using its ID simplifies your API requests as well as enables you to filter payment orders by internal account or account holder.

curl --request POST \
     --url https://sandbox.numeral.io/v1/expected_payments \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "connected_account_id": "711b414e-2d31-11ed-a261-0242ac120002",
  "direction": "credit",
  "amount_from": 1000,
  "amount_to": 1000,
  "currency": "EUR",
  "start_date": "2022-09-05",
  "end_date": "2022-09-10",
  "internal_account_id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
	"external_account_id": "ff3f23d6-0585-455d-aa80-05ebe95ff542",
  "description": "Subscription 11eda261",
}