Account POST API Documentation

Purpose

This API creates a new customer account using basic information such as name, display name, and email address. Optional fields like portal access and payment methods can also be included.

Use Case

Used when onboarding a new customer or account through the admin panel, CRM, or integration service. The API creates a new entity in the system with a unique identifier and default settings.

Path Parameters

No path parameters required for this endpoint.

Query Parameters

No query parameters required for this endpoint.

Request Body

                JSON
              

                      {
  "account": {
    "name": "ACCOUNT_NAME",
    "display_name": "DISPLAY_NAME",
    "email_address": "EMAIL_ADDRESS"
    // Optional:
    // "grant_portal_access": "BOOLEAN_STRING",
    // "payment_methods": [
    //   {
    //     "processor_type": "PROCESSOR_TYPE",
    //     "default": "BOOLEAN_STRING",
    //     "payment_processor": "PROCESSOR_NAME",
    //     "card_type": "CARD_TYPE",
    //     "token": "CARD_TOKEN",
    //     "card_number": "XXXX",
    //     "expiry_month": "MM",
    //     "expiry_year": "YYYY",
    //     "reference": "REFERENCE_TEXT",
    //     "additional_fields": {
    //       "host_ip": "HOST_IP"
    //     }
    //   }
    // ]
  }
}

                    

                JSON
              

                      {
  "account": {
    "status": "ACCOUNT_STATUS",
    "id": "ACCOUNT_ID",
    "name": "ACCOUNT_NAME",
    "display_name": "DISPLAY_NAME",
    "description": "",
    "invoice_parent_account": "BOOLEAN_STRING",
    "type": "CUSTOMER",
    "email_address": "EMAIL_ADDRESS",
    "user_team": {},
    "image_uri": "",
    "custom_forms": {
      "uuid": "FORM_UUID",
      "name": "FORM_NAME"
    },
    "currency": {
      "uuid": "CURRENCY_UUID",
      "name": "CURRENCY_NAME",
      "link": "CURRENCY_LINK"
    },
    "time_zone": {
      "uuid": "TIMEZONE_UUID",
      "name": "TIMEZONE_NAME",
      "link": "TIMEZONE_LINK"
    },
    "grant_portal_access": "BOOLEAN_STRING",
    "tax": {},
    "accounting_code": {},
    "communication_preference": "",
    "addresses": [],
    "website": "",
    "linkedin": "",
    "twitter": "",
    "facebook": "",
    "kpis": {},
    "created_by": "CREATOR_NAME",
    "created_on": "CREATED_TIMESTAMP",
    "last_updated_by": "",
    "last_updated_on": "",
    "uuid": "ACCOUNT_UUID",
    "version": "VERSION",
    "custom_attributes": [],
    "custom_objects": [],
    "billing_preferences": {
      "communication_profile": "COMM_PROFILE",
      "invoice_mode": "INVOICE_MODE",
      "invoice_term": "INVOICE_TERM",
      "billing_period": "BILLING_PERIOD",
      "billing_start_date": "START_DATE",
      "billing_start_day_of_month": "START_DAY",
      "charging_and_billing_alignment": "BOOLEAN_STRING",
      "payment_processor": "PROCESSOR_NAME",
      "payment_mode": "PAYMENT_MODE",
      "payment_term": "PAYMENT_TERM",
      "payment_term_alignment": "TERM_ALIGNMENT"
    },
    "contacts": [],
    "payment_methods": [
      {
        "processor_type": "PROCESSOR_TYPE",
        "status": "",
        "default": "BOOLEAN_STRING",
        "processor": {},
        "reference": "",
        "payment_count": "",
        "last_used_on": "",
        "created_by": "",
        "created_on": "",
        "last_updated_by": "",
        "last_updated_on": "",
        "uuid": "",
        "version": "",
        "use_for_specified_orders": "BOOLEAN_STRING",
        "specified_orders": ""
      }
    ]
  }
}

                    

Purpose

This API allows multiple address records to be added to an existing account. Addresses may include structured fields like street information, city, state, country, postal code, and default billing/shipping flags.

Use Case

Used when registering one or more physical or mailing addresses for a customer account during onboarding or profile updates. These addresses may later be used for invoicing, shipping, or location-based logic.

Path Parameters

Parameter	Type	Description
id	String	Unique identifier of the account.

Query Parameters

No query parameters required for this endpoint.

