Skip to main content
GET
/
companies
List Companies
curl --request GET \
  --url https://api.example.com/companies
{
  "success": true,
  "data": {
    "data.items": [
      {
        "data.items[].id": "<string>",
        "data.items[].name": "<string>",
        "data.items[].slug": "<string>",
        "data.items[].industry": "<string>",
        "data.items[].country": "<string>",
        "data.items[].timezone": "<string>",
        "data.items[].currency": "<string>",
        "data.items[].registration_number": "<string>",
        "data.items[].tax_id": "<string>",
        "data.items[].address": "<string>",
        "data.items[].phone": "<string>",
        "data.items[].logo_url": "<string>",
        "data.items[].status": "<string>",
        "data.items[].settings": {},
        "data.items[].created_at": "<string>",
        "data.items[].updated_at": "<string>"
      }
    ],
    "data.total": 123,
    "data.page": 123,
    "data.page_size": 123,
    "data.total_pages": 123
  }
}
Retrieve a paginated list of companies with optional filtering by status and search.

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
page_size
integer
default:"10"
Number of items per page
​
status
string
Filter by company status. One of: active, suspended, inactive
​
search
string
Search companies by name or slug

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Paginated company results
​
data.items
array
Array of company objects
​
data.items[].id
string
Company UUID
​
data.items[].name
string
Company name
​
data.items[].slug
string
Company slug identifier
​
data.items[].industry
string
Industry sector
​
data.items[].country
string
Country location
​
data.items[].timezone
string
Timezone identifier
​
data.items[].currency
string
Currency code
​
data.items[].registration_number
string
Registration number
​
data.items[].tax_id
string
Tax identification
​
data.items[].address
string
Physical address
​
data.items[].phone
string
Contact phone
​
data.items[].logo_url
string
Logo URL
​
data.items[].status
string
Company status
​
data.items[].settings
object
Company settings (JSON)
​
data.items[].created_at
string
Creation timestamp (ISO 8601)
​
data.items[].updated_at
string
Last update timestamp (ISO 8601)
​
data.total
integer
Total number of companies matching the criteria
​
data.page
integer
Current page number
​
data.page_size
integer
Items per page
​
data.total_pages
integer
Total number of pages

​
Request Examples

cURL
curl -X GET https://api.companyflow.com/companies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response Example

200 OK
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Acme Corporation",
        "slug": "acme-corp",
        "industry": "Technology",
        "country": "United States",
        "timezone": "America/New_York",
        "currency": "USD",
        "registration_number": "123456789",
        "tax_id": "98-7654321",
        "address": "123 Main St, New York, NY 10001",
        "phone": "+1-555-0100",
        "logo_url": "",
        "status": "active",
        "settings": null,
        "created_at": "2026-03-03T10:00:00Z",
        "updated_at": "2026-03-03T10:00:00Z"
      },
      {
        "id": "223e4567-e89b-12d3-a456-426614174001",
        "name": "TechStart Inc",
        "slug": "techstart",
        "industry": "Software",
        "country": "Canada",
        "timezone": "America/Toronto",
        "currency": "CAD",
        "registration_number": "987654321",
        "tax_id": "12-3456789",
        "address": "456 Tech Ave, Toronto, ON M5H 2N2",
        "phone": "+1-416-555-0200",
        "logo_url": "https://example.com/logo.png",
        "status": "active",
        "settings": null,
        "created_at": "2026-03-02T15:30:00Z",
        "updated_at": "2026-03-02T15:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 10,
    "total_pages": 5
  }
}
400 Bad Request
{
  "success": false,
  "message": "invalid page"
}
500 Internal Server Error
{
  "success": false,
  "message": "internal server error"
}

​
Error Responses

Status CodeDescription
400Invalid page or page_size parameter
500Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us