Create Account

The CreateAccount API facilitates the creation of new account records in OCS.io, enabling customization to meet specific operational requirements.

API Overview

Fields Required for Account Creation

The following table lists and describes the fields required to create an account through the CreateAccount API:

Field	Description
accountProfile	Profile of the Account to be used for creation. Account Profile must be configured.
externalId	External ID of the Account.
accountType	Type of the Account to be used for creation. Account Type must be configured.
customer	ID (Ref ID / External ID) of the Customer.
accountSegment	Segment of the Account. Account Segment must be configured.
billCycle	BillCycle to be assigned. BillCycle must be configured.
billingDay	Day of the Billing in case Billing Cycle per Account is Individual.
billingMonth	Month of the Billing in case Billing Cycle per Account is Individual.
billingYear	Year of the Billing in case Billing Cycle per Account is Individual.
currency	Currency ISO 4217 code (3 letters). Currency must be configured.
state	Initial State of the Account.
paymentResponsible	Indicates whether the Account is Payment Responsible.
testAccount	Indicates whether the Account is a Test Account.
customName	Custom Account name.
customAttributes	Custom attributes, Key - Value (String) Map.
parent	ID (Ref ID / External ID) of the Parent Account.
taxExemption	Indicates whether the Account is subject to Tax exemption.
taxResidence	Tax Residence or the Payment Responsible Account.

Field

Description

accountProfile

Profile of the Account to be used for creation. Account Profile must be configured.

externalId

External ID of the Account.

accountType

Type of the Account to be used for creation. Account Type must be configured.

customer

ID (Ref ID / External ID) of the Customer.

accountSegment

Segment of the Account. Account Segment must be configured.

billCycle

BillCycle to be assigned. BillCycle must be configured.

billingDay

Day of the Billing in case Billing Cycle per Account is Individual.

billingMonth

Month of the Billing in case Billing Cycle per Account is Individual.

billingYear

Year of the Billing in case Billing Cycle per Account is Individual.

currency

Currency ISO 4217 code (3 letters). Currency must be configured.

state

Initial State of the Account.

paymentResponsible

Indicates whether the Account is Payment Responsible.

testAccount

Indicates whether the Account is a Test Account.

customName

Custom Account name.

customAttributes

Custom attributes, Key - Value (String) Map.

parent

ID (Ref ID / External ID) of the Parent Account.

taxExemption

Indicates whether the Account is subject to Tax exemption.

taxResidence

Tax Residence or the Payment Responsible Account.

Detailed API documentation and endpoint specifics are available here.

Request Validations

The following validations are performed when creating an account:

If Account Profile is provided in the request, it must be configured in the system.
If Account Segment is provided in the request, it must be configured in the system.
Currency must be configured in the system.
State Reason must be configured in the system for given State.
If Pending State is provided in the request, it will be ignored and Account will be created without Pending.
If Account Profile is not provided in the request, attributes Account Type, Currency, State and State Reason must be provided in the request.
If Customer is not provided in the request, Account Profile must be provided in the request.
If External ID is provided in the request, it must be unique and must not be already assigned to another Account even in Deactivated State.
If Customer is provided in the request, it must be already created in the system and must not be in Deactivated State.
If Parent Account is provided in the request, it must be already created in the system and must not be in Deactivated State.
If Parent Account is not provided in the request, Account Type must be Payment Responsible.

Create Account Examples

1. Create Account by Profile

Creating an account in OCS.io is most straightforward when using a pre-configured account profile. For more details on setting up account profiles, see the configuration guide here.

Use the following request’s body to create an Account by Profile:

{
  "requestId": "{{$guid}}",
  "externalId": "account_external_id",
  "accountProfile": "paymentResponsible"
}

The outcome of the API call is as follows:

A new account with the external ID account_external_id is created using the configured paymentResponsible profile.

2. Create Account by Profile with Additional Attributes

To enhance a basic account profile with additional attributes, such as a Custom Name, you can modify the initial request as shown below:

{
  "requestId": "{{$guid}}",
  "externalId": "account_external_id",
  "accountProfile": "paymentResponsible",
  "customAttributes": {
    "key1": "Value 1",
    "key2": "Value 2"
  },
  "customName": "Demo Account"
}

The outcome of the API call is as follows:

A new account with the external ID account_external_id is created using the configured paymentResponsible profile.
The custom attributes key1: Value 1 and key2: Value 2 are set for the account.
The custom name of the account is set to Demo Account.

3. Create Account by Providing Mandatory Attributes

The last option is to create an account by providing all mandatory attributes:

Use the following request’s body to create an Account by providing all attributes:

{
  "requestId": "{{$guid}}",
  "customer": {
    "externalId": "customer_external_id"
  },
  "externalId": "account_external_id",
  "accountSegment": "topPayers",
  "customAttributes": {
    "key1": "Value 1",
    "key2": "Value 2"
  },
  "state": {
    "state": "ACTIVE",
    "stateReason": "dfltActive"
  },
  "customName": "Demo Account"
}

The outcome of the API call is as follows:

A new account, with the external ID account_external_id is created under the customer identified by external ID customer_external_id.
Configured Segment topPayers is assigned to the account.
Custom Attributes key1: Value 1 and key2: Value 2 are set to the account.
Custom Name Demo Account is set as the account’s name.
The account’s state is set to ACTIVE with the reason dfltActive.