Backend API: Manage company business units

This document describes how to manage company business units using the Backend API. A business unit represents a department, branch, or site of a company. Company users are assigned to a business unit. You can use these endpoints to build Back Office extensions, CRM and ERP integrations, and onboarding automation.

Installation

These endpoints are implemented using API Platform. To install and enable it, see Enable API Platform.

For the modules that provide the business unit endpoints and their installation instructions, see Install the Company Business Units Backend API.

Conventions

Request headers, pagination, and the filter and sort syntax are the same for every Backend API resource—see Backend API conventions. This page lists only what is specific to business units.

Retrieve business units

To retrieve a paginated collection of business units, send the request:

GET /company-business-units

Request

name is the only filterable property; a filter addressing any other property returns 400 with the error code 1215.

You can combine q with the name filter. The collection then contains only the business units that match both criteria.

Response

{
    "links": {
        "self": "https://glue-backend.mysprykershop.com/company-business-units",
        "first": "https://glue-backend.mysprykershop.com/company-business-units?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/company-business-units?page[limit]=10&page[offset]=10",
        "next": "https://glue-backend.mysprykershop.com/company-business-units?page[limit]=10&page[offset]=10"
    },
    "meta": {
        "pagination": {
            "numFound": 14,
            "currentPage": 1,
            "maxPage": 2,
            "currentItemsPerPage": 10
        }
    },
    "data": [
        {
            "type": "company-business-units",
            "id": "4d1b3f9a-9d4c-5c1e-9f6b-2b5a7c8d9e01",
            "attributes": {
                "uuid": "4d1b3f9a-9d4c-5c1e-9f6b-2b5a7c8d9e01",
                "name": "Acme Procurement",
                "companyUuid": "0818f408-cc84-575d-ad54-92118a0e4273",
                "parentBusinessUnitUuid": "b7c2e4d6-1a3f-5b8c-9d0e-4f6a8b2c1d3e",
                "iban": "DE89370400440532013000",
                "bic": "DEUTDEFF",
                "phone": "+49 30 234567890",
                "addressUuids": [
                    "9f2c7b41-5d8e-5a3c-b06f-1e4d7a9c2b58"
                ]
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/company-business-units/4d1b3f9a-9d4c-5c1e-9f6b-2b5a7c8d9e01"
            }
        }
    ]
}

Retrieve a business unit

To retrieve a single business unit, send the request:

GET /company-business-units/{{business_unit_uuid}}

Response

The response contains one business unit, with the same attributes as Retrieve business units.

Create a business unit

To create a business unit, send the request:

POST /company-business-units

Request

Request sample: POST https://glue-backend.mysprykershop.com/company-business-units

{
    "data": {
        "type": "company-business-units",
        "attributes": {
            "name": "Acme Procurement",
            "companyUuid": "0818f408-cc84-575d-ad54-92118a0e4273",
            "addressUuids": ["9f2c7b41-5d8e-5a3c-b06f-1e4d7a9c2b58"]
        }
    }
}

Response

{
    "data": {
        "type": "company-business-units",
        "id": "4d1b3f9a-9d4c-5c1e-9f6b-2b5a7c8d9e01",
        "attributes": {
            "uuid": "4d1b3f9a-9d4c-5c1e-9f6b-2b5a7c8d9e01",
            "name": "Acme Procurement",
            "companyUuid": "0818f408-cc84-575d-ad54-92118a0e4273",
            "parentBusinessUnitUuid": null,
            "iban": null,
            "bic": null,
            "phone": null,
            "addressUuids": ["9f2c7b41-5d8e-5a3c-b06f-1e4d7a9c2b58"]
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/company-business-units/4d1b3f9a-9d4c-5c1e-9f6b-2b5a7c8d9e01"
        }
    }
}

A successful request returns the 201 Created status code. The response contains the uuid that you can use to address the business unit in subsequent requests, and the addresses assigned to it.

Edit a business unit

To update a business unit, send the request:

PATCH /company-business-units/{{business_unit_uuid}}

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/company-business-units/4d1b3f9a-9d4c-5c1e-9f6b-2b5a7c8d9e01

{
    "data": {
        "type": "company-business-units",
        "attributes": {
            "phone": "+49 30 234567890"
        }
    }
}

The request accepts the same writable attributes as Create a business unit, and all of them are optional. The endpoint applies only the attributes present in the payload; every attribute you omit keeps its stored value.

In addition, addressUuids can be sent on update, with the same meaning it has on create:

To detach a business unit from its parent, send parentBusinessUnitUuid as null:

{
    "data": {
        "type": "company-business-units",
        "attributes": {
            "parentBusinessUnitUuid": null
        }
    }
}

A parent that would make the business unit its own ancestor is rejected with 422 and error code 1225. A parent that belongs to another company is rejected with error code 1226.

Response

The response contains the updated business unit, with the same attributes as Retrieve a business unit.

Delete a business unit

To delete a business unit, send the request:

DELETE /company-business-units/{{business_unit_uuid}}

Response

A successful request returns the 204 No Content status code with an empty body.

Possible errors

To view generic errors, see API errors and troubleshooting.