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

# Create a company

> Create a new company in your CRM.



## OpenAPI

````yaml https://app.alvahq.com/api/v1/openapi post /api/v1/companies
openapi: 3.1.0
info:
  title: Alva API
  version: 1.0.0
  description: >
    The Alva API provides programmatic access to your CRM data. Use it to
    integrate Alva with other applications, build custom workflows, or connect
    via platforms like Zapier.


    ## Authentication


    All API requests require a valid API key passed as a Bearer token:


    ```

    Authorization: Bearer alva_sk_your_api_key_here

    ```


    API keys can be created and managed in **Settings > Developer** within the
    Alva application.


    ## Rate Limiting


    API requests are rate limited to **100 requests per minute** per API key.
    Rate limit information is included in response headers:


    - `X-RateLimit-Limit` - Maximum requests per minute

    - `X-RateLimit-Remaining` - Requests remaining in current window

    - `X-RateLimit-Reset` - Unix timestamp when the window resets


    ## Pagination


    List endpoints support pagination via query parameters:


    - `page` - Page number (default: 1)

    - `limit` - Items per page (default: 25, max: 100)


    ## Sorting


    List endpoints support sorting:


    - `sort` - Sort field and direction, e.g. `sort=createdAt:desc`


    ## Errors


    All errors follow a consistent format:


    ```json

    {
      "error": "Error Type",
      "message": "Human-readable description",
      "details": { "field": ["Validation message"] }
    }

    ```
  contact:
    name: Alva Support
    url: https://alva.ai
servers:
  - url: https://app.alvahq.com
    description: Current environment
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Manage companies in your CRM
  - name: Contacts
    description: Manage contacts and people
  - name: Deals
    description: Manage sales deals and pipeline
  - name: Activities
    description: Log and track activities (calls, meetings, emails, etc.)
  - name: Pipeline
    description: Pipeline stages and methodology metadata
  - name: Custom Fields
    description: Define custom fields on companies and contacts
  - name: Email Templates
    description: >-
      Manage email templates and template groups. Use {{company.custom.<key>}}
      merge tags in subject and body.
  - name: Account
    description: API key, account members and company tags
  - name: BDR Agents
    description: List BDR agents and assign a company to one
paths:
  /api/v1/companies:
    post:
      tags:
        - Companies
      summary: Create a company
      description: Create a new company in your CRM.
      operationId: createCompany
      requestBody:
        required: true
        description: >-
          Fields marked "required" must be provided; all others are optional. In
          the interactive playground (the "Test Request" panel) the JSON body is
          fully editable — type over any value and delete the properties you
          don't need. Blank fields are ignored, so only the values you provide
          are sent.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompany'
      responses:
        '200':
          description: Company
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    description: Human-readable confirmation of the action.
                  data:
                    $ref: '#/components/schemas/Company'
                  resource:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorised'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CreateCompany:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        domain:
          type: string
          nullable: true
        industry:
          type: string
          nullable: true
        size:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        website:
          type: string
          format: uri
          nullable: true
        description:
          type: string
          nullable: true
        lifecycleStage:
          type: string
          nullable: true
          enum:
            - target
            - prospect
            - lead
            - customer
            - evaluating
            - engaging
            - negotiating
            - vendor
            - partner
            - supplier
        relationshipType:
          type: string
          nullable: true
          enum:
            - customer
            - vendor
            - partner
            - supplier
            - competitor
        primaryEmail:
          type: string
          format: email
          nullable: true
        primaryPhone:
          type: string
          nullable: true
        emails:
          type: array
          items:
            type: string
            format: email
        phones:
          type: array
          items:
            type: string
        linkedinUrl:
          type: string
          format: uri
          nullable: true
        foundedYear:
          type: integer
          nullable: true
        employeeCountRange:
          type: string
          nullable: true
        ownerId:
          type: string
          format: uuid
          nullable: true
        enrichmentIcpId:
          type: string
          format: uuid
          nullable: true
        tagIds:
          type: array
          items:
            type: string
            format: uuid
          description: Replaces the company tags. Omit to leave tags unchanged.
        notInterestedUntil:
          type: string
          format: date-time
          nullable: true
          description: Null clears the hold.
        notInterestedReason:
          type: string
          nullable: true
        customFields:
          type: object
      example:
        name: ''
        domain: ''
        industry: ''
        size: ''
        location: ''
        website: ''
        description: ''
        lifecycleStage: ''
        relationshipType: ''
        primaryEmail: ''
        primaryPhone: ''
        emails: []
        phones: []
        linkedinUrl: ''
        foundedYear: null
        employeeCountRange: ''
        ownerId: ''
        enrichmentIcpId: ''
        tagIds: []
        notInterestedUntil: ''
        notInterestedReason: ''
        customFields: {}
    Company:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Acme Corporation
        domain:
          type: string
          nullable: true
          example: acme.com
        industry:
          type: string
          nullable: true
          example: Technology
        size:
          type: string
          nullable: true
          example: 51-200
        location:
          type: string
          nullable: true
          example: London, UK
        website:
          type: string
          nullable: true
          example: https://acme.com
        description:
          type: string
          nullable: true
        lifecycleStage:
          type: string
          nullable: true
          enum:
            - target
            - prospect
            - lead
            - customer
            - evaluating
            - engaging
            - negotiating
            - vendor
            - partner
            - supplier
        relationshipType:
          type: string
          nullable: true
          enum:
            - customer
            - vendor
            - partner
            - supplier
            - competitor
        primaryEmail:
          type: string
          nullable: true
        primaryPhone:
          type: string
          nullable: true
        emails:
          type: array
          items:
            type: string
        phones:
          type: array
          items:
            type: string
        linkedinUrl:
          type: string
          nullable: true
        foundedYear:
          type: integer
          nullable: true
        employeeCountRange:
          type: string
          nullable: true
        ownerId:
          type: string
          format: uuid
          nullable: true
          description: Active account member. See GET /api/v1/users.
        enrichmentIcpId:
          type: string
          format: uuid
          nullable: true
        originalName:
          type: string
          nullable: true
          readOnly: true
        customFields:
          type: object
          nullable: true
        enrichmentStatus:
          type: string
          nullable: true
          readOnly: true
        enrichmentQueuedAt:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        enrichmentCompletedAt:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        lastEnrichedAt:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        websiteSummary:
          type: string
          nullable: true
          readOnly: true
        linkedinSummary:
          type: string
          nullable: true
          readOnly: true
        emailPattern:
          type: string
          nullable: true
          readOnly: true
        technologies:
          nullable: true
          readOnly: true
        socialProfiles:
          nullable: true
          readOnly: true
        discoverySourceId:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        inboundSource:
          type: string
          nullable: true
          readOnly: true
        createdById:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        notInterestedUntil:
          type: string
          format: date-time
          nullable: true
        notInterestedReason:
          type: string
          nullable: true
        notInterestedAt:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        tags:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/CompanyTag'
        bdrOutreach:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/CompanyBdrOutreach'
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    CompanyTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: string
          nullable: true
    CompanyBdrOutreach:
      type: object
      properties:
        id:
          type: string
          format: uuid
        agentId:
          type: string
          format: uuid
          nullable: true
        agentName:
          type: string
          nullable: true
        status:
          type: string
        lastActivityAt:
          type: string
          format: date-time
          nullable: true
          description: Latest BDR action or email on this assignment.
        nextActionNote:
          type: string
          nullable: true
        nextActionNoteSource:
          type: string
          nullable: true
        nextEvaluationAt:
          type: string
          format: date-time
          nullable: true
        waitForEnrichment:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: object
          nullable: true
  responses:
    Unauthorised:
      description: Authentication failed - invalid, expired, or revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorised
            message: Invalid or revoked API key
    ValidationError:
      description: Request body validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unprocessable Entity
            message: Validation failed
            details:
              name:
                - Name is required
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Too Many Requests
            message: Rate limit exceeded. Maximum 100 requests per minute.
            retryAfter: 30
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until rate limit resets
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key from Settings > Developer. Format: alva_sk_...'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.