Business Partners

Business partners are the companies and people that you work with. They can be your suppliers, customers, employees, owners or any other person/company that you interact with. Business partners are one of the most important resources in Snapbooks, and are used in journal entries, invoices, credit notes, payment lists and more.

Endpoints

Query Parameters

The GET /business-partners endpoint supports the following query parameters:

Attributes

Relationships

Statistics Object

Example Response

{
    "id": 1,
    "created_at": "2023-05-10T12:00:00Z",
    "created_by_id": 1,
    "updated_at": "2023-05-10T12:00:00Z",
    "updated_by_id": 1,
    "client_account_id": 1,
    "sequence_number": 1001,
    "name": "John Doe",
    "is_organization": false,
    "organization_id": 1245,
    "organization_number": "123456789",
    "ssn": null,
    "user_id": null,
    "address": "Street 1",
    "zip": "1234",
    "city": "City",
    "state": "State",
    "country": "NO",
    "email": "john@doe.com",
    "phone": "+4712345678",
    "is_active": true,
    "autonomy_level": null,
    "organization": {
        "id": 1245,
        "name": "ACME Corp"
    },
    "user": null,
    "bank_accounts": [
        {
            "id": 1,
            "account_number": "12345678901"
        }
    ],
    "sending_methods": {
        "ARINV": [
            {"method": "email", "value": "john@doe.com"},
            {"method": "peppol", "value": "0192:123456789"}
        ],
        "ARCRN": [
            {"method": "email", "value": "john@doe.com"}
        ]
    },
    "statistics": {
        "is_customer": true,
        "is_supplier": false,
        "is_employee": false,
        "is_owner": false,
        "balances": [
            {"account_code": "1500", "balance": 1250.00}
        ],
        "receivable_credit_days": 14,
        "payable_credit_days": null
    }
}

Deactivation Validation

When attempting to deactivate a business partner using the DELETE endpoint, the system performs validation to ensure data integrity:

• Balance Checking: The system checks if any accounting accounts with mandatory business partner dimensions have non-zero balances for this specific business partner.
• Validation Failure: If any accounts have non-zero balances, the deactivation is denied with a 400 Bad Request error.
• Error Details: The error message includes specific account codes and their balances to help identify which transactions need to be resolved.

Example Error Response

{
    "error": {
        "code": "common.validation_error",
        "message": "Cannot deactivate business partner: account 1500: 1250.00, account 2400: -500.00",
        "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
}

This validation ensures that business partners cannot be deactivated while they still have outstanding balances, maintaining the integrity of your accounting records.

Error Responses

Example Duplicate Error Response

{
    "error": {
        "code": "businesspartner.duplicate",
        "message": "Duplicate business partner: John Doe (NO)",
        "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
}

Notes

• The client_account_id must be one of the eligible client accounts for the authenticated user.
• When creating or updating a business partner, the created_by_id/updated_by_id is automatically set to the authenticated user’s ID.
• Relationships can be included by specifying them in the with parameter.
• The sequence_number is automatically assigned when creating a new business partner.
• The statistics and sending_methods relationships provide additional information about the partner’s activity and communication preferences.
• All dates are returned in ISO 8601 format.
• The DELETE endpoint deactivates the business partner (sets is_active to false) rather than permanently deleting the record.