# Companies

> Manage private companies (lenders and sponsors) in the Lev API.

Source: https://www.lev.com/docs/build/companies

Last updated: June 2026

---
## Overview

| Endpoint | Description |
|----------|-------------|
| `GET /companies` | List companies with pagination |
| `GET /companies/{id}` | Get a single company |
| `POST /companies` | Create a new company |
| `PATCH /companies/{id}` | Update a company |
| `GET /companies/{id}/notes` | List notes logged on a company |
| `POST /companies/{id}/notes` | Add a note to a company |
| `PATCH /companies/{id}/notes/{note_id}` | Edit a company note |
| `DELETE /companies/{id}/notes/{note_id}` | Delete a company note |

## List Companies

### `GET /api/external/v2/companies`

List companies in your account

#### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | `integer` | No | Results per page (1–200, default 50) |
| `cursor` | `string` | No | Cursor for next page |
| `fields` | `string` | No | Comma-separated fields to include |

Response: `200`

#### Error Responses

- **401** (unauthorized): Authentication required
- **400** (bad_request): cursor and sort cannot be combined; use offset pagination when sorting

## Get Company

### `GET /api/external/v2/companies/{company_id}`

Get a single company by ID

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `company_id` | `integer` | Yes | The company ID |

Response: `200`

#### Error Responses

- **401** (unauthorized): Authentication required
- **404** (not_found): Company not found

## Create Company

### `POST /api/external/v2/companies`

Create a new company

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | Company name (1–255 characters) |
| `company_type` | `string` | Yes | Company type: "lender" or "sponsor" (required) |
| `website` | `string` | No | Company website URL |
| `address` | `string` | No | Street address |
| `city` | `string` | No | City |
| `state` | `string` | No | State |
| `zip` | `string` | No | ZIP code |
| `org_id` | `integer` | No | Link to a global organization record |
| `linkedin_url` | `string` | No | LinkedIn URL |

Response: `201`

#### Error Responses

- **401** (unauthorized): Authentication required
- **403** (forbidden): User not authorized to create company
- **422** (validation_error): name is required; company_type is required

## Update Company

### `PATCH /api/external/v2/companies/{company_id}`

Update a company

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `company_id` | `integer` | Yes | The company ID |

Response: `200`

#### Error Responses

- **401** (unauthorized): Authentication required
- **404** (not_found): Company not found

## List Company Notes

### `GET /api/external/v2/companies/{company_id}/notes`

List notes logged on a company

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `company_id` | `integer` | Yes | The company ID |

#### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | `integer` | No | Results per page (1–200, default 50) |
| `cursor` | `string` | No | Cursor for next page |

Response: `200`

#### Error Responses

- **401** (unauthorized): Authentication required
- **404** (not_found): Company not found

## Create Company Note

### `POST /api/external/v2/companies/{company_id}/notes`

Add a note to a company

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `company_id` | `integer` | Yes | The company ID |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | `string` | Yes | Note text. Must be non-empty. |

Response: `201`

#### Error Responses

- **401** (unauthorized): Authentication required
- **404** (not_found): Company not found
- **422** (validation_error): text must not be blank

- Supports idempotent writes with the `Idempotency-Key` header.

## Update Company Note

### `PATCH /api/external/v2/companies/{company_id}/notes/{note_id}`

Edit a company note

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `company_id` | `integer` | Yes | The company ID |
| `note_id` | `integer` | Yes | The note ID |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | `string` | Yes | Replacement note text. Must be non-empty. |

Response: `200`

#### Error Responses

- **401** (unauthorized): Authentication required
- **404** (not_found): Company or note not found
- **400** (bad_request): text cannot be empty
- **422** (validation_error): text must not be blank

- Supports idempotent writes with the `Idempotency-Key` header.

## Delete Company Note

### `DELETE /api/external/v2/companies/{company_id}/notes/{note_id}`

Permanently delete a company note

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `company_id` | `integer` | Yes | The company ID |
| `note_id` | `integer` | Yes | The note ID |

Response: `200`

#### Error Responses

- **401** (unauthorized): Authentication required
- **404** (not_found): Company or note not found

## Company Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Company identifier |
| `name` | string\|null | Company name |
| `website` | string\|null | Website URL |
| `address` | string\|null | Street address |
| `city` | string\|null | City |
| `state` | string\|null | State |
| `zip` | string\|null | ZIP code |
| `org_id` | integer\|null | Linked global organization ID |
| `owner_account_id` | integer\|null | Owning account ID |
| `is_connected` | boolean | Whether this is a connected company |
| `linkedin_url` | string\|null | LinkedIn URL |
| `created_at` | string\|null | Creation timestamp |
| `updated_at` | string\|null | Last update timestamp |