> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkturo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API endpoints for CRM companies

> Create and list company records in the Talkturo CRM using the REST API. Companies group contacts and associate them with outbound campaigns.

Companies are organizational records in the Talkturo CRM. They act as a grouping layer above contacts — each contact belongs to a company, and each campaign is associated with one. You can store address, industry, size, and custom fields on a company, and the AI info extractor can update these fields automatically as calls complete.

***

## Create a company

`POST /api/crm/companies`

Creates a new company in your CRM.

### Request body

<ParamField body="teamId" type="string" required>
  The team ID that owns this company.
</ParamField>

<ParamField body="name" type="string" required>
  The company's name.
</ParamField>

<ParamField body="website" type="string">
  The company's website URL.
</ParamField>

<ParamField body="industry" type="string">
  The industry the company operates in (for example, `"SaaS"`, `"Healthcare"`, `"Finance"`).
</ParamField>

<ParamField body="companySize" type="string">
  A descriptor of the company's size (for example, `"1-10"`, `"51-200"`, `"1000+"`).
</ParamField>

<ParamField body="addressLine1" type="string">
  First line of the company's street address.
</ParamField>

<ParamField body="addressLine2" type="string">
  Second address line (suite, floor, etc.).
</ParamField>

<ParamField body="city" type="string">
  City.
</ParamField>

<ParamField body="state" type="string">
  State or province.
</ParamField>

<ParamField body="postalCode" type="string">
  Postal or ZIP code.
</ParamField>

<ParamField body="country" type="string">
  Country (for example, `"US"`, `"GB"`, `"DE"`).
</ParamField>

<ParamField body="phone" type="string">
  Company main phone number in E.164 format.
</ParamField>

<ParamField body="notes" type="string">
  Free-text notes about the company.
</ParamField>

<ParamField body="customFields" type="object">
  Key-value object for any additional company-level data.
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://<your-domain>/api/crm/companies \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team_01j...",
    "name": "Acme Corporation",
    "website": "https://acme.example.com",
    "industry": "Manufacturing",
    "companySize": "500-1000",
    "city": "Chicago",
    "state": "IL",
    "country": "US",
    "customFields": {
      "crm_id": "acme-001",
      "account_tier": "enterprise"
    }
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "company": {
    "id": "comp_01j...",
    "team_id": "team_01j...",
    "name": "Acme Corporation",
    "website": "https://acme.example.com",
    "industry": "Manufacturing",
    "company_size": "500-1000",
    "phone": null,
    "address_line1": null,
    "address_line2": null,
    "city": "Chicago",
    "state": "IL",
    "postal_code": null,
    "country": "US",
    "notes": null,
    "custom_fields": {
      "crm_id": "acme-001",
      "account_tier": "enterprise"
    },
    "contact_count": 0,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}
```

<ResponseField name="company.id" type="string">
  Unique identifier for the company. Use this ID when creating contacts or campaigns.
</ResponseField>

<ResponseField name="company.team_id" type="string">
  The team this company belongs to.
</ResponseField>

<ResponseField name="company.name" type="string">
  Company name.
</ResponseField>

<ResponseField name="company.website" type="string">
  Company website URL.
</ResponseField>

<ResponseField name="company.industry" type="string">
  Industry descriptor.
</ResponseField>

<ResponseField name="company.company_size" type="string">
  Company size descriptor.
</ResponseField>

<ResponseField name="company.phone" type="string">
  Main company phone number.
</ResponseField>

<ResponseField name="company.address_line1" type="string">
  First line of the street address.
</ResponseField>

<ResponseField name="company.address_line2" type="string">
  Second line of the address.
</ResponseField>

<ResponseField name="company.city" type="string">
  City.
</ResponseField>

<ResponseField name="company.state" type="string">
  State or province.
</ResponseField>

<ResponseField name="company.postal_code" type="string">
  Postal or ZIP code.
</ResponseField>

<ResponseField name="company.country" type="string">
  Country code.
</ResponseField>

<ResponseField name="company.notes" type="string">
  Free-text notes.
</ResponseField>

<ResponseField name="company.custom_fields" type="object">
  Key-value pairs of custom company data.
</ResponseField>

<ResponseField name="company.contact_count" type="integer">
  Number of contacts associated with this company.
</ResponseField>

<ResponseField name="company.created_at" type="string">
  ISO 8601 timestamp of when the company was created.
</ResponseField>

<ResponseField name="company.updated_at" type="string">
  ISO 8601 timestamp of the most recent update.
</ResponseField>

***

## List companies

`GET /api/crm/companies`

Returns a paginated list of companies. You can filter by team or account, search by name, and filter by industry.

### Query parameters

<ParamField query="teamId" type="string">
  The team ID to list companies for. Provide either `teamId` or `accountSlug`.
</ParamField>

<ParamField query="accountSlug" type="string">
  Your account slug. Alternative to `teamId`.
</ParamField>

<ParamField query="search" type="string">
  Search by company name.
</ParamField>

<ParamField query="industry" type="string">
  Filter by industry value.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum records to return. Defaults to `50`.
</ParamField>

<ParamField query="offset" type="integer">
  Records to skip for pagination. Defaults to `0`.
</ParamField>

### Example request

```bash theme={null}
curl "https://<your-domain>/api/crm/companies?teamId=team_01j...&industry=SaaS&limit=25" \
  -H "Authorization: Bearer <token>"
```

### Response

```json theme={null}
{
  "success": true,
  "companies": [
    {
      "id": "comp_01j...",
      "team_id": "team_01j...",
      "name": "Acme Corporation",
      "website": "https://acme.example.com",
      "industry": "Manufacturing",
      "company_size": "500-1000",
      "contact_count": 42,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "count": 1,
  "limit": 25,
  "offset": 0
}
```

<ResponseField name="companies" type="array">
  Array of company objects.
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of companies matching the filters.
</ResponseField>

<ResponseField name="limit" type="integer">
  The `limit` value applied to this response.
</ResponseField>

<ResponseField name="offset" type="integer">
  The `offset` value applied to this response.
</ResponseField>

<Note>
  When creating a campaign, you must supply a `companyId`. Create your company record first, then create contacts under it, then create the campaign.
</Note>