Request Body

                JSON
              

                      {
  "account": {
    "addresses": [
      {
        "address_line_1": "ADDRESS_LINE_1",
        "address_line_2": "ADDRESS_LINE_2",
        "address_line_3": "ADDRESS_LINE_3",
        "address_line_4": "ADDRESS_LINE_4",
        "address_line_5": "ADDRESS_LINE_5",
        "post_code": "POST_CODE",
        "city": "CITY",
        "state": "STATE",
        "country": "COUNTRY"
        // "default_billing": "BOOLEAN_STRING",
        // "default_shipping": "BOOLEAN_STRING"
      },
      {
        "address_line_1": "ADDRESS_LINE_1",
        "address_line_2": "ADDRESS_LINE_2",
        "address_line_3": "ADDRESS_LINE_3",
        "address_line_4": "ADDRESS_LINE_4",
        "address_line_5": "ADDRESS_LINE_5",
        "post_code": "POST_CODE",
        "city": "CITY",
        "state": "STATE",
        "country": "COUNTRY"
        // "default_billing": "BOOLEAN_STRING",
        // "default_shipping": "BOOLEAN_STRING"
      }
    ]
  }
}

                    

Field	Type	Description
address_line_1-5	String	Address lines detailing location.
post_code	String	Postal or ZIP code of the address.
city	String	City where the address is located.
state	String	State or province.
country	String	Country name.
default_billing	String	(Optional) Flag to mark this address for billing.
default_shipping	String	(Optional) Flag to mark this address for shipping.

Response

Returns the list of addresses that have been successfully created for the specified account. Each address includes its uuid for future identification or modification.

                JSON
              

                      {
  "account": {
    "id": "ACCOUNT_ID",
    "addresses": [
      {
        "address_line_1": "ADDRESS_LINE_1",
        "address_line_2": "ADDRESS_LINE_2",
        "address_line_3": "ADDRESS_LINE_3",
        "address_line_4": "ADDRESS_LINE_4",
        "address_line_5": "ADDRESS_LINE_5",
        "post_code": "POST_CODE",
        "city": "CITY",
        "state": "STATE",
        "country": "COUNTRY",
        "default_billing": "BOOLEAN_STRING",
        "default_shipping": "BOOLEAN_STRING",
        "uuid": "ADDRESS_UUID"
      }
    ]
  }
}

                    

Field	Type	Description
id	String	Account ID to which addresses are attached.
addresses	Array	List of address objects.
address_line_1-5	String	Address components.
post_code	String	ZIP or postal code.
city	String	City name.
state	String	State name.
country	String	Country name.
default_billing	String	Indicates if this is the billing address.
default_shipping	String	Indicates if this is the shipping address.
uuid	UUID	Unique identifier for the address record.

Purpose

This API is used to create a new payment method and associate it with a specific account. It supports two major groups of payment types: non-card payment methods such as Cash, Cheque, and Bank Deposit (categorized as OTHER processor type), and card-based payment methods (categorized as DIRECT_CREDIT). The request structure varies slightly between the two groups depending on the payment processor and required details.

Use Case

This endpoint is used during account setup or billing configuration to register payment options that will later be used for invoices or transactions. For non-card methods such as Cash, Cheque, and Bank Deposit, only minimal details like the processor name and a reference label are required. These are ideal for manual/offline payments. For card-based methods, additional information is needed including card number, expiry details, token, and processor, allowing for automated payments via integrated gateways like "bitmascot secure pay". The endpoint supports assigning default payment status and capturing tracking metadata such as creation timestamps and versioning.

Path Parameter

Parameter	Type	Description
account_id	String	The unique identifier of the account to which the payment method will be added.

Query Parameters

No query parameters required for this endpoint.

Request Body

