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

# Create a draft invoice

> Create a new invoice if no id is supplied, otherwise update existing invoice with supplied id



## OpenAPI

````yaml https://dev.hurdlr.com/rest/v1/devUtils/documentation?version=4&Authorization=dexfeE6aRK3zwXP4ku5aWm8w&env=sandbox post /v4/invoicing/invoice
openapi: 3.0.1
info:
  title: Tight API
  contact:
    name: Hurdlr, Inc. (dba Tight)
    url: https://www.tight.com
    email: api@tight.com
  version: 6.0.0
servers:
  - url: https://sandbox.hurdlr.com/rest
    description: Staging Environment
  - url: https://prod.hurdlr.com/rest
    description: Production Environment
security:
  - accessTokenSecurity: []
  - basicSecurity: []
tags:
  - name: Authentication
  - name: Banks
  - name: Expenses
  - name: Revenue
  - name: Business & Client Management
  - name: Invoicing
  - name: Reports
  - name: Taxes
  - name: Accounting
  - name: Investment Incomes
paths:
  /v4/invoicing/invoice:
    post:
      tags:
        - Invoicing
      summary: Create a draft invoice
      description: >-
        Create a new invoice if no id is supplied, otherwise update existing
        invoice with supplied id
      operationId: postInvoiceV4
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceCreationRetVal'
      security:
        - accessTokenSecurity: []
