Levitate Companies API

openapi: 3.2.0
info:
  title: LevitateAPI | public-v1 Companies API
  version: 1.0.0
servers:
- url: https://api.levitate.ai/
tags:
- name: Companies
paths:
  /public/v1/Companies/{id}:
    get:
      tags:
      - Companies
      summary: Get Company by Id
      description: '

        ### Retrieves company information for a given identifier.



        **Required Scope:** `levitate:contacts`'
      operationId: GetCompanyById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResultOfCompany'
        '401':
          description: Unauthorized
          content:
            application/json: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
    patch:
      tags:
      - Companies
      summary: Update a company
      description: '

        ### Partially updates a company and returns the full record.

        Only the fields present in the body are changed: an omitted field is left unchanged, an explicit `null`

        clears a scalar, and a provided array replaces the whole array. `name` may be changed but not cleared.

        Unknown or read-only fields are rejected. Changing the name or an email domain to one already used by

        another company on the account returns `409`; an email domain that cannot identify a company is rejected

        with `400`.



        **Required Scope:** `levitate:contacts`'
      operationId: UpdateCompany
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyPatch'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CompanyPatch'
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CompanyPatch'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResultOfCompany'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '401':
          description: Unauthorized
          content:
            application/json: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
    delete:
      tags:
      - Companies
      summary: Delete a company
      description: '

        ### Permanently removes a company.

        Contacts associated with the company are detached from it, not deleted. Returns `404` when the company

        doesn''t exist on the caller''s account.



        **Required Scope:** `levitate:contacts`'
      operationId: DeleteCompany
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '401':
          description: Unauthorized
          content:
            application/json: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
  /public/v1/Companies:
    get:
      tags:
      - Companies
      summary: List companies
      description: '

        ### Returns a cursor-paged list of companies matching the supplied filters.

        The query-string filters combine with AND. `name` is a case-insensitive prefix match; `tags` is repeatable

        and every supplied tag must be present on the company (max 10). Each row is a lean summary; follow its

        `url` for the full record.


        **Sortable fields:** `name` (default, ascending) and `creationDate`. Prefix a field with `-` for descending order (e.g. `sort=-name`).



        **Required Scope:** `levitate:contacts`'
      operationId: ListCompanies
      parameters:
      - name: name
        in: query
        description: Filter by company name
        schema:
          type: string
      - name: tags
        in: query
        description: Filter by tag; repeatable, combined with AND (max 10)
        schema:
          type: array
          items:
            type: string
      - name: limit
        in: query
        description: Maximum results per page (default 25, max 100)
        schema:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
      - name: pageToken
        in: query
        description: Opaque pagination cursor from a previous response; omit for the first page
        schema:
          type: string
      - name: sort
        in: query
        description: Sort field; prefix with '-' for descending. See the endpoint description for supported fields.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResultOfPagedCollectionOfCompanySummary'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '401':
          description: Unauthorized
          content:
            application/json: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
    post:
      tags:
      - Companies
      summary: Create a company
      description: '

        ### Creates a company from the supplied fields and returns the full record.

        A `name` is required. New tags are created automatically. A create that matches a company already on the

        account — by name, or by one of the supplied email domains — returns `409` and creates nothing. An email

        domain that cannot identify a company (a free-email provider, a malformed host, or any domain when the

        account has company-domain matching disabled) is rejected with `400` rather than silently dropped. Unknown

        or read-only fields are rejected, and the company is stored exactly as supplied — no enrichment is applied.



        **Required Scope:** `levitate:contacts`'
      operationId: CreateCompany
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyWrite'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CompanyWrite'
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CompanyWrite'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResultOfCompany'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '401':
          description: Unauthorized
          content:
            application/json: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResult'
