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

# Create a ticket

> Opens a ticket for a customer who has chatted with you, found by your `userId` (linked through the Context API) or their `phone`. It's linked to their latest chat. Unless `notifyCustomer` is false, the customer is told in that chat, and your ticket webhook gets `ticket.created`.



## OpenAPI

````yaml /openapi.yaml post /tickets
openapi: 3.1.0
info:
  title: Frictionless API
  version: '1.0'
  description: >-
    Send who your customers are and what just happened to them, so agents see it
    beside the chat. Open and move tickets from your own systems.
servers:
  - url: https://api.usefrictionless.com/api/v1
security:
  - apiKey: []
tags:
  - name: Contacts
  - name: Events
  - name: Tickets
paths:
  /tickets:
    post:
      tags:
        - Tickets
      summary: Create a ticket
      description: >-
        Opens a ticket for a customer who has chatted with you, found by your
        `userId` (linked through the Context API) or their `phone`. It's linked
        to their latest chat. Unless `notifyCustomer` is false, the customer is
        told in that chat, and your ticket webhook gets `ticket.created`.
      operationId: createTicket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subject
                - customer
              properties:
                customer:
                  type: object
                  description: Send `userId` or `phone`.
                  properties:
                    userId:
                      type: string
                      example: user_42
                    phone:
                      type: string
                      example: '+2348012345678'
                subject:
                  type: string
                  maxLength: 140
                  example: Refund for order 381
                description:
                  type: string
                  maxLength: 4000
                  example: Charged twice on 3 November.
                type:
                  type: string
                  maxLength: 30
                  example: Refund
                priority:
                  $ref: '#/components/schemas/Priority'
                status:
                  $ref: '#/components/schemas/Status'
                dueAt:
                  type:
                    - string
                    - 'null'
                  format: date-time
                  example: '2026-11-07T17:00:00Z'
                notifyCustomer:
                  type: boolean
                  default: true
                  description: >-
                    false opens the ticket without messaging the customer, now
                    or when it moves later.
      responses:
        '201':
          description: The new ticket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    $ref: '#/components/schemas/Ticket'
        '400':
          $ref: '#/components/responses/InvalidTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PlanRequired'
        '404':
          description: >-
            `customer_not_found`: nobody with that userId or phone has chatted
            with you yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Priority:
      type: string
      enum:
        - low
        - normal
        - high
        - urgent
      example: high
    Status:
      type: string
      enum:
        - new
        - in_progress
        - waiting
        - resolved
      example: in_progress
    Ticket:
      type: object
      properties:
        id:
          type: string
          description: The ticket's number.
          example: NE-1042
        ticketId:
          type: string
          example: c0a8f3e2-5b1d-4f7e-9a3c-1e2d3f4a5b6c
        subject:
          type: string
          example: Refund for order 381
        description:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
          example: Refund
        priority:
          $ref: '#/components/schemas/Priority'
        status:
          $ref: '#/components/schemas/Status'
        dueAt:
          type:
            - string
            - 'null'
          format: date-time
        resolvedAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
          example: '2026-11-04T09:12:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-11-05T10:00:00Z'
        notifyCustomer:
          type: boolean
          example: true
        customer:
          type: object
          properties:
            name:
              type:
                - string
                - 'null'
              example: Ada Obi
            channel:
              type:
                - string
                - 'null'
              description: Where they last chatted, like whatsapp, instagram or widget.
              example: whatsapp
            phone:
              type:
                - string
                - 'null'
              example: '+2348012345678'
            email:
              type:
                - string
                - 'null'
            userId:
              type:
                - string
                - 'null'
              description: Your own ID, when linked through the Context API.
              example: user_42
        owner:
          type:
            - object
            - 'null'
          properties:
            name:
              type: string
              example: Kemi
        chatUrl:
          type:
            - string
            - 'null'
          description: The customer's chat in Frictionless.
        url:
          type: string
          example: https://usefrictionless.com/tickets/NE-1042
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
              description: Says what to fix.
  responses:
    InvalidTicket:
      description: >-
        `invalid_ticket`: a missing subject, or a status, priority or date we
        can't read. The message says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: '`missing_key` or `invalid_key`: no API key, or one that was rotated.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PlanRequired:
      description: '`plan_required`: the API is on the Pro plan and above.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: '`rate_limited`: over 300 requests a minute. Wait and retry.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Your API key (`fk_live_…`) from Settings → Developers.

````

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