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

# Create Contact

> Create a new contact with optional attribution tracking.

<Note>
  This endpoint supports both authenticated and public modes. Omit the API key for lead capture forms (rate limited to 20 req/min per IP).
</Note>

## Request Fields

| Field          | Required | Description       |
| -------------- | -------- | ----------------- |
| `first_name`   | Yes      | First name        |
| `last_name`    | Yes      | Last name         |
| `email`        | \*       | Email address     |
| `phone`        | \*       | Phone number      |
| `company`      | No       | Company name      |
| `notes`        | No       | Additional notes  |
| `utm_source`   | No       | Traffic source    |
| `utm_medium`   | No       | Marketing medium  |
| `utm_campaign` | No       | Campaign name     |
| `referral_url` | No       | Referral page URL |

<Note>\* At least one of `email` or `phone` is required.</Note>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.stover.app/v1/contacts \
    -H "Authorization: Bearer stover_pk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "company": "Acme Inc",
      "utm_source": "linkedin"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.stover.app/v1/contacts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer stover_pk_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      first_name: 'Jane',
      last_name: 'Doe',
      email: 'jane@example.com',
      company: 'Acme Inc',
      utm_source: 'linkedin'
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.stover.app/v1/contacts',
      headers={
          'Authorization': 'Bearer stover_pk_your_api_key',
          'Content-Type': 'application/json'
      },
      json={
          'first_name': 'Jane',
          'last_name': 'Doe',
          'email': 'jane@example.com',
          'company': 'Acme Inc',
          'utm_source': 'linkedin'
      }
  )
  ```
</CodeGroup>


## OpenAPI

````yaml POST /v1/contacts
openapi: 3.1.0
info:
  title: Stover API
  description: API for managing contacts and social media posts
  version: 1.0.0
  contact:
    email: support@stover.app
servers:
  - url: https://api.stover.app
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/contacts:
    post:
      tags:
        - Contacts
      summary: Create Contact
      description: Create a new contact with optional attribution tracking.
      operationId: createContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactRequest'
      responses:
        '201':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - {}
        - bearerAuth: []
components:
  schemas:
    ContactRequest:
      type: object
      required:
        - first_name
        - last_name
      properties:
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
        email:
          type: string
          description: Email (required if no phone)
        phone:
          type: string
          description: Phone (required if no email)
        company:
          type: string
        notes:
          type: string
        utm_source:
          type: string
        utm_medium:
          type: string
        utm_campaign:
          type: string
        referral_url:
          type: string
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key: Bearer stover_pk_...'

````