API Endpoints

Companies

The Companies API allows you to create, read, and update company records. Companies can be linked to people and support custom fields and nested notes.

List Companies 

GET /api/companies

Retrieves a paginated list of companies in your organization.

Query Parameters

Parameter Type Required Description
limit integer No Number of companies to return (1-500, default: 50)
offset integer No Number of companies to skip (default: 0)
search string No Search by name, industry, or website
isSolutionProvider boolean No Filter to solution providers (true or false)

Response

Success Response (200)

{
  "success": true,
  "data": {
    "companies": [
      {
        "id": "company-uuid",
        "name": "Acme Inc",
        "description": "Enterprise software company",
        "website": "https://acme.com",
        "industry": "Technology",
        "address": "456 Market St, San Francisco, CA 94102",
        "tagline": "Enterprise software, minus the enterprise",
        "headquarters": "San Francisco, CA",
        "employeeCount": "51-200",
        "foundedYear": 2015,
        "linkedinUrl": "https://linkedin.com/company/acme",
        "logoUrl": "https://cdn.example.com/acme.png",
        "productOfferings": ["Widgets", "Sprockets"],
        "technologyNames": ["PostgreSQL", "TypeScript"],
        "isSolutionProvider": true,
        "isConnector": false,
        "primaryContactId": "person-uuid",
        "customFields": {
          "cf_tier": "Enterprise"
        },
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Profile Fields

Company responses include a profile block intended for public-facing directories and websites: tagline, headquarters, employeeCount, foundedYear, linkedinUrl, logoUrl, productOfferings, and technologyNames. All are optional and may be null.

Two typing notes for consumers:

  • employeeCount is a string band (for example "51-200"), not a number.
  • foundedYear is an integer.
  • productOfferings and technologyNames are string arrays and default to [], never null.

These fields are read-only; they are not accepted by POST or PATCH.

Create Company 

POST /api/companies

Creates a new company in your organization.

Request Body 

{
  "name": "Acme Inc",
  "description": "Enterprise software company",
  "website": "https://acme.com",
  "industry": "Technology",
  "address": "456 Market St, San Francisco, CA 94102",
  "isSolutionProvider": false,
  "isConnector": false,
  "customFields": {
    "cf_tier": "Enterprise"
  }
}

Parameters

Parameter Type Required Description
name string Yes Company name (1-200 characters)
description string No Company description
website string No Company website URL
industry string No Industry sector
address string No Full address
isSolutionProvider boolean No Mark as a solution provider (defaults to false)
isConnector boolean No Mark as a connector (defaults to false)
customFields object No Custom field key-value pairs

Response

Success Response (201)

{
  "success": true,
  "data": {
    "id": "company-uuid",
    "name": "Acme Inc",
    "description": "Enterprise software company",
    "website": "https://acme.com",
    "industry": "Technology",
    "address": "456 Market St, San Francisco, CA 94102",
    "primaryContactId": null,
    "customFields": {
      "cf_tier": "Enterprise"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "message": "Company created successfully"
}

Error Response (409)

{
  "success": false,
  "error": "A company with this name already exists in your organization"
}

Get Company 

GET /api/companies/{id}

Retrieves details for a specific company including custom fields.

Path Parameters

Parameter Type Required Description
id string Yes Company UUID

Response

Success Response (200)

{
  "success": true,
  "data": {
    "id": "company-uuid",
    "name": "Acme Inc",
    "description": "Enterprise software company",
    "website": "https://acme.com",
    "industry": "Technology",
    "address": "456 Market St, San Francisco, CA 94102",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "tagline": "Enterprise software, minus the enterprise",
    "headquarters": "San Francisco, CA",
    "employeeCount": "51-200",
    "foundedYear": 2015,
    "linkedinUrl": "https://linkedin.com/company/acme",
    "logoUrl": "https://cdn.example.com/acme.png",
    "productOfferings": ["Widgets", "Sprockets"],
    "technologyNames": ["PostgreSQL", "TypeScript"],
    "isSolutionProvider": true,
    "isConnector": false,
    "primaryContactId": "person-uuid",
    "customFields": {
      "cf_tier": "Enterprise",
      "cf_account_manager": "Jane Smith"
    },
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Update Company 

PATCH /api/companies/{id}

Updates an existing company. Only provided fields are updated. Custom fields are merged with existing values.

Accepts the same fields as Create Company, except name is optional. Changing isSolutionProvider or isConnector is recorded in the company's activity timeline.

Update also accepts primaryContactId, which is not accepted on create. (API v3.4.0)

Parameter Type Required Description
primaryContactId string | null No UUID of a person at this company (their companyId must be this company). null clears the primary contact; omit to leave it.

A primaryContactId for a person who does not belong to the company returns 400 with Primary contact must be an employee of this company. Create the person first with POST /api/people and this company's companyId.

Request Body 

{
  "industry": "SaaS",
  "isSolutionProvider": true,
  "primaryContactId": "person-uuid",
  "customFields": {
    "cf_tier": "Premium"
  }
}

Response

Success Response (200)

{
  "success": true,
  "data": {
    "id": "company-uuid",
    "name": "Acme Inc",
    "industry": "SaaS",
    "primaryContactId": "person-uuid",
    "customFields": {
      "cf_tier": "Premium",
      "cf_account_manager": "Jane Smith"
    }
  },
  "message": "Company updated successfully"
}

Example Usage 

# List companies with search
curl -X GET "https://api.introzy.com/api/companies?search=acme&limit=10" \
  -H "Authorization: Bearer introzy_your_api_key"

# Create a new company
curl -X POST "https://api.introzy.com/api/companies" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc",
    "website": "https://acme.com",
    "industry": "Technology",
    "customFields": {
      "cf_tier": "Enterprise"
    }
  }'

# Update a company
curl -X PATCH "https://api.introzy.com/api/companies/company-uuid" \
  -H "Authorization: Bearer introzy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"industry": "SaaS"}'

Related Endpoints

  • Notes — Manage notes on companies via GET/POST /api/companies/{companyId}/notes
  • Custom Fields — Define custom field schemas via GET/POST /api/companies/custom-fields
Previous
People
Next
Pipelines
Introzy API Documentation