Overview

Base URL

https://www.happyscribe.com/api/v1

https://www.happyscribe.com/api/v1

Authentication is the same Bearer token as the Product API — see the Authentication section.

The Intelligence API extracts a structured graph of companies and people from your organization's meeting transcripts. As your team records calls and meetings, HappyScribe automatically identifies the external participants and their employers, enriches their profiles with firmographic data, and makes them queryable through a dedicated API.

What's included

Enrolling your organization unlocks three capabilities:

Transcription Extensions — The GET /transcriptions endpoint gains four additional filter parameters (person_id, person_email, company_id, company_domain) and two new response fields (people, companies) that embed linked contacts directly on each transcription.

Companies — List and retrieve companies discovered from your transcripts, enriched with industry, employee count, funding stage, and other firmographic data.

People — List and retrieve individual contacts discovered from your transcripts. People are linked to their company and can optionally be enriched with job title, seniority, and LinkedIn profile (opt-in, disabled by default).

Enrichment

Company enrichment (industry, employee count, website, LinkedIn, etc.) runs automatically for all enrolled organizations when a new company is discovered.

Person enrichment (job title, seniority, LinkedIn profile) is disabled by default and must be opted in separately. Contact support@happyscribe.com to enable it. Until enrichment has run, those fields on a person record are null.

Transcription Extensions

The Intelligence API extends the existing GET /transcriptions endpoint with additional filter parameters and new response fields. No changes are needed to your existing transcription workflow — the extensions are additive and silently ignored for non-enrolled organizations.

Additional Filter Parameters

curl "https://www.happyscribe.com/api/v1/transcriptions?organization_id=123&company_domain=acme.com" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch(
  'https://www.happyscribe.com/api/v1/transcriptions?organization_id=123&company_domain=acme.com',
  {
    headers: {
      authorization: 'Bearer **your_api_key_here**',
    },
  },
);

Returns all transcriptions where anyone from acme.com was a participant:

{
  "results": [
    {
      "id": "e458099e7f8da14f9625854ba7b6a026917ad306",
      "name": "Q4 sync — 2024-01-15",
      "state": "automatic_done",
      "people": [
        {
          "id": 1,
          "name": "Jane Smith",
          "primaryEmail": "jane@acme.com",
          "company": { "id": 1, "name": "Acme Corp", "primaryDomain": "acme.com" },
          "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/people/1" } }
        }
      ],
      "companies": [
        {
          "id": 1,
          "name": "Acme Corp",
          "primaryDomain": "acme.com",
          "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/companies/1" } }
        }
      ],
      "_links": {
        "self": {
          "editorUrl": "https://www.happyscribe.com/api/v1/transcriptions/e458099e7f8da14f9625854ba7b6a026917ad306"
        }
      }
    }
  ],
  "_links": {}
}

The following query parameters are available on GET /api/v1/transcriptions for enrolled organizations:

Parameter	Description
`person_id`	Filter to transcriptions where the person with this ID was linked.
`person_email`	Same as `person_id` but resolved by email address.
`company_id`	Filter to transcriptions where any person from the company with this ID was linked.
`company_domain`	Same as `company_id` but resolved by domain — matches `primaryDomain` or any entry in the company's `domains` array (e.g. `company_domain=acme.com`).

These filter parameters never return a 400 for unrecognized values — the API returns 200 with an empty results array. This differs from the People and Companies endpoints, which validate their parameters strictly.

Embedded People and Companies

For enrolled organizations, transcription responses include two additional top-level arrays: people and companies. These appear on both the list endpoint and the retrieve endpoint.

Example transcription response with embedded people and companies:

{
  "id": "e458099e7f8da14f9625854ba7b6a026917ad306",
  "name": "Q4 sync — 2024-01-15",
  "state": "automatic_done",
  "people": [
    {
      "id": 1,
      "name": "Jane Smith",
      "primaryEmail": "jane@acme.com",
      "company": { "id": 1, "name": "Acme Corp", "primaryDomain": "acme.com" },
      "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/people/1" } }
    }
  ],
  "companies": [
    {
      "id": 1,
      "name": "Acme Corp",
      "primaryDomain": "acme.com",
      "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/companies/1" } }
    }
  ]
}

Field	Type	Description
`people`	array of Person	Every Person linked to this transcription via the Intelligence API.
`companies`	array of Company	The distinct Companies of those people.

Speaker vs. attendee provenance is not distinguished — all linked people appear uniformly in people regardless of whether they were a speaker, an invitee, or discovered through another signal. For fine-grained role information, use meeting.participants and meeting.organizer on the transcription.