The request body must include a wrapper for the account.payment_method object. It varies depending on the payment method type. For , the non card payment method body contains processor type, processor name, default flag, and reference. For , the card payment method body also includes card details, tokens, and optionally IP address for verification.

                 OTHER payment Processor(Cheque,Card,Bank Deposit)
              

                DIRECT_CREDIT payment type (Card)
              

                      {
    "account": {
        "payment_method": {
            "processor_type": "PAYMENT_TYPE_OTHER",
            "default": "BOOLEAN_TRUE",
            "payment_processor": "PAYMENT_PROCESSOR_CHEQUE",
            "reference": "PAYMENT_REFERENCE"
        }
    }
}
                    

                      {
    "account": {
        "payment_method": {
            "processor_type": "PAYMENT_TYPE_DIRECT_CREDIT",
            "default": "BOOLEAN_TRUE",
            "payment_processor": "PAYMENT_PROCESSOR_SECUREPAY",
            "card_type": "CARD_TYPE_VISA",
            "token": "PAYMENT_TOKEN",
            "card_number": "MASKED_CARD_NUMBER",
            "expiry_month": "CARD_EXPIRY_MONTH",
            "expiry_year": "CARD_EXPIRY_YEAR",
            "reference": "PAYMENT_REFERENCE",
            "additional_fields": {
                "host_ip": "CLIENT_IP_ADDRESS"
            }
        }
    }
}
                    

Non-Card Payment: Cash, Cheque, Bank Deposit

Attribute	Type	Description
processor_type	String	Must be "OTHER" for non-card methods.
default	String	"true" or "false" to set as default.
payment_processor	String	Name of the processor (e.g., "Cheque").
reference	String	A unique reference string for identification.

Card-Based Payment

Attribute	Type	Description
processor_type	String	Must be "DIRECT_CREDIT" for card payments.
default	String	"true" or "false" to mark as default.
payment_processor	String	Name of the card processor .
card_type	String	Type of the card .
token	String	Encrypted or secure token for the card.
card_number	String	Full card number (used for registration).
expiry_month	String	Expiry month of the card .
expiry_year	String	Expiry year of the card .
reference	String	A unique reference for the payment method.
additional_fields.host_ip	String	IP address of the host initiating the request.

Response

The API response includes the full details of the registered payment method under the account, including processor name, UUID, and configuration metadata. For non-card methods, response fields confirm processor type, name, reference, status, timestamps, and UUID. For card-based methods, the response includes masked card details, processor metadata, and versioning, along with encrypted CVV or token info. Both response types help confirm successful creation and can be used for auditing or displaying in admin panels.

                OTHER payment Processor(Cheque,Card,Bank Deposit)
              

                DIRECT_CREDIT payment type (Card)
              

                      {
    "account": {
        "payment_method": {
            "processor_type": "PAYMENT_TYPE_OTHER",
            "status": "PAYMENT_STATUS_ACTIVE",
            "default": "BOOLEAN_TRUE",
            "processor": {
                "uuid": "PAYMENT_PROCESSOR_UUID",
                "name": "PAYMENT_PROCESSOR_CHEQUE",
                "link": "PAYMENT_PROCESSOR_API_URL"
            },
            "reference": "PAYMENT_REFERENCE",
            "payment_count": "0",
            "last_used_on": "",
            "created_by": "SYSTEM_USER",
            "created_on": "TIMESTAMP_CREATED",
            "last_updated_by": "",
            "last_updated_on": "",
            "uuid": "PAYMENT_METHOD_UUID",
            "version": "1",
            "use_for_specified_orders": "BOOLEAN_FALSE",
            "specified_orders": ""
        },
        "id": "ACCOUNT_ID"
    }
}
                    

                      {
    "account": {
        "payment_method": {
            "processor_type": "PAYMENT_TYPE_DIRECT_CREDIT",
            "status": "PAYMENT_STATUS_ACTIVE",
            "default": "BOOLEAN_TRUE",
            "processor": {
                "uuid": "PAYMENT_PROCESSOR_UUID",
                "name": "PAYMENT_PROCESSOR_SECUREPAY",
                "link": "PAYMENT_PROCESSOR_API_URL"
            },
            "card_type": "CARD_TYPE_VISA",
            "token": "PAYMENT_TOKEN",
            "card_number": "MASKED_CARD_NUMBER",
            "expiry_month": "CARD_EXPIRY_MONTH",
            "expiry_year": "CARD_EXPIRY_YEAR",
            "card_cvv": "MASKED_CVV",
            "name_on_card": "",
            "reference": "PAYMENT_REFERENCE",
            "payment_count": "0",
            "last_used_on": "",
            "last_used_result": "",
            "error_count_since_last_success": "",
            "created_by": "SYSTEM_USER",
            "created_on": "TIMESTAMP_CREATED",
            "last_updated_by": "",
            "last_updated_on": "",
            "uuid": "PAYMENT_METHOD_UUID",
            "version": "1",
            "use_for_specified_orders": "BOOLEAN_FALSE",
            "specified_orders": ""
        },
        "id": "ACCOUNT_ID"
    }
}
                    

