openapi: 3.0.3
info:
  title: PayDai API
  description: |
    The commission and revenue platform API for high-performance sales teams.
    Connect PayDai to any tool  -  Zapier, Make, HubSpot, TypeForm, or a custom workflow  -  in minutes.

    ## Authentication

    Every request requires a Bearer token. Use your `pd_live_...` key from Settings → Developer.

    ```
    Authorization: Bearer YOUR_API_KEY
    ```

    Generate your API key at **Settings → Developer** inside [app.itspaydai.com](https://api.itspaydai.com).
  version: v1
  contact:
    name: PayDai Support
    email: support@itspaydai.com
    url: https://api.itspaydai.com

servers:
  - url: https://api.itspaydai.com
    description: Production

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Your PayDai API key (`pd_live_...`). Generate one at **Settings → Developer** in your dashboard.

  schemas:
    Lead:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique lead ID.
          example: 5c888b75-3a29-4cbd-b200-cf57886352a8
        name:
          type: string
          description: Lead's full name.
          example: John
        email:
          type: string
          format: email
          description: Lead's email address.
          example: john@xyz.com
        phone:
          type: string
          description: Lead's phone number.
          example: "8149958193"
        stage:
          type: string
          description: Current stage  -  always `lead` on creation.
          example: lead
        setter:
          type: string
          description: Full name of the assigned setter.
          example: jay test Closer
        setterId:
          type: string
          format: uuid
          description: User ID of the assigned setter.
          example: c3a969b3-6a9a-4d6c-9a1a-e13890501f6a
        description:
          type: string
          description: Notes about the lead.
          example: This is lead synced from lead api

    Member:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Member record ID  -  pass this as `setter` when creating a lead.
          example: bb7668f0-42a1-4268-aab7-dbad7dbf002b
        userId:
          type: string
          format: uuid
          description: User account ID.
          example: c3a969b3-6a9a-4d6c-9a1a-e13890501f6a
        firstName:
          type: string
          example: jay
        lastName:
          type: string
          example: test Closer
        email:
          type: string
          format: email
          example: jay+testcloser@itspaydai.com
        roles:
          type: array
          items:
            type: object
            properties:
              roleId:
                type: string
                example: setter
              role:
                type: string
                example: Setter
        isActive:
          type: boolean
          example: true
        workspaceId:
          type: string
          format: uuid
          example: 7c448c98-390c-4994-abe8-21d0f7b899a8

    ErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: Unauthorized

security:
  - BearerAuth: []

tags:
  - name: Leads
    description: Create and manage leads in your PayDai workspace.
  - name: Members
    description: Query team members to look up setter IDs.

paths:
  /api/v1/biz/leads/:
    post:
      summary: Create Lead
      description: |
        Push a lead into your PayDai workspace from any external source. Closers get it instantly.

        **Idempotency:** Pass a unique `Idempotency-Key` header to safely retry without creating duplicate leads. Repeating the same key returns the original response without creating a duplicate.
      operationId: createLead
      tags:
        - Leads
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: A unique string per request. Retrying with the same key returns the original response without creating a duplicate lead.
          schema:
            type: string
            example: unique-request-id-123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Lead's full name.
                  example: John
                email:
                  type: string
                  format: email
                  description: Lead's email address.
                  example: john@xyz.com
                phone:
                  type: string
                  description: Lead's phone number.
                  example: "8149958193"
                description:
                  type: string
                  description: Notes about this lead.
                  example: This is lead synced from lead api
                setter:
                  type: string
                  format: uuid
                  description: Member `id` of the setter to assign this lead to (not the userId). Use the [Get Members](#tag/Members/GET/api/v1/biz/members/) endpoint to look up IDs.
                  example: bb7668f0-42a1-4268-aab7-dbad7dbf002b
            example:
              name: John
              email: john@xyz.com
              phone: "8149958193"
              description: This is lead synced from lead api
              setter: bb7668f0-42a1-4268-aab7-dbad7dbf002b
      responses:
        "201":
          description: Lead created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  statusCode:
                    type: string
                    example: OK
                  message:
                    type: string
                    example: "Success!"
                  data:
                    $ref: "#/components/schemas/Lead"
              example:
                status: true
                statusCode: OK
                message: "Success!"
                data:
                  id: 5c888b75-3a29-4cbd-b200-cf57886352a8
                  name: John
                  email: john@xyz.com
                  phone: "8149958193"
                  stage: lead
                  setter: jay test Closer
                  setterId: c3a969b3-6a9a-4d6c-9a1a-e13890501f6a
                  description: This is lead synced from lead api
        "400":
          description: Bad request  -  missing or invalid fields.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: false
                message: name is required
        "401":
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: false
                message: Unauthorized

  /api/v1/biz/members/:
    get:
      summary: Get Members
      description: Retrieve all active team members in your PayDai workspace. Use the member `id` (not `userId`) when creating leads to assign a setter.
      operationId: getMembers
      tags:
        - Members
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of workspace members.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Member"
              example:
                data:
                  - id: bb7668f0-42a1-4268-aab7-dbad7dbf002b
                    userId: c3a969b3-6a9a-4d6c-9a1a-e13890501f6a
                    firstName: jay
                    lastName: test Closer
                    email: jay+testcloser@itspaydai.com
                    roles:
                      - roleId: setter
                        role: Setter
                    isActive: true
                    workspaceId: 7c448c98-390c-4994-abe8-21d0f7b899a8
        "401":
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: false
                message: Unauthorized