These fields are absent for non-enrolled organizations and for transcriptions where no Intelligence API contacts have been linked yet. Always guard against people and companies being absent or empty when deserializing.

Companies

The Companies API lets you list and retrieve companies discovered from your organization's meeting transcripts.

List Companies

curl "https://www.happyscribe.com/api/v1/companies?organization_id=123" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/companies?organization_id=123', {
  headers: {
    authorization: 'Bearer **your_api_key_here**',
  },
});

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": 1,
      "name": "Acme Corp",
      "primaryDomain": "acme.com",
      "domains": ["acme.com", "acme.co"],
      "industry": "Technology",
      "employeeCount": 500,
      "foundedYear": 2010,
      "shortDescription": "Project management software for modern teams.",
      "keywords": ["saas", "productivity", "collaboration"],
      "city": "San Francisco",
      "country": "United States",
      "websiteUrl": "https://acme.com",
      "linkedinUrl": "https://linkedin.com/company/acme-corp",
      "logoUrl": "https://example.com/logo.png",
      "totalFunding": null,
      "annualRevenue": null,
      "latestFundingStage": null,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-06-01T12:00:00Z",
      "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/companies/1" } }
    }
  ],
  "_links": {
    "next": {
      "url": "https://www.happyscribe.com/api/v1/companies?organization_id=123&page=2"
    }
  }
}

Returns a paginated list of companies associated with your organization, sorted by name ascending. _links.next is omitted on the last page.

HTTP Request

GET https://www.happyscribe.com/api/v1/companies

Query Parameters

Parameter	Default	Description
organization_id	-	(required) ID of the organization to list companies from.
search	-	Case-insensitive substring search on company `name` only.
domain	-	Exact-match filter on `primaryDomain` or any entry in `domains` (e.g. `?domain=acme.com`).
page	1	Page number to retrieve.
per_page	5	Number of results per page. Maximum 100.

Response Fields

Field	Type	Description
`id`	integer	Unique identifier for the company.
`name`	string	Company name.
`primaryDomain`	string	The primary web domain for the company.
`domains`	array of strings	All known domains for the company, including `primaryDomain`.
`industry`	string	Industry classification from enrichment.
`employeeCount`	integer	Approximate number of employees from enrichment.
`foundedYear`	integer	Year the company was founded, from enrichment.
`shortDescription`	string	Brief description of the company from enrichment.
`keywords`	array of strings	Tags and keywords associated with the company from enrichment.
`city`	string	City where the company is headquartered.
`country`	string	Country where the company is headquartered.
`websiteUrl`	string	Company website URL.
`linkedinUrl`	string	LinkedIn company page URL.
`logoUrl`	string	Company logo image URL.
`totalFunding`	number	Total funding raised in USD. May be `null` if not available.
`annualRevenue`	number	Estimated annual revenue in USD. May be `null` if not available.
`latestFundingStage`	string	Most recent funding stage (e.g. `"Series A"`). May be `null` if not available.
`createdAt`	ISO 8601	When the company record was first created.
`updatedAt`	ISO 8601	When the company record was last updated.
`_links.self.url`	string	The canonical API URL for this company.

totalFunding, annualRevenue, and latestFundingStage may be null even when enrichment has run — these fields are not available for all companies.

Retrieve a Company

curl "https://www.happyscribe.com/api/v1/companies/1" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/companies/1', {
  headers: {
    authorization: 'Bearer **your_api_key_here**',
  },
});

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "Acme Corp",
  "primaryDomain": "acme.com",
  "domains": ["acme.com", "acme.co"],
  "industry": "Technology",
  "employeeCount": 500,
  "foundedYear": 2010,
  "shortDescription": "Project management software for modern teams.",
  "keywords": ["saas", "productivity", "collaboration"],
  "city": "San Francisco",
  "country": "United States",
  "websiteUrl": "https://acme.com",
  "linkedinUrl": "https://linkedin.com/company/acme-corp",
  "logoUrl": "https://example.com/logo.png",
  "totalFunding": null,
  "annualRevenue": null,
  "latestFundingStage": null,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-06-01T12:00:00Z",
  "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/companies/1" } }
}

Returns a single Company resource by ID.

HTTP Request

GET https://www.happyscribe.com/api/v1/companies/:id

Error Reference

Status	Cause
401	Missing or invalid `Authorization` header.
400	Missing or invalid `organization_id` parameter.
400	`:id` is not an integer.
404	Organization is not enrolled in the Intelligence API; company not found; or company belongs to another organization.

People

The People API lets you list and retrieve contacts discovered from your organization's meeting transcripts.

List People

