Companies

Companies represent business entities you work with — suppliers, B2B customers, or both. Each company can have multiple addresses (warehouses, HQ, etc.) and contacts (account managers, buyers). Companies are soft-deletable.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
`GET`	`/v1/companies`	Secret	List companies
`POST`	`/v1/companies`	Secret	Create a company
`GET`	`/v1/companies/{id}`	Secret	Get a company
`PATCH`	`/v1/companies/{id}`	Secret	Update a company
`DELETE`	`/v1/companies/{id}`	Secret	Delete a company
`GET`	`/v1/companies/{id}/addresses`	Secret	List company addresses
`POST`	`/v1/companies/{id}/addresses`	Secret	Create an address
`PATCH`	`/v1/companies/{id}/addresses/{address_id}`	Secret	Update an address
`DELETE`	`/v1/companies/{id}/addresses/{address_id}`	Secret	Delete an address
`GET`	`/v1/companies/{id}/contacts`	Secret	List company contacts
`POST`	`/v1/companies/{id}/contacts`	Secret	Create a contact
`PATCH`	`/v1/companies/{id}/contacts/{contact_id}`	Secret	Update a contact
`DELETE`	`/v1/companies/{id}/contacts/{contact_id}`	Secret	Delete a contact

ℹSecret keys only

All company endpoints require a secret API key (sk_live_* or sk_test_*). Publishable keys cannot access company data.

List companies

GET /v1/companies

Returns a paginated list of companies with address and contact counts.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`25`	Results per page (1-250)
`cursor`	string	-	Pagination cursor from a previous response
`sort`	string	`created_at`	Sort field: `created_at`, `updated_at`, `name`
`order`	string	`desc`	Sort direction: `asc`, `desc`
`search`	string	-	Filter by name (case-insensitive substring, max 200 chars)
`type`	string	-	Filter by type: `supplier`, `customer`, `both`
`expand`	string	-	Comma-separated: `addresses`, `contacts`
`fields`	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/companies?type=supplier&limit=10 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response `200`

{
	"data": [
		{
			"id": "comp_abc123",
			"type": "supplier",
			"name": "Acme Supplies",
			"handle": "acme-supplies",
			"email": "orders@acme.com",
			"phone": "+1-555-0100",
			"website": "https://acme.com",
			"tax_number": null,
			"tax_number_type": null,
			"currency": "USD",
			"payment_terms": "net_30",
			"note": null,
			"external_id": null,
			"address_count": 2,
			"contact_count": 1,
			"metadata": {},
			"created_at": "2026-08-01T10:00:00Z",
			"updated_at": "2026-08-01T10:00:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 1
	}
}

Create a company

POST /v1/companies

Creates a new company. Returns the created company with 201.

Request body

Field	Type	Required	Description
`name`	string	Yes	Company name (1-255 chars)
`handle`	string	No	URL-friendly slug (auto-generated from name if omitted)
`type`	string	No	`supplier` (default), `customer`, or `both`
`email`	string	No	Company email
`phone`	string	No	Phone number
`website`	string	No	Website URL
`tax_number`	string	No	Tax identification number
`tax_number_type`	string	No	Tax number type: `vat`, `ein`, `gst`, `abn`, `nif`, `siren`, `siret`, `nzbn`, `gst_hst`, `qst`, `other`
`currency`	string	No	Preferred currency (3-letter ISO code)
`payment_terms`	string	No	`due_on_receipt`, `net_15`, `net_30`, `net_60`, `net_90`
`note`	string	No	Internal notes
`external_id`	string	No	External system reference (e.g. ERP ID)
`metadata`	object	No	Arbitrary key-value pairs (max 50 keys)

Request

curl -X POST https://api.hydrajs.dev/v1/companies \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Supplies",
    "type": "supplier",
    "email": "orders@acme.com",
    "payment_terms": "net_30",
    "currency": "USD"
  }'

Response `201`

