Create a Transaction - Bookeeping.ai Docs

POST

transactions

Create a Transaction

curl --request POST \
  --url https://api.bookeeping.ai/public-api/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "totalAmount": 123,
  "transactionDate": "2023-11-07T05:31:56Z",
  "paymentMethod": {},
  "isReconciled": true,
  "entries": [
    {
      "id": "<string>",
      "amount": 123,
      "type": "DEBIT",
      "category": "<string>",
      "parentCategory": "INCOME",
      "isMain": true,
      "note": "<string>"
    }
  ],
  "refNo": "<string>",
  "currency": "<string>",
  "counterParty": "<string>",
  "account": "<string>"
}
'

{
  "message": "<string>",
  "metaData": {
    "warnings": [
      "<string>"
    ]
  },
  "data": {
    "transaction": {
      "_id": "<string>",
      "projectId": "<string>",
      "currency": "<string>",
      "totalAmount": 123,
      "transactionDate": "2023-11-07T05:31:56Z",
      "paymentMethod": {},
      "source": {},
      "isReconciled": true,
      "nonProfitAllocations": [
        {
          "percentage": 123,
          "program": {
            "_id": "<string>",
            "name": "<string>",
            "status": "PLANNING",
            "createdAt": "2023-11-07T05:31:56Z",
            "updatedAt": "2023-11-07T05:31:56Z",
            "hexColor": "<string>"
          },
          "grant": {
            "_id": "<string>",
            "name": "<string>",
            "status": "ACTIVE",
            "createdAt": "2023-11-07T05:31:56Z",
            "updatedAt": "2023-11-07T05:31:56Z",
            "hexColor": "<string>",
            "funder": {
              "_id": "<string>",
              "accountName": "<string>",
              "accountNumber": "<string>",
              "email": "jsmith@example.com",
              "phone": "<string>",
              "type": "customer"
            }
          },
          "note": "<string>"
        }
      ],
      "entries": [
        {
          "id": "<string>",
          "amount": 123,
          "type": "DEBIT",
          "parentCategory": "INCOME",
          "category": {
            "_id": "<string>",
            "name": "<string>",
            "emoji": "<string>",
            "parentCategory": "INCOME",
            "number": "<string>",
            "group": "<string>"
          },
          "isMain": true,
          "note": "<string>"
        }
      ],
      "classes": [
        {
          "_id": "<string>",
          "name": "<string>",
          "description": "<string>",
          "emoji": "<string>",
          "color": "<string>"
        }
      ],
      "attachmentsIds": [
        "<string>"
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "refNo": "<string>",
      "originalAmount": 123,
      "originalCurrency": "<string>",
      "counterParty": {
        "_id": "<string>",
        "accountName": "<string>",
        "accountNumber": "<string>",
        "email": "jsmith@example.com",
        "phone": "<string>",
        "type": "customer"
      },
      "account": {
        "_id": "<string>",
        "accountType": "Depository",
        "accountName": "<string>",
        "accountNumber": "<string>"
      },
      "nonProfitGrantId": "<string>",
      "attachedTransactionId": "<string>"
    },
    "action": "CREATED"
  }
}

Authorizations

Authorization

string

header

required

API key for authentication. Get your key from the Dashboard > Settings > API Access.

Query Parameters

force

string

required

Force create the transaction if it already exists

Body

application/json

totalAmount

number

required

The total amount of the transaction. Same as the sum of the Total Credit = Total Debit.

transactionDate

string<date-time>

required

The transaction date of the transaction

paymentMethod

object

required

The payment method of the transaction

isReconciled

boolean

required

The reconciliation status of the transaction

entries

object[]

required

The entries of the transaction

Show child attributes

entries.id

string

required

The id of the entry

entries.amount

number

required

The amount of the entry

entries.type

enum<string>

required

The type of the entry

Available options:

DEBIT,

CREDIT

entries.category

string

required

The category id of the entry

entries.parentCategory

enum<string> | null

Available options:

INCOME,

OTHER_INCOME,

SALES,

EXPENSE,

DEPRECIATION,

COST_OF_GOODS_SOLD,

OTHER_EXPENSE,

OVERHEAD,

CURRENT_ASSET,

FIXED_ASSET,

INVENTORY,

NON_CURRENT_ASSET,

PREPAYMENT,

LIABILITY,

CURRENT_LIABILITY,

NON_CURRENT_LIABILITY,

TAX_PAYABLE,

TAX,

EQUITY,

OTHER

entries.isMain

boolean | null

entries.note

string | null

refNo

string | null

currency

string | null

counterParty

string | null

The counter party id of the transaction. Expected to be a valid object id like 666666666666666666666666

account

string | null

The account id of the transaction. Expected to be a valid object id like 666666666666666666666666

Response

Create a Transaction executed successfully

message

string

Success message

metaData

object

Show child attributes

metaData.warnings

string[]

Any validation warnings

data

object

The response of the transaction creation. CREATED if transaction created successfully, ALREADY_EXISTS if similar transaction already exists, send query params force=true to override

Show child attributes

data.transaction

object

required

Show child attributes

data.transaction._id

string

required

The id of the transaction

data.transaction.projectId

string

required

The project id of the transaction

data.transaction.currency

string

required

The currency of the transaction

data.transaction.totalAmount

number

required

The total amount of the transaction. Same as the sum of the Total Credit = Total Debit.

data.transaction.transactionDate

string<date-time>

required

The transaction date of the transaction

data.transaction.paymentMethod

object

required

The payment method of the transaction

data.transaction.source

object

required

The source of the transaction

data.transaction.isReconciled

boolean

required

The reconciliation status of the transaction

data.transaction.nonProfitAllocations

object[]

required

The non profit allocations of the transaction

Show child attributes

data.transaction.nonProfitAllocations.percentage

number

required

The percentage of the non profit allocation

data.transaction.nonProfitAllocations.program

object

Show child attributes

data.transaction.nonProfitAllocations.program._id

string

required

The id of the program

data.transaction.nonProfitAllocations.program.name

string

required

The name of the program

data.transaction.nonProfitAllocations.program.status

enum<string>

required

The status of the program

Available options:

PLANNING,

ACTIVE,

COMPLETED,

CANCELLED

data.transaction.nonProfitAllocations.program.createdAt

string<date-time>

required

The created at of the program

data.transaction.nonProfitAllocations.program.updatedAt

string<date-time>

required

The updated at of the program

data.transaction.nonProfitAllocations.program.hexColor

string | null

data.transaction.nonProfitAllocations.grant

object

Show child attributes

data.transaction.nonProfitAllocations.grant._id

string

required

The id of the grant

data.transaction.nonProfitAllocations.grant.name

string

required

The name of the grant

data.transaction.nonProfitAllocations.grant.status

enum<string>

required

The status of the grant

Available options:

ACTIVE,

COMPLETED,

CANCELLED

data.transaction.nonProfitAllocations.grant.createdAt

string<date-time>

required

The created at of the grant

data.transaction.nonProfitAllocations.grant.updatedAt

string<date-time>

required

The updated at of the grant

data.transaction.nonProfitAllocations.grant.hexColor

string | null

data.transaction.nonProfitAllocations.grant.funder

object

Show child attributes

data.transaction.nonProfitAllocations.grant.funder._id

string

required

The id of the counterparty

data.transaction.nonProfitAllocations.grant.funder.accountName

string | null

data.transaction.nonProfitAllocations.grant.funder.accountNumber

string | null

data.transaction.nonProfitAllocations.grant.funder.email

string<email> | null

data.transaction.nonProfitAllocations.grant.funder.phone

string | null

data.transaction.nonProfitAllocations.grant.funder.type

enum<string> | null

Available options:

customer,

vendor,

both

data.transaction.nonProfitAllocations.note

string | null

data.transaction.entries

object[]

required

The entries of the transaction

Show child attributes

data.transaction.entries.id

string

required

The id of the entry

data.transaction.entries.amount

number

required

The amount of the entry

data.transaction.entries.type

enum<string>

required

The type of the entry

Available options:

DEBIT,

CREDIT

data.transaction.entries.parentCategory

enum<string> | null

Available options:

INCOME,

OTHER_INCOME,

SALES,

EXPENSE,

DEPRECIATION,

COST_OF_GOODS_SOLD,

OTHER_EXPENSE,

OVERHEAD,

CURRENT_ASSET,

FIXED_ASSET,

INVENTORY,

NON_CURRENT_ASSET,

PREPAYMENT,

LIABILITY,

CURRENT_LIABILITY,

NON_CURRENT_LIABILITY,

TAX_PAYABLE,

TAX,

EQUITY,

OTHER

data.transaction.entries.category

object

Show child attributes

data.transaction.entries.category._id

string

required

The id of the category

data.transaction.entries.category.name

string

required

The name of the category

data.transaction.entries.category.emoji

string | null

data.transaction.entries.category.parentCategory

enum<string> | null

Available options:

INCOME,

OTHER_INCOME,

SALES,

EXPENSE,

DEPRECIATION,

COST_OF_GOODS_SOLD,

OTHER_EXPENSE,

OVERHEAD,

CURRENT_ASSET,

FIXED_ASSET,

INVENTORY,

NON_CURRENT_ASSET,

PREPAYMENT,

LIABILITY,

CURRENT_LIABILITY,

NON_CURRENT_LIABILITY,

TAX_PAYABLE,

TAX,

EQUITY,

OTHER

data.transaction.entries.category.number

string | null

data.transaction.entries.category.group

string | null

data.transaction.entries.isMain

boolean | null

data.transaction.entries.note

string | null

data.transaction.classes

object[]

required

The classes of the transaction

Show child attributes

data.transaction.classes._id

string

required

The id of the class

data.transaction.classes.name

string

required

The name of the class

data.transaction.classes.description

string | null

data.transaction.classes.emoji

string | null

data.transaction.classes.color

string | null

data.transaction.attachmentsIds

string[]

required

The attachments ids of the transaction

data.transaction.createdAt

string<date-time>

required

The created at of the transaction

data.transaction.updatedAt

string<date-time>

required

The updated at of the transaction

data.transaction.refNo

string | null

data.transaction.originalAmount

number | null

data.transaction.originalCurrency

string | null

data.transaction.counterParty

object

Show child attributes

data.transaction.counterParty._id

string

required

The id of the counterparty

data.transaction.counterParty.accountName

string | null

data.transaction.counterParty.accountNumber

string | null

data.transaction.counterParty.email

string<email> | null

data.transaction.counterParty.phone

string | null

data.transaction.counterParty.type

enum<string> | null

Available options:

customer,

vendor,

both

data.transaction.account

object

Show child attributes

data.transaction.account._id

string

required

The id of the account

data.transaction.account.accountType

enum<string>

required

The type of the account

Available options:

Depository,

Credit,

Loan,

Investment,

Other

data.transaction.account.accountName

string | null

data.transaction.account.accountNumber

string | null

data.transaction.nonProfitGrantId

string | null

data.transaction.attachedTransactionId

string | null

data.action

enum<string>

required

The action of the transaction

Available options:

CREATED,

ALREADY_EXISTS

Get a Transaction by IDGet a Transaction by ID

⌘I

Create a Transaction

curl --request POST \
  --url https://api.bookeeping.ai/public-api/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "totalAmount": 123,
  "transactionDate": "2023-11-07T05:31:56Z",
  "paymentMethod": {},
  "isReconciled": true,
  "entries": [
    {
      "id": "<string>",
      "amount": 123,
      "type": "DEBIT",
      "category": "<string>",
      "parentCategory": "INCOME",
      "isMain": true,
      "note": "<string>"
    }
  ],
  "refNo": "<string>",
  "currency": "<string>",
  "counterParty": "<string>",
  "account": "<string>"
}
'