components:
  schemas:
    InvoiceCreationRetVal:
      type: object
      properties:
        invoiceResult:
          type: string
          enum:
            - SUCCESS
            - FAILURE_INVALID_INVOICE
            - WORKITEMS_ALREADY_INVOICED
            - FAILURE_ZERO_AMOUNT
            - PAYMENT_NOT_SETUP
            - FAILURE_OTHER
        cloudStorageRetVal:
          $ref: '#/components/schemas/CloudStorageRetVal'
        emailStatus:
          type: string
          enum:
            - SUCCESS
            - FAILURE_TOKEN_INVALIDATED
            - FAILURE_TOKEN_POSSIBLY_EXPIRED
            - FAILURE_INVOICE_NOT_FOUND
            - FAILURE_OTHER
            - SENDING
            - NOT_SENT
            - FAILURE_BOUNCED
            - WARNING_AUTO_RESPONSE
        result:
          type: string
          enum:
            - SUCCESS
            - FAILURE_INVOICE
            - FAILURE_CLOUDSTORAGE
            - FAILURE_EMAIL
            - FAILURE_OTHER
        message:
          type: string
        errors:
          $ref: '#/components/schemas/ValidationRetVal'
        htmlReport:
          type: string
        invoiceId:
          type: string
        newlyCreatedInvoiceId:
          type: string
        invoiceNo:
          type: integer
          format: int32
        webhook:
          $ref: '#/components/schemas/EntityUpdateEvent'
        invoiceRetVal:
          $ref: '#/components/schemas/InvoiceRetVal'
    CloudStorageRetVal:
      type: object
      properties:
        url:
          type: string
        fileName:
          type: string
        result:
          type: string
          enum:
            - SUCCESS
            - FAILURE_CLOUDSTORAGE_NOT_SETUP
            - FAILURE_UPLOAD_ERROR
            - MASTER_SUCCESS_PERSONAL_FAILURE_UPLOAD_ERROR
            - FAILURE_NO_DATA
            - FAILURE_TOKEN_INVALIDATED
            - FAILURE_EMAIL_TOKEN_INVALIDATED
            - FAILURE_UNKNOWN_ERROR
            - FAILURE_USER_OVER_QUOTA
            - FAILURE_VALIDATION_ERROR
        htmlReport:
          type: string
        jsonReport:
          type: object
        cloudStorageResult:
          type: string
          writeOnly: true
          enum:
            - SUCCESS
            - FAILURE_CLOUDSTORAGE_NOT_SETUP
            - FAILURE_UPLOAD_ERROR
            - MASTER_SUCCESS_PERSONAL_FAILURE_UPLOAD_ERROR
            - FAILURE_NO_DATA
            - FAILURE_TOKEN_INVALIDATED
            - FAILURE_EMAIL_TOKEN_INVALIDATED
            - FAILURE_UNKNOWN_ERROR
            - FAILURE_USER_OVER_QUOTA
            - FAILURE_VALIDATION_ERROR
    ValidationRetVal:
      type: object
      properties:
        fieldErrors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValidationError'
          description: Map of field-level errors, often originating from validation errors
        globalErrors:
          type: array
          description: List of higher-level errors
          items:
            $ref: '#/components/schemas/ValidationError'
      description: Error object containing details errors incurred, if any
    EntityUpdateEvent:
      type: object
      properties:
        userId:
          type: string
        accountantUserId:
          type: string
        type:
          type: string
          enum:
            - ENTITY_UPDATE
            - LIFECYCLE_EVENT
            - LIFECYCLE
    InvoiceRetVal:
      type: object
      properties:
        xml:
          type: string
        id:
          type: string
        name:
          type: string
        totalAmount:
          type: number
        term:
          type: string
          enum:
            - DUE_NOW
            - NET_10
            - NET_15
            - NET_30
            - NET_60
            - OTHER
        result:
          type: string
          enum:
            - SUCCESS
            - FAILURE_INVALID_INVOICE
            - WORKITEMS_ALREADY_INVOICED
            - FAILURE_ZERO_AMOUNT
            - PAYMENT_NOT_SETUP
            - FAILURE_OTHER
        invoice:
          $ref: '#/components/schemas/ArInvoice'
        logoUrl:
          type: string
        invoiceReport:
          $ref: '#/components/schemas/InvoiceReport'
        invoiceStatus:
          type: string
          enum:
            - OPEN
            - CLOSED
            - CANCELLED
            - DRAFT
            - REFUNDED
            - SCHEDULED
        isDraftInvoice:
          type: boolean
    ValidationError:
      type: object
      properties:
        type:
          type: string
          description: A broad categorization of the error
          enum:
            - DUPLICATE
            - REQUIRED
            - DELETE
            - INVALID_VALUE
            - NOT_MODIFIABLE
            - GENERAL
            - INVALID_FORMAT
        errorMessage:
          type: string
          description: Human-friendly message describing this error
        message:
          type: string
          writeOnly: true
          enum:
            - DUPLICATE
            - REQUIRED
            - DELETE
            - INVALID_VALUE
            - NOT_MODIFIABLE
            - GENERAL
            - INVALID_FORMAT
            - INVALID_MAPPING
      description: List of higher-level errors
    ArInvoice:
      type: object
      properties:
        id:
          type: string
        business:
          $ref: '#/components/schemas/Business'
        businessId:
          type: integer
          format: int64
        companyId:
          type: string
        companyIdLong:
          type: integer
          format: int64
        customerPartnerId:
          type: integer
          format: int64
        createdDatetime:
          type: string
          format: date-time
        name:
          type: string
        date:
          type: string
          format: date-time
        totalAmount:
          type: number
        invoiceStatus:
          type: string
          enum:
            - OPEN
            - CLOSED
            - CANCELLED
            - DRAFT
            - REFUNDED
            - SCHEDULED
        discountAmount:
          type: number
        discountPercent:
          type: number
        invoiceTerm:
          type: string
          enum:
            - DUE_NOW
            - NET_10
            - NET_15
            - NET_30
            - NET_60
            - OTHER
        dueDate:
          type: string
          format: date-time
        email:
          type: string
        invoiceNo:
          type: integer
          format: int32
        message:
          type: string
        propertyId:
          type: string
        lastReminderDate:
          type: string
          format: date-time
        emailStatus:
          type: string
          enum:
            - SUCCESS
            - FAILURE_TOKEN_INVALIDATED
            - FAILURE_TOKEN_POSSIBLY_EXPIRED
            - FAILURE_INVOICE_NOT_FOUND
            - FAILURE_OTHER
            - SENDING
            - NOT_SENT
            - FAILURE_BOUNCED
            - WARNING_AUTO_RESPONSE
        clientId:
          type: string
        lastViewedDate:
          type: string
          format: date-time
        acceptCredit:
          type: boolean
        acceptCash:
          type: boolean
        reminderSchedule:
          type: string
        lastCreatedRecurringInvoice:
          type: string
          format: date-time
        parentId:
          type: string
        invoiceFrequency:
          type: string
          enum:
            - ONE_TIME
            - WEEKLY
            - BI_WEEKLY
            - MONTHLY
            - YEARLY
            - AFTER_TWO_MINS
        isRecurringParent:
          type: boolean
        refundStatus:
          type: string
          enum:
            - PENDING
            - SUCCEEDED
            - FAILED
            - UNKNOWN
        emailErrors:
          $ref: '#/components/schemas/JSONArray'
        sendEmail:
          type: boolean
        sentDate:
          type: string
          format: date-time
        billingInfoId:
          type: string
        paymentErrors:
          type: string
        acceptACH:
          type: boolean
        extensionId:
          type: string
        apiName:
          type: string
          enum:
            - GOOGLELOGIN
            - LINKEDINLOGIN
            - DROPBOX
            - BOX
            - SKYDRIVE
            - CLOVER
            - STRIPE
            - GOOGLESTORAGE
            - GOOGLECONTACTS
            - GOOGLEEMAIL
            - LINKEDINCONTACTS
            - PLAID
            - KNOX
            - UBER
            - FACEBOOKLOGIN
            - FRESHBOOKS
            - HARVEST
            - KW
            - FRESHBOOKS2
            - CAPITAL_ONE
            - SQUARE
            - S3
            - DOTLOOP
            - XERO_DEPRECATED
            - REALOGY
            - UPWORK
            - SHOPIFY
            - DEDUCTR
            - ENTERPRISE
            - MOXIWORKS
            - STRIPE_EXPRESS
            - APPLELOGIN
            - APPDIRECT
            - LONEWOLF
            - USER_IMPORTED
            - LONEWOLF_TRANSACTIONDESK
            - SAMPLE_BANK
            - TAXBOT
            - THIRD_PARTY_BANK
            - GUSTO
            - THIRD_PARTY_PAYMENTS
            - XERO
            - UNIT
            - USER_ENTRY
            - MOOV
            - QBO
            - COLUMN
            - QUALPAY
            - BENCH
            - PARTNER_IMPLEMENTATION
            - CHECK
            - RUTTER
            - WAVE
            - ADYEN
            - APRIL
            - PAYABLI
        apiInvoiceId:
          type: string
        installments:
          type: array
          items:
            $ref: '#/components/schemas/Installment'
        calculateSalesTaxBeforeDiscount:
          type: boolean
        glSourceId:
          type: integer
          format: int64
        source:
          type: string
          enum:
            - EXPENSE
            - REVENUE_ENTRY
            - BANK_TRANSFER
            - TAX_PAYMENT
            - AR_INVOICE_ITEM
            - AR_PAYMENT
            - PAYROLL
            - JOURNAL_ENTRY
            - TAX_ENTRY
            - AP_INVOICE_ITEM
            - AP_PAYMENT
            - BILL
            - AR_INVOICE
        ccemails:
          type: string
        bccemails:
          type: string
        invoicePrefix:
          type: string
        glAccountId:
          type: integer
          format: int64
        invoiceNumberDigitLength:
          type: integer
          format: int32
        paymentErrorsAsJsonArray:
          $ref: '#/components/schemas/JSONArray'
        lastCreatedRecurringExpense:
          type: string
          format: date-time
          writeOnly: true
        glAmount:
          type: number
        generalLedgerStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
        reviewStatus:
          type: string
          enum:
            - PARTNER_REVIEW_REQUIRED
            - USER_REVIEW_REQUIRED
            - ACCOUNTANT_REVIEW_REQUIRED
            - RECONCILIATION_STAGED
            - RECONCILED
            - RECONCILIATION_DISCREPANCY
            - ADJUSTMENT_USER_REVIEW_REQUIRED
            - ADJUSTMENT_ACCOUNTANT_REVIEW_REQUIRED
            - ADJUSTMENT_RECONCILIATION_STAGED
            - RECONCILIATION_AWAITING
        bankAccountId:
          type: integer
          format: int64
        parentEntityId:
          type: integer
          format: int64
        externalId:
          type: string
        idPrefix:
          type: string
          enum:
            - COMPANY
            - EMPLOYEE
            - DIMENSION_VALUE
            - CLASS_LABEL
            - CUSTOMER
            - BANK_ACCOUNT
            - GL_ACCOUNT
            - TRANSACTION_CATEGORY
            - BANK_TRANSACTION
            - PROCESSOR_TRANSACTION
            - TRANSACTION_LINE_ITEM
            - VENDOR
            - TRANSACTION_RULE
            - REVENUE_RULE
            - INVOICE
            - INVOICE_LINE_ITEM
            - BILL
            - BILL_LINE_ITEM
            - PAYROLL
            - PAYROLL_LINE_ITEM
            - FINANCIAL_SUMMARY
            - TASK
            - CONVERSATION
            - MESSAGE
            - REACTION
            - BUSINESS_TYPE
            - TEMPLATE_DIMENSION
            - TEMPLATE_COA
            - TEMPLATE_GL_ACCOUNT
            - TEMPLATE_TRANSACTION_RULES
            - MANUAL_JOURNAL_ENTRY
            - GL_TRANSACTION
            - ATTACHMENT
            - CAR
            - MILEAGE
            - INTEGRATION
            - TIME
            - TIME_TYPE
            - TAX_RETURN
    InvoiceReport:
      type: object
      properties:
        invoiceName:
          type: string
        invoiceNo:
          type: integer
          format: int32
        totalInvoiceAmount:
          type: number
        totalDiscountedInvoiceAmount:
          type: number
        personalNote:
          type: string
        dueDate:
          type: string
          format: date-time
        invoiceDate:
          type: string
          format: date-time
        discountAmount:
          type: number
        discountPercent:
          type: number
        invoiceTerm:
          type: string
        businessName:
          type: string
        showBusinessName:
          type: boolean
        businessLogoUrl:
          type: string
        businessCity:
          type: string
        businessState:
          type: string
        businessZip:
          type: string
        businessAddress1:
          type: string
        businessAddress2:
          type: string
        clientName:
          type: string
        companyName:
          type: string
        companyPhone:
          type: string
        businessPhone:
          type: string
        companyAddress1:
          type: string
        companyAddress2:
          type: string
        companyCity:
          type: string
        companyState:
          type: string
        companyZip:
          type: string
        employeeName:
          type: string
        employeeEmail:
          type: string
        type:
          type: string
          enum:
            - INITIAL
            - PREVIEW
            - FINAL
            - UPDATE
        businessAddressExist:
          type: boolean
        senderInfoExist:
          type: boolean
        brandColor:
          type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentDTO'
        showInvoiceIsDraft:
          type: boolean
        salesTax:
          type: number
        invoiceItemByWorkItemType:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/InvoiceReportLineItem'
        invoiceLineItemList:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceReportLineItem'
        clientAdditionalContactName:
          type: string
        clientBusinessName:
          type: string
        clientEmail:
          type: string
        clientPhoneWork:
          type: string
        clientAddress1:
          type: string
        clientAddress2:
          type: string
        clientCity:
          type: string
        clientState:
          type: string
        clientZip:
          type: string
        clientInfoExist:
          type: boolean
        clientAddressExist:
          type: boolean
    Business:
      type: object
      properties:
        id:
          type: string
        companyId:
          type: string
        companyIdLong:
          type: integer
          format: int64
        customerPartnerId:
          type: integer
          format: int64
        name:
          type: string
        showName:
          type: boolean
        contactFirst:
          type: string
        contactLast:
          type: string
        showContactFirstLast:
          type: boolean
        email:
          type: string
        showEmail:
          type: boolean
        phoneWork:
          type: string
        showPhoneWork:
          type: boolean
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        showAddress:
          type: boolean
        tin:
          type: string
        invoicePrefix:
          type: string
        plaidApiEntityIds:
          type: string
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - PENDING
            - DELETED
        apiName:
          type: string
          enum:
            - GOOGLELOGIN
            - LINKEDINLOGIN
            - DROPBOX
            - BOX
            - SKYDRIVE
            - CLOVER
            - STRIPE
            - GOOGLESTORAGE
            - GOOGLECONTACTS
            - GOOGLEEMAIL
            - LINKEDINCONTACTS
            - PLAID
            - KNOX
            - UBER
            - FACEBOOKLOGIN
            - FRESHBOOKS
            - HARVEST
            - KW
            - FRESHBOOKS2
            - CAPITAL_ONE
            - SQUARE
            - S3
            - DOTLOOP
            - XERO_DEPRECATED
            - REALOGY
            - UPWORK
            - SHOPIFY
            - DEDUCTR
            - ENTERPRISE
            - MOXIWORKS
            - STRIPE_EXPRESS
            - APPLELOGIN
            - APPDIRECT
            - LONEWOLF
            - USER_IMPORTED
            - LONEWOLF_TRANSACTIONDESK
            - SAMPLE_BANK
            - TAXBOT
            - THIRD_PARTY_BANK
            - GUSTO
            - THIRD_PARTY_PAYMENTS
            - XERO
            - UNIT
            - USER_ENTRY
            - MOOV
            - QBO
            - COLUMN
            - QUALPAY
            - BENCH
            - PARTNER_IMPLEMENTATION
            - CHECK
            - RUTTER
            - WAVE
            - ADYEN
            - APRIL
            - PAYABLI
        apiClientId:
          type: string
        bizType:
          type: string
          enum:
            - ADVISOR_COACH
            - ARCHITECT
            - BRANDING_DESIGN
            - CONSULTANT
            - GOVT_CONTRACTOR
            - HOTEL_HOSPITALITY
            - PHOTOGRAPHY
            - PRINTING_DESIGN
            - PROFESSIONAL_SERVICES
            - LANDLORD
            - REAL_ESTATE_AGENT
            - RESTAURANT
            - SOFTWARE_DEV
            - SPEAKER_AUTHOR
            - TECH_SUPPORT
            - WEB_DESIGN_DEV
            - HEALTH_PROFESSIONAL
            - OTHER
            - DRIVER
            - AIRBNB
            - FINANCIAL_ADVISOR
            - INSURANCE_AGENT
            - MARKETER
            - RETAIL
            - HOST
            - FREELANCER
            - E_COMMERCE
            - SALES
        dimensionId:
          type: integer
          format: int64
        level0Id:
          type: integer
          format: int64
        createdDate:
          type: string
          format: date-time
        idPrefix:
          type: string
          enum:
            - COMPANY
            - EMPLOYEE
            - DIMENSION_VALUE
            - CLASS_LABEL
            - CUSTOMER
            - BANK_ACCOUNT
            - GL_ACCOUNT
            - TRANSACTION_CATEGORY
            - BANK_TRANSACTION
            - PROCESSOR_TRANSACTION
            - TRANSACTION_LINE_ITEM
            - VENDOR
            - TRANSACTION_RULE
            - REVENUE_RULE
            - INVOICE
            - INVOICE_LINE_ITEM
            - BILL
            - BILL_LINE_ITEM
            - PAYROLL
            - PAYROLL_LINE_ITEM
            - FINANCIAL_SUMMARY
            - TASK
            - CONVERSATION
            - MESSAGE
            - REACTION
            - BUSINESS_TYPE
            - TEMPLATE_DIMENSION
            - TEMPLATE_COA
            - TEMPLATE_GL_ACCOUNT
            - TEMPLATE_TRANSACTION_RULES
            - MANUAL_JOURNAL_ENTRY
            - GL_TRANSACTION
            - ATTACHMENT
            - CAR
            - MILEAGE
            - INTEGRATION
            - TIME
            - TIME_TYPE
            - TAX_RETURN
        nameColumnNameForPagination:
          type: string
        externalId:
          type: string
    JSONArray:
      type: object
      properties:
        empty:
          type: boolean
    Installment:
      required:
        - amount
        - dueDate
        - name
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the installment
        companyId:
          type: string
        arInvoice:
          $ref: '#/components/schemas/ArInvoice'
        name:
          type: string
          description: Name or description of the installment
          example: First Payment
        dueDate:
          type: string
          description: The due date for this installment payment
          format: date
          example: '2025-01-15'
        amount:
          type: number
          description: The fixed dollar amount for this installment
          example: 500
        status:
          type: string
          description: Status of the installment
          example: ACTIVE
          enum:
            - ACTIVE
            - INACTIVE
            - REMOVED
        dateForPagination:
          type: string
          format: date-time
        externalId:
          type: string
        idPrefix:
          type: string
          enum:
            - COMPANY
            - EMPLOYEE
            - DIMENSION_VALUE
            - CLASS_LABEL
            - CUSTOMER
            - BANK_ACCOUNT
            - GL_ACCOUNT
            - TRANSACTION_CATEGORY
            - BANK_TRANSACTION
            - PROCESSOR_TRANSACTION
            - TRANSACTION_LINE_ITEM
            - VENDOR
            - TRANSACTION_RULE
            - REVENUE_RULE
            - INVOICE
            - INVOICE_LINE_ITEM
            - BILL
            - BILL_LINE_ITEM
            - PAYROLL
            - PAYROLL_LINE_ITEM
            - FINANCIAL_SUMMARY
            - TASK
            - CONVERSATION
            - MESSAGE
            - REACTION
            - BUSINESS_TYPE
            - TEMPLATE_DIMENSION
            - TEMPLATE_COA
            - TEMPLATE_GL_ACCOUNT
            - TEMPLATE_TRANSACTION_RULES
            - MANUAL_JOURNAL_ENTRY
            - GL_TRANSACTION
            - ATTACHMENT
            - CAR
            - MILEAGE
            - INTEGRATION
            - TIME
            - TIME_TYPE
            - TAX_RETURN
    AttachmentDTO:
      type: object
      properties:
        id:
          type: integer
          description: Id of the attachment, required when updating an existing attachment
          format: int64
        type:
          type: string
          description: Type of the attachment
          example: FILE
          enum:
            - PICTURE
            - FILE
            - VOICE
            - INVOICE
        caption:
          type: string
          description: Caption of the attachment
        publicFileUrl:
          type: string
          description: URL at which the attachment is located
        date:
          type: string
          description: Date of the attachment
          format: date-time
        amount:
          type: number
          description: Amount of the attachment
        attachToTable:
          type: string
          description: Entity table the attachment is associated with
        attachToId:
          type: string
          description: Id of the entity this attachment is associated with
    InvoiceReportLineItem:
      type: object
      properties:
        lineItemName:
          type: string
        workItemType:
          type: string
        lineItemDescription:
          type: string
        price:
          type: number
        workItemDate:
          type: string
        invoiceItemDiscountedPrice:
          type: number
        unitPrice:
          type: number
        quantity:
          type: number
        invoiceItemRegularPrice:
          type: number
        salesTax:
          type: number
  securitySchemes:
    accessTokenSecurity:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: /auth/account
          scopes:
            write: ''

````