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

Method	Endpoint	Description
GET	/business-partners	List business partners
POST	/business-partners	Create a business partner
GET	/business-partners/{id}	Get a business partner
PUT	/business-partners/{id}	Update a business partner
DELETE	/business-partners/{id}	Deactivate a business partner

Query Parameters

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

Parameter	Type	Required	Description
client_account_id	integer	Yes	Filter by client account ID. Must be one of the user’s eligible client accounts
is_organization	boolean	No	Filter by organization status
organization_id	integer	No	Filter by organization ID
user_id	integer	No	Filter by user ID
is_active	boolean	No	Filter by active status (default: true)
free_text	string	No	Search in business partner fields
page	integer	No	Page number for pagination (default: 1)
per_page	integer	No	Number of items per page (default: 100)

Attributes

Attribute	Type	Description
id	integer	The ID of the business partner
created_at	datetime	The date and time when the business partner was created
created_by_id	integer	The ID of the user that created the business partner
updated_at	datetime	The date and time when the business partner was last updated
updated_by_id	integer	The ID of the user that last updated the business partner
client_account_id	integer	The ID of the client account this partner belongs to
sequence_number	integer	The sequence number of the business partner
name	string	The name of the business partner
is_organization	boolean	Whether the business partner is an organization or not
organization_id	integer	The organization ID of the business partner
organization_number	string	The organization number of the business partner
user_id	integer	The ID of the associated user, if any
address	string	The address of the business partner
zip	string	The zip code of the business partner
city	string	The city of the business partner
state	string	The state of the business partner
country	string	The country code of the business partner
email	string	The email address of the business partner
is_active	boolean	Whether the business partner is active or not

Relationships

Relationship	Type	Description
organization	Organization	The organization of the business partner
user	User	The associated user account
bank_accounts	BankAccount	The bank accounts of the business partner
sending_methods	string[]	The methods used for sending documents to this partner
statistics	object	Statistical information about the business partner

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",
    "user_id": null,
    "address": "Street 1",
    "zip": "1234",
    "city": "City",
    "state": "State",
    "country": "NO",
    "email": "john@doe.com",
    "is_active": true,
    "organization": {
        "id": 1245,
        "name": "ACME Corp"
    },
    "user": null,
    "bank_accounts": [
        {
            "id": 1,
            "account_number": "12345678901"
        }
    ],
    "sending_methods": ["email", "peppol"],
    "statistics": {
        "total_invoices": 10,
        "open_invoices": 2
    }
}

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": "Cannot deactivate business partner: account 1500: 1250.00, account 2400: -500.00",
    "status": 400
}

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

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_relations 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.