{
  "message": "<string>",
  "metaData": {
    "warnings": [
      "<string>"
    ]
  },
  "data": {
    "transaction": {
      "_id": "<string>",
      "projectId": "<string>",
      "currency": "<string>",
      "totalAmount": 123,
      "transactionDate": "2023-11-07T05:31:56Z",
      "paymentMethod": {},
      "source": {},
      "isReconciled": true,
      "nonProfitAllocations": [
        {
          "percentage": 123,
          "program": {
            "_id": "<string>",
            "name": "<string>",
            "status": "PLANNING",
            "createdAt": "2023-11-07T05:31:56Z",
            "updatedAt": "2023-11-07T05:31:56Z",
            "hexColor": "<string>"
          },
          "grant": {
            "_id": "<string>",
            "name": "<string>",
            "status": "ACTIVE",
            "createdAt": "2023-11-07T05:31:56Z",
            "updatedAt": "2023-11-07T05:31:56Z",
            "hexColor": "<string>",
            "funder": {
              "_id": "<string>",
              "accountName": "<string>",
              "accountNumber": "<string>",
              "email": "jsmith@example.com",
              "phone": "<string>",
              "type": "customer"
            }
          },
          "note": "<string>"
        }
      ],
      "entries": [
        {
          "id": "<string>",
          "amount": 123,
          "type": "DEBIT",
          "parentCategory": "INCOME",
          "category": {
            "_id": "<string>",
            "name": "<string>",
            "emoji": "<string>",
            "parentCategory": "INCOME",
            "number": "<string>",
            "group": "<string>"
          },
          "isMain": true,
          "note": "<string>"
        }
      ],
      "classes": [
        {
          "_id": "<string>",
          "name": "<string>",
          "description": "<string>",
          "emoji": "<string>",
          "color": "<string>"
        }
      ],
      "attachmentsIds": [
        "<string>"
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "refNo": "<string>",
      "originalAmount": 123,
      "originalCurrency": "<string>",
      "counterParty": {
        "_id": "<string>",
        "accountName": "<string>",
        "accountNumber": "<string>",
        "email": "jsmith@example.com",
        "phone": "<string>",
        "type": "customer"
      },
      "account": {
        "_id": "<string>",
        "accountType": "Depository",
        "accountName": "<string>",
        "accountNumber": "<string>"
      },
      "nonProfitGrantId": "<string>",
      "attachedTransactionId": "<string>"
    },
    "action": "CREATED"
  }
}

Routes

Authorizations

Query Parameters

Body

Response