Non-Card Payment: Cash, Cheque, Bank Deposit

Attribute	Type	Description
processor_type	String	Always "OTHER" for these methods.
status	String	Status of the payment method ("ACTIVE").
default	String	Whether the method is default.
processor.name	String	Name of the processor used ("Cheque").
processor.uuid	String	Unique processor identifier.
reference	String	Custom reference tag for the method.
payment_count	String	Count of transactions using this method.
created_by	String	Creator of the payment method (e.g., "Nabil").
created_on	String	Timestamp of creation.
uuid	String	Unique identifier of the payment method.
version	String	Version of the payment configuration.

Card-Based Payment

Attribute	Type	Description
processor_type	String	Always "DIRECT_CREDIT" for card payments.
status	String	Status of the payment method ("ACTIVE").
default	String	Indicates if the method is default.
processor.name	String	Name of the payment gateway.
processor.uuid	String	Unique identifier for the processor.
card_type	String	Card type like VISA or MASTERCARD.
card_number	String	Masked card number .
token	String	Encrypted card token.
expiry_month, expiry_year	String	Expiry details for the card.
card_cvv	String	Masked CVV shown as "XXX".
reference	String	Unique reference string used for this method.
created_by	String	User who added the method.
created_on	String	Timestamp of creation.
uuid	String	Unique identifier of the payment method.
version	String	Configuration version of the method.

Purpose

This API endpoint upload an image to a specific account, effectively assigning a profile photo to that account.

Use Case

This endpoint is used when creating or editing an account where a profile image is needed for visual identification in the UI .The uploaded image is stored and linked to the account, allowing it to be retrieved and displayed later. This operation replaces any existing image with the new one. This helps improve the visual context and branding associated with the account throughout the system.

Path Parameter

Parameter	Type	Description
account_id	String	The unique identifier of the account

Query Parameters

No query parameters required for this endpoint.

Request Body

The request body must be sent as form-data with a key named and the image file as its value. Supported file types include JPG, JPEG, PNG, etc. Only one image file is accepted per request.

Attribute	Type	Description
image	File	The image file to upload as profile photo

Response

The API successfully returns a JSON object containing the full URL of the uploaded image in the image_uri field. This URL can be used to display the account's profile picture across the application. If an image already exists for the account, it will be replaced with the newly uploaded one.

                JSON
              

                      {
    "account": {
        "image_uri": "RESOURCE_BASE_URL/RESOURCE_PATH/ACCOUNT_IMAGE_ID.jpeg"
    }
}
                    

Attribute	Type	Description
image_uri	String	The URI of the uploaded image file linked to the account

Purpose

This endpoint is used to add a new note to a specific account. The note content is mandatory, while file attachments are optional. Files can be used to provide supporting documents or images related to the note.

Use Case

This API is used to submit notes tied to an account for recordkeeping, support communication, or customer management purposes. While the note field is mandatory to describe the content of the message or update, the file field can optionally include attachments such as screenshots, documents, or images that support the note's context.

Path Parameters

Parameter	Type	Description
account_id	String	The unique identifier of the account

Query Parameters

No query parameters required for this endpoint.

Request Body

The request body must be sent as form-data with the note and file as its value. Supported file types include JPG, TXT,CSV etc.

Key	Type	Description
note	Text	The note content in plain text or rich text (HTML supported)
file	File	Optional file(s) to attach with the note

Response

The response returns the UUID of the newly created note under the specified account. This UUID can later be used to retrieve, update, or delete the note if needed. If a file was included, it is linked with the note and accessible via note file-related APIs.

                JSON
              

                      {
    "account": {
        "notes": {
            "uuid": "NOTE_UUID"
        }
    }
}
                    

Attribute	Type	Description
account.notes.uuid	String	UUID of the newly created note

Purpose

This API upload and attach one or more files to an already created note under a specific account. A maximum of 8 files can be attached to a single note.

Use Case

This API is used when an existing note associated with an account requires additional documentation or media. Users can attach supporting files such as images, documents, or spreadsheets to a note. This is especially helpful in customer communication history, documentation, and audit purposes. If more than 8 files are attempted to be uploaded, the API will return an error indicating the limit.

Path Parameters

Parameter	Type	Description
id	String	Unique identifier of the account
uuid	String	UUID of the note to which files are being added

