Companies

Resolve or create a company

Changed on

Resolves an existing company by website domain (and optionally by name), or creates a new one if no match is found. On creation, a logo is auto-fetched from website when available. Use matchByName to disable name fallback, or createIfMissing to disable creation. Useful for workflows that have a name and website but no company ID yet.

post/companies/find-or-create

Request

  • Base URL: https://api.cavuno.com/v1
  • URL: https://api.cavuno.com/v1/companies/find-or-create
  • Auth: HTTP bearer

Request body

namestring required

The company's display name.

websitestring nullable

Public company website URL. Used to resolve to an existing company by domain before falling back to creation. null or "" means not set.

summarystring nullable

One-line summary of the company. Up to 280 characters. null or "" means not set.

matchByNameboolean

If true (default), falls back to matching by name when no website match is found. Set to false to match by website domain only.

createIfMissingboolean

If true (default), creates a new company when no match is found. Set to false to receive a 404 companies_not_found response instead.

Response

Successful response. The matched field indicates whether the returned company already existed (true) or was newly created (false).

idstring required

Unique identifier for the object. Use this value as the {id} path parameter for the company endpoints (e.g. GET /v1/companies/{id}).

object'company' required

String representing the object's type. Objects of the same type share the same value.

namestring required

Display name of the company.

slugstring required

URL-friendly slug for the company.

websitestring nullable required

Public company website URL, or null if not set.

logoUrlstring nullable required

URL of the company logo, or null if no logo is set.

summarystring nullable required

One-line summary of the company, or null if not set.

marketsstring[] required

Canonical market slugs assigned to the company.

xUrlstring nullable required

X (Twitter) profile URL, or null if not set.

linkedinUrlstring nullable required

LinkedIn page URL, or null if not set.

facebookUrlstring nullable required

Facebook page URL, or null if not set.

instagramUrlstring nullable required

Instagram profile URL, or null if not set.

createdAtstring required

Time at which the company was created. ISO 8601 datetime.

updatedAtstring nullable required

Time at which the company was last updated, or null if it has never been updated. ISO 8601 datetime.

revisioninteger required

Public Company lifecycle revision. Historical rows may be 0 until rollout backfill.

descriptionstring nullable required

Long-form description of the company (HTML), or null if not set.

canBackfillboolean nullable required

Whether automated backfill of jobs from this company is supported, or null if not yet evaluated.

jobCountnumber required

Total number of jobs at this company across all statuses.

publishedJobCountnumber required

Number of currently-published jobs at this company.

matchedboolean required

Changes