curl "https://www.happyscribe.com/api/v1/people?organization_id=123" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/people?organization_id=123', {
  headers: {
    authorization: 'Bearer **your_api_key_here**',
  },
});

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": 1,
      "name": "Jane Smith",
      "fullName": "Jane Smith",
      "emails": ["jane@acme.com", "jsmith@acme.com"],
      "primaryEmail": "jane@acme.com",
      "company": {
        "id": 1,
        "name": "Acme Corp",
        "primaryDomain": "acme.com",
        "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/companies/1" } }
      },
      "jobTitle": null,
      "seniority": null,
      "headline": null,
      "linkedinUrl": null,
      "city": null,
      "country": null,
      "photoUrl": "https://example.com/photo.png",
      "avatarUrl": "https://example.com/avatar.png",
      "enrichedAt": null,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-06-01T12:00:00Z",
      "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/people/1" } }
    }
  ],
  "_links": {
    "next": {
      "url": "https://www.happyscribe.com/api/v1/people?organization_id=123&page=2"
    }
  }
}

Returns a paginated list of people associated with your organization, sorted by name ascending. _links.next is omitted on the last page.

The inline company object on each person is the full Company resource. See the Companies section for field descriptions.

HTTP Request

GET https://www.happyscribe.com/api/v1/people

Query Parameters

Parameter	Default	Description
organization_id	-	(required) ID of the organization to list people from.
search	-	Full-text search across name, full name, and email fields.
email	-	Filter to the person with this exact email address (matched case-insensitively).
company_id	-	Filter to people who belong to the company with this ID. Must be an integer.
page	1	Page number to retrieve.
per_page	5	Number of results per page. Maximum 100.

Response Fields

Field	Type	Description
`id`	integer	Unique identifier for the person.
`name`	string	Display name (typically first name + last initial, or first name alone).
`fullName`	string	Full name when available.
`emails`	array of strings	All email addresses recorded for this person. See primary email caveat below.
`primaryEmail`	string	The first email address recorded for this person. See primary email caveat below.
`company`	object	Full Company resource for the person's primary company, or `null` if no company is linked. See the Companies section for field descriptions.
`jobTitle`	string	Job title from enrichment. See enrichment caveat below.
`seniority`	string	Seniority level from enrichment. See enrichment caveat below.
`headline`	string	Professional headline from enrichment. See enrichment caveat below.
`linkedinUrl`	string	LinkedIn profile URL from enrichment. See enrichment caveat below.
`city`	string	City from enrichment. See enrichment caveat below.
`country`	string	Country from enrichment. See enrichment caveat below.
`photoUrl`	string	Full-size photo URL.
`avatarUrl`	string	Thumbnail avatar URL.
`enrichedAt`	ISO 8601	Timestamp of the last enrichment run for this person, or `null` if enrichment has not run.
`createdAt`	ISO 8601	When the person record was first created.
`updatedAt`	ISO 8601	When the person record was last updated.
`_links.self.url`	string	The canonical API URL for this person.

Enrichment caveat: jobTitle, seniority, headline, linkedinUrl, city, and country are populated only when person enrichment has run. Person-level enrichment is disabled by default — these fields are typically null. Contact support to opt in.

Primary email caveat: emails is an ordered array; primaryEmail is the first email recorded for this person. The order reflects discovery order, not user preference, and cannot be changed via the API.

Retrieve a Person

curl "https://www.happyscribe.com/api/v1/people/1" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/people/1', {
  headers: {
    authorization: 'Bearer **your_api_key_here**',
  },
});

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "Jane Smith",
  "fullName": "Jane Smith",
  "emails": ["jane@acme.com", "jsmith@acme.com"],
  "primaryEmail": "jane@acme.com",
  "company": {
    "id": 1,
    "name": "Acme Corp",
    "primaryDomain": "acme.com",
    "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/companies/1" } }
  },
  "jobTitle": null,
  "seniority": null,
  "headline": null,
  "linkedinUrl": null,
  "city": null,
  "country": null,
  "photoUrl": "https://example.com/photo.png",
  "avatarUrl": "https://example.com/avatar.png",
  "enrichedAt": null,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-06-01T12:00:00Z",
  "_links": { "self": { "url": "https://www.happyscribe.com/api/v1/people/1" } }
}

Returns a single Person resource by ID.

HTTP Request

GET https://www.happyscribe.com/api/v1/people/:id

Error Reference

Status	Cause
401	Missing or invalid `Authorization` header.
400	Missing or invalid `organization_id` parameter.
400	`:id` is not an integer, or `?company_id` is not an integer.
404	Organization is not enrolled in the Intelligence API; person not found; or person belongs to another organization.