components:
  schemas:
    Company:
      type: object
      properties:
        name:
          type:
          - 'null'
          - string
          description: Display name of the company
        description:
          type:
          - 'null'
          - string
          description: Description of the company
        emailDomains:
          type:
          - 'null'
          - array
          items:
            type: string
          description: List of email domains associated with the company, eg. example.com
        webSite:
          type:
          - 'null'
          - string
          description: Url to the company's website
        logoUrl:
          type:
          - 'null'
          - string
          description: Url to a display logo for the company and should point to an image file
        phoneNumbers:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          description: A list of phone numbers for this company that do not tie to a specific contact
        keyFactsCollection:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/CompanyKeyFact'
          description: A collection of key facts, which are a unique piece of information about a company that you can reference to appear personable and genuine.
        tags:
          type:
          - 'null'
          - array
          items:
            type: string
          description: A list of values that can be used to help group companies and contacts together for easier management and search
        address:
          allOf:
          - $ref: '#/components/schemas/Address'
          description: A physical or mailing address associated with this company
        id:
          type:
          - 'null'
          - string
          description: Unique identifier generated by Levitate
    PhoneNumber:
      required:
      - value
      type: object
      properties:
        label:
          type:
          - 'null'
          - string
          description: The type of phone number, eg. Home, Mobile, etc.
        value:
          type:
          - 'null'
          - string
          description: Unformatted value of the phone number
        metadata:
          allOf:
          - $ref: '#/components/schemas/PhoneNumberMetadata'
          description: Extra metadata and formatting options for the phone number
        canSMS:
          allOf:
          - $ref: '#/components/schemas/Capability'
          description: 'Can this phone number receive text messages: Unknown, Yes, No, Maybe, Opted out. Server-owned — learned from real send outcomes; any value sent on a write is ignored.'
    CompanyWrite:
      type: object
      properties:
        name:
          maxLength: 200
          minLength: 0
          type:
          - 'null'
          - string
          description: Display name of the company
        description:
          maxLength: 5000
          minLength: 0
          type:
          - 'null'
          - string
          description: Description of the company
        emailDomains:
          maxItems: 25
          type:
          - 'null'
          - array
          items:
            type: string
          description: List of email domains associated with the company, eg. example.com. A domain already claimed by another company is rejected.
        webSite:
          maxLength: 2048
          minLength: 0
          type:
          - 'null'
          - string
          description: Url to the company's website
        logoUrl:
          maxLength: 2048
          minLength: 0
          type:
          - 'null'
          - string
          description: Url to a display logo for the company and should point to an image file
        phoneNumbers:
          maxItems: 25
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          description: A list of phone numbers for this company that do not tie to a specific contact. Each value is capped at 50 characters and each label at 50.
        tags:
          maxItems: 50
          type:
          - 'null'
          - array
          items:
            type: string
          description: A list of values used to group companies and contacts; new tags are created automatically. Each tag name is capped at 100 characters.
        address:
          allOf:
          - $ref: '#/components/schemas/Address'
          description: A physical or mailing address associated with this company. Address lines are capped at 200 characters; city, state/province, and country at 100; postal code at 20.
      additionalProperties: false
    OperationResultOfPagedCollectionOfCompanySummary:
      type: object
      properties:
        success:
          type: boolean
        systemMessage:
          type:
          - 'null'
          - string
        systemCode:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        error:
          $ref: '#/components/schemas/ITechnicalError'
        requestId:
          type:
          - 'null'
          - string
        value:
          $ref: '#/components/schemas/PagedCollectionOfCompanySummary'
    Address:
      type: object
      properties:
        address1:
          type:
          - 'null'
          - string
          description: Street Address - First Line
        address2:
          type:
          - 'null'
          - string
          description: Street Address - Second Line
        city:
          type:
          - 'null'
          - string
          description: City name
        stateProvince:
          type:
          - 'null'
          - string
          description: State or Province - Code or full name allowed
        postalCode:
          type:
          - 'null'
          - string
          description: Postal zip code
        country:
          type:
          - 'null'
          - string
          description: Country of the address - Code or full name allowed
    ITechnicalError:
      type: object
      properties:
        errorMessage:
          type:
          - 'null'
          - string
        timestamp:
          type: string
          format: date-time
        source:
          type:
          - 'null'
          - string
        errorCode:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int64
        category:
          type:
          - 'null'
          - string
    PhoneNumberMetadata:
      type: object
      properties:
        e164:
          type:
          - 'null'
          - string
          description: The international standard E.164 formatted string
        standard:
          type:
          - 'null'
          - string
          description: A localized standard of formatting based on the country code, eg. (919) 555-3333
        countryCode:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Country code for the phone number, eg. 1 for US based phone numbers
          format: int32
        extension:
          type:
          - 'null'
          - string
          description: An optional number that is an extension to be keyed after the main number to reach the phone
    CompanySummary:
      type: object
      properties:
        url:
          type:
          - 'null'
          - string
          description: Path to the company's full record
        name:
          type:
          - 'null'
          - string
          description: Display name of the company
        webSite:
          type:
          - 'null'
          - string
          description: Url to the company's website
        logoUrl:
          type:
          - 'null'
          - string
          description: Url to a display logo for the company
        emailDomains:
          type:
          - 'null'
          - array
          items:
            type: string
          description: List of email domains associated with the company, eg. example.com
        tags:
          type:
          - 'null'
          - array
          items:
            type: string
          description: A list of values that can be used to help group companies and contacts together for easier management and search
        creationDate:
          type:
          - 'null'
          - string
          description: Date/time this company was created in ISO 8601 format
          format: date-time
        id:
          type:
          - 'null'
          - string
          description: Unique identifier generated by Levitate
    OperationResultOfCompany:
      type: object
      properties:
        success:
          type: boolean
        systemMessage:
          type:
          - 'null'
          - string
        systemCode:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        error:
          $ref: '#/components/schemas/ITechnicalError'
        requestId:
          type:
          - 'null'
          - string
        value:
          $ref: '#/components/schemas/Company'
    Capability:
      enum:
      - 'Yes'
      - 'No'
      - Maybe
      - OptOut
      - Unknown
    OperationResult:
      type: object
      properties:
        success:
          type: boolean
        systemMessage:
          type:
          - 'null'
          - string
        systemCode:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        error:
          $ref: '#/components/schemas/ITechnicalError'
        requestId:
          type:
          - 'null'
          - string
    CompanyKeyFact:
      type: object
      properties:
        value:
          type:
          - 'null'
          - string
          description: Display value for the Key Fact
        creatorId:
          type:
          - 'null'
          - string
          description: The unique identifier of the user who created this key fact
        creationDate:
          type:
          - 'null'
          - string
          description: Date/time this was created in ISO 8601 format
          format: date-time
        lastModifiedDate:
          type:
          - 'null'
          - string
          description: Date/time this was last modified in ISO 8601 format
          format: date-time
        id:
          type:
          - 'null'
          - string
          description: Unique identifier generated by Levitate
    CompanyPatch:
      type: object
      properties:
        name:
          maxLength: 200
          type: string
          description: Display name of the company; it may be changed but not cleared
        description:
          maxLength: 5000
          type: string
          description: Description of the company
        emailDomains:
          maxItems: 25
          type: array
          items:
            type: string
          description: List of email domains associated with the company, eg. example.com. A provided array replaces the existing domains; a domain already claimed by another company is rejected.
        webSite:
          maxLength: 2048
          type: string
          description: Url to the company's website
        logoUrl:
          maxLength: 2048
          type: string
          description: Url to a display logo for the company and should point to an image file
        phoneNumbers:
          maxItems: 25
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          description: A list of phone numbers for this company that do not tie to a specific contact. A provided array replaces the existing numbers. Each value is capped at 50 characters and each label at 50.
        tags:
          maxItems: 50
          type: array
          items:
            type: string
          description: A list of values used to group companies and contacts; new tags are created automatically. A provided array replaces the existing tags. Each tag name is capped at 100 characters.
        address:
          $ref: '#/components/schemas/Address'
      additionalProperties: false
    PagedCollectionOfCompanySummary:
      type: object
      properties:
        values:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/CompanySummary'
        pageToken:
          type:
          - 'null'
          - string
        totalCount:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int64
        debug: {}
  securitySchemes:
    OAuth2:
      type: oauth2
      description: Levitate OAuth2 Authorization Flow
      flows:
        authorizationCode:
          authorizationUrl: https://login.levitate.ai/oauth2/authorize
          tokenUrl: https://login.levitate.ai/oauth2/token
          scopes:
            levitate:contacts: Access Levitate contacts and related operations
            levitate:campaigns: Access Levitate campaigns and related operations