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

# Create Audience

> Creates a new audience



## OpenAPI

````yaml POST /audiences
openapi: 3.0.1
info:
  title: OpenAPI Letterby
  description: API for Letterby
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://letterby.com/api/v4
security:
  - apiKeyAuth: []
paths:
  /audiences:
    post:
      description: Creates a new audience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - listId
              properties:
                name:
                  type: string
                  description: Name of the audience
                listId:
                  type: string
                  description: ID of the list this audience belongs to
                filters:
                  type: string
                  description: >-
                    JSON string containing Prisma where clause for Sub model.
                    Required if mode is 'smart'
                  example: >-
                    {"points": {"gte": 100}, "AND": [{"email": {"contains":
                    "@gmail.com"}}]}
                mode:
                  type: string
                  description: Audience mode
                  default: manual
                  enum:
                    - manual
                    - smart
      responses:
        '201':
          description: Audience created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      audience:
                        $ref: '#/components/schemas/Audience'
        '400':
          description: Bad request - Invalid filters or missing required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Name and listId are required
                      - Filters are required for smart mode
                      - >-
                        Invalid filters format. Must be a valid Prisma where
                        clause for Sub model
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Audience:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the audience
        name:
          type: string
          description: Name of the audience
        filters:
          type: string
          description: JSON string containing Prisma where clause for filtering contacts
        mode:
          type: string
          description: Audience mode (smart or manual)
          default: smart
          enum:
            - smart
            - manual
        listId:
          type: string
          description: ID of the list this audience belongs to
        createdAt:
          type: string
          format: date-time
          description: When the audience was created
        updatedAt:
          type: string
          format: date-time
          description: When the audience was last updated
        subs:
          type: array
          description: Contacts in this audience
          items:
            $ref: '#/components/schemas/Contact'
    Contact:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the contact
        email:
          type: string
          description: Email address of the contact
        firstName:
          type: string
          description: First name of the contact
        lastName:
          type: string
          description: Last name of the contact
        phoneNumber:
          type: string
          description: Phone number of the contact
        createdAt:
          type: string
          format: date-time
          description: When the contact was created
        points:
          type: integer
          description: Points accumulated by the contact
        referrals:
          type: integer
          description: Number of referrals by the contact
        listId:
          type: string
          description: ID of the list this contact belongs to
        isVerified:
          type: boolean
          description: Whether the contact is verified
        unsubscribed:
          type: boolean
          description: Whether the contact has unsubscribed
        data:
          type: object
          description: Custom data associated with the contact
        address:
          type: string
          description: Contact's address
        isGDPR:
          type: boolean
          description: Whether the contact has GDPR consent
        name:
          type: string
          description: Full name of the contact
        instagram:
          type: string
          description: Instagram handle
        twitter:
          type: string
          description: Twitter handle
        website:
          type: string
          description: Personal website URL
        company:
          type: string
          description: Company name
        country:
          type: string
          description: Country of residence
        city:
          type: string
          description: City of residence
        list:
          type: object
          description: Associated list information
          properties:
            id:
              type: string
              description: List ID
            name:
              type: string
              description: List name
            url:
              type: string
              description: List URL identifier
            mode:
              type: string
              description: List mode
            referrals:
              type: boolean
              description: Whether referrals are enabled
            color:
              type: string
              description: List primary color
            title:
              type: string
              description: List title
            desc:
              type: string
              description: List description
        audiences:
          type: array
          description: Audiences this contact belongs to
        referralLink:
          type: string
          description: Contact's referral link
        privateLink:
          type: string
          description: Contact's private subscriber page URL
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized - Invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: apiKey
      description: API key to authorize requests

````