# Businesses & Contacts

Businesses represent companies and organizations in your transport network — your own company, customers, carriers, subcontractors, and receivers. This guide covers creating, managing, and organizing business relationships.

## Creating a Business


```bash
curl -X POST https://api.otms.transportial.com/api/business \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Acme Logistics B.V.",
    "relationType": "carrier",
    "coc": "12345678",
    "vat": "NL123456789B01",
    "website": "https://acme-logistics.com",
    "locations": [
      {
        "name": "Headquarters",
        "address": {
          "street": "Transportweg 1",
          "city": "Rotterdam",
          "postalCode": "3011 AA",
          "country": "NL"
        }
      }
    ],
    "contactDetails": [
      { "type": "email", "value": "ops@acme-logistics.com" },
      { "type": "phone", "value": "+31 10 123 4567" }
    ]
  }'
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "business": {
    "id": "business-uuid",
    "name": "Acme Logistics B.V.",
    "relationType": "carrier",
    "coc": "12345678",
    "vat": "NL123456789B01",
    "createdAt": "2026-03-22T10:00:00Z"
  }
}
```

## Relation Types

Businesses can have different relationships to your platform:

| Relation Type | Description |
|  --- | --- |
| `carrier` | Transport carrier or logistics service provider |
| `shipper` | Customer who ships goods |
| `receiver` | Recipient of goods |
| `subcontractor` | Subcontracted carrier |
| `supplier` | Supplier of goods or services |


## Updating a Business


```bash
curl -X PUT https://api.otms.transportial.com/api/business \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "business-uuid",
    "name": "Acme Logistics International B.V.",
    "eori": "NL123456789"
  }'
```

## Get a Business


```bash
curl -X GET "https://api.otms.transportial.com/api/business/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## List Businesses


```bash
# Paginated list
curl -X GET "https://api.otms.transportial.com/api/businesses/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Search with filters
curl -X POST "https://api.otms.transportial.com/api/businesses/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "relationType": "carrier"
  }'
```

## Business Hierarchy

Businesses can be organized hierarchically using the `partOf` relationship. This is useful for companies with divisions or subsidiaries:


```bash
curl -X POST https://api.otms.transportial.com/api/business \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Acme Netherlands Division",
    "partOf": { "id": "parent-business-uuid" }
  }'
```

## Contact Details

Businesses support multiple contact detail types:


```json
{
  "contactDetails": [
    { "type": "email", "value": "info@company.com" },
    { "type": "phone", "value": "+31 10 123 4567" },
    { "type": "fax", "value": "+31 10 123 4568" },
    { "type": "mobile", "value": "+31 6 12345678" }
  ]
}
```

## Tax Identifiers

Businesses can have multiple tax and registration identifiers:

| Field | Description |
|  --- | --- |
| `vat` | VAT number (e.g., NL123456789B01) |
| `eori` | EORI number for customs |
| `coc` | Chamber of Commerce number |


## Business Locations

Link locations (warehouses, offices, depots) to a business:


```bash
curl -X PUT https://api.otms.transportial.com/api/business \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "business-uuid",
    "locations": [
      { "id": "existing-location-uuid" },
      {
        "name": "New depot",
        "address": {
          "street": "Industrieweg 5",
          "city": "Eindhoven",
          "postalCode": "5600 AB",
          "country": "NL"
        }
      }
    ]
  }'
```

## Businesses in Transport Orders

Businesses are referenced throughout transport operations:

- **Customer** — the business requesting the transport
- **Carrier** — the business executing the transport
- **Sender / Receiver** — physical parties at load and unload locations
- **Invoice subject / target** — parties on financial documents



```bash
curl -X POST https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Order #1042",
    "customer": { "id": "customer-business-uuid" },
    "consignments": [
      {
        "originalPhysicalSender": { "id": "sender-business-uuid" },
        "originalPhysicalAddressee": { "id": "receiver-business-uuid" }
      }
    ]
  }'
```

## Next Steps

- Create transport orders for your businesses with the [Quickstart guide](/guides/quickstart)
- Link locations to businesses in [Managing Locations](/examples/managing-locations)
- See the full [API Reference](/apis) for all business endpoints