Query Parameters

No query parameters required for this endpoint.

Request Body

The request body must be sent as form-data with a file as its value. Supported file types include JPG, PNG, TXT,CSV etc.

Attribute	Type	Description
file	File	One or more files to be uploaded

Response

The API successfully returns a list of file names that were successfully attached to the note. If the number of uploaded files exceeds 8, an error message is returned indicating the violation of the file limit.

                JSON
              

                      {
    "account": {
        "notes": {
            "files": [
                {
                    "name": "SPREADSHEET_FILE.xlsx"
                },
                {
                    "name": "ORDER_DOCUMENT.pdf"
                },
                {
                    "name": "SPREADSHEET_FILE.xlsx"
                },
                {
                    "name": "ORDER_DOCUMENT.pdf"
                },
                {
                    "name": "IMAGE_FILE.jpg"
                },
                {
                    "name": "IMAGE_FILE.jpg"
                },
                {
                    "name": "IMAGE_FILE.jpg"
                },
                {
                    "name": "ORDER_DOCUMENT.pdf"
                }
            ]
        }
    }
}
                    

Attribute	Type	Description
account.notes.files	Array	List of successfully added files
name	String	File name added to the note

Purpose

This API is cancel or deactivate a specific account. Once an account is cancelled, no operational or functional actions (such as billing, orders, or updates) can be performed on it. The cancellation is effective from the specified date.

Use Case

This API is used when an account needs to be deactivated from the system, either due to service termination, customer offboarding, or administrative decision. The client can set the effective date from which the cancellation becomes active. Once the account is cancelled, its resources and features are locked and no further interactions (like adding notes, making payments, or updating data) are allowed.

Path Parameters

Parameter	Type	Description
account_id	String	The unique identifier of the account

Query Parameters

No query parameters required for this endpoint.

Request Body

The request body must include the "effective_date"to specify when the cancellation should take effect.

                JSON
              

                      {
    "account": {
        "effective_date": "EFFECTIVE_DATE"
    }
}
                    

Attribute	Type	Description
effective_date	String	Date when the account cancellation should take effect (format: YYYY-MM-DD)

Response

The response successfully returns a unique event UUID representing the cancellation activity. This UUID can be used for tracking or audit purposes.

                JSON
              
                      {
    "event_uuid": "EVENT_UUID"
}

Field	Type	Description
event_uuid	String	Unique identifier of the cancellation event

Purpose

This API reactivate a previously cancelled or deactivated account by providing its unique identifier and the date from which reactivation should be effective. It ensures that the account is brought back into an active state, restoring its operational capability within the system.

Use Case

This API is used when an account needs to be reinstated, either due to customer re-engagement, service renewal, or correction of a cancellation. For instance, if a customer returns within a grace period or if a business reverses a termination decision, this endpoint allows reactivation to be scheduled using an effective_date. It ensures that the account regains its functionality in accordance with system rules and audit tracking.

Path Parameters

Parameter	Type	Description
account_id	String	Unique identifier of the accoun

Query Parameters

No query parameters required for this endpoint.

Request Body

The request must include the effective date when the account should be reactivated.

                JSON
              

                      {
    "account": {
        "effective_date": "EFFECTIVE_DATE"
    }
}
                    

Attribute	Type	Description
effective_date	String	Date (YYYY-MM-DD) the reactivation starts

Response

Upon successful reactivation, the response returns an event_uuid which uniquely identifies the reactivation event. This UUID can be used for auditing or integration with downstream workflows.

                JSON
              
                      {
    "event_uuid": "EVENT_UUID"
}

Create New Account (Basic Information): /account

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Add Addresses to Account: /accounts/{id}/addresses

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Create Payment Method: /accounts/{account_id}/payment-methods

Purpose

Use Case

Path Parameter

Query Parameters

Request Body

Non-Card Payment: Cash, Cheque, Bank Deposit

Card-Based Payment

Response

Upload Account Profile Image : /accounts/{account_id}/image

Purpose

Use Case

Path Parameter

Query Parameters

Request Body

Response

Add Note to Account: /accounts/{account_id}/notes

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Add Files to an Existing Account Note : /accounts/{account_id}/notes/{note_uuid}/files

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Cancel an Account : /accounts/{account_id}/cancel

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Reactivate an Account: /accounts/{account_id}/reactivate

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response