{
	"data": {
		"id": "comp_abc123",
		"type": "supplier",
		"name": "Acme Supplies",
		"handle": "acme-supplies",
		"email": "orders@acme.com",
		"phone": null,
		"website": null,
		"tax_number": null,
		"tax_number_type": null,
		"currency": "USD",
		"payment_terms": "net_30",
		"note": null,
		"external_id": null,
		"address_count": 0,
		"contact_count": 0,
		"metadata": {},
		"created_at": "2026-08-26T12:00:00Z",
		"updated_at": "2026-08-26T12:00:00Z"
	}
}

Get a company

GET /v1/companies/{id}

Returns a single company by ID. Use ?expand=addresses,contacts to include related data.

Query parameters

Parameter	Type	Description
`expand`	string	Comma-separated: `addresses`, `contacts`
`fields`	string	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/companies/comp_abc123?expand=addresses,contacts \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response `200`

The response includes addresses and contacts arrays when expanded.

Update a company

PATCH /v1/companies/{id}

Partially updates a company. Send only the fields you want to change.

Request body

All fields are optional. Same fields as create, plus:

Field	Type	Description
`name`	string	Company name
`handle`	string	URL-friendly slug
Any create field	-	Set to `null` to clear nullable fields

Request

curl -X PATCH https://api.hydrajs.dev/v1/companies/comp_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_terms": "net_60"}'

Response `200`

Returns the updated company object.

Delete a company

DELETE /v1/companies/{id}

Soft-deletes a company. The handle is freed for reuse.

Response `204`

Empty body.

Company addresses

Create an address

POST /v1/companies/{id}/addresses

Field	Type	Required	Description
`label`	string	No	Address label (e.g. “Warehouse”, “HQ”)
`first_name`	string	No	Contact first name
`last_name`	string	No	Contact last name
`line1`	string	Yes	Street address
`line2`	string	No	Apt, suite, etc.
`city`	string	Yes	City
`state`	string	No	State/province
`postal_code`	string	No	Postal/ZIP code
`country`	string	Yes	ISO 3166-1 alpha-2 country code
`phone`	string	No	Phone number
`is_default`	boolean	No	Set as default address (default: `false`)

Response `201`

Returns the created address object.

Company contacts

Create a contact

POST /v1/companies/{id}/contacts

Field	Type	Required	Description
`name`	string	Yes	Contact name
`email`	string	No	Email address
`phone`	string	No	Phone number
`role`	string	No	Role (e.g. “Account Manager”)
`is_primary`	boolean	No	Mark as primary contact (default: `false`)

Response `201`

Returns the created contact object.

The company object

Field	Type	Description
`id`	string	Unique ID (prefix: `comp_`)
`type`	string	`supplier`, `customer`, or `both`
`name`	string	Company name
`handle`	string	URL-friendly slug (unique per project)
`email`	string \| null	Company email
`phone`	string \| null	Phone number
`website`	string \| null	Website URL
`tax_number`	string \| null	Tax identification number
`tax_number_type`	string \| null	Tax number type
`currency`	string \| null	Preferred currency (3-letter ISO)
`payment_terms`	string \| null	Payment terms
`note`	string \| null	Internal notes
`external_id`	string \| null	External system reference
`address_count`	integer	Number of addresses
`contact_count`	integer	Number of contacts
`metadata`	object	Arbitrary key-value pairs
`addresses`	object[]	Expanded with `?expand=addresses`
`contacts`	object[]	Expanded with `?expand=contacts`
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Companies

Endpoints

List companies

Query parameters

Request

Response 200

Create a company

Request body

Request

Response 201

Get a company

Query parameters

Request

Response 200

Update a company

Request body

Request

Response 200

Delete a company

Response 204

Company addresses

Create an address

Response 201

Company contacts

Create a contact

Response 201

The company object

Response `200`

Response `201`

Response `200`

Response `200`

Response `204`

Response `201`

Response `201`