Intuit Customers API

openapi: 3.1.0
info:
  title: QuickBooks Online Accounting Customers API
  description: The QuickBooks Online Accounting API is a RESTful API that provides programmatic access to QuickBooks Online company data. This specification covers core entities including invoices, customers, items, and payments, enabling developers to automate accounting workflows, synchronize financial data, and extend QuickBooks Online functionality for small and mid-sized businesses. All API calls require OAuth 2.0 authorization and a valid company ID (realmId). Responses follow the Intuit entity response envelope pattern, and the API supports minor version parameters to access newer fields and behaviors without breaking existing integrations.
  version: '75'
  termsOfService: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  contact:
    name: Intuit Developer Support
    url: https://help.developer.intuit.com
    email: developer-support@intuit.com
  license:
    name: Intuit Developer Terms of Service
    url: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  x-logo:
    url: https://developer.intuit.com/app/developer/common/imgs/IntuitDev_Logo.svg
servers:
- url: https://quickbooks.api.intuit.com/v3/company/{realmId}
  description: Production
  variables:
    realmId:
      description: The QuickBooks Online company ID (realm ID) that uniquely identifies the company dataset to operate on.
      default: '1234567890'
- url: https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}
  description: Sandbox
  variables:
    realmId:
      description: The sandbox company ID for testing and development purposes.
      default: '1234567890'
security:
- oauth2: []
tags:
- name: Customers
  description: A Customer object represents a consumer of the service or product that the business offers. The Customer entity allows you to categorize customers into jobs and sub-customers.
  externalDocs:
    url: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/customer
paths:
  /query:
    get:
      operationId: queryEntities
      summary: Query Entities
      description: Executes a SQL-like query against QuickBooks Online entities. The query language supports SELECT, WHERE, ORDER BY, COUNT, STARTPOSITION, and MAXRESULTS clauses. This endpoint is used to query invoices, customers, items, payments, and other entity types.
      tags:
      - Customers
      parameters:
      - name: query
        in: query
        required: true
        description: 'A SQL-like query string. For example: SELECT * FROM Invoice WHERE TotalAmt > ''100.00'' ORDERBY TxnDate'
        schema:
          type: string
        example: SELECT * FROM Invoice WHERE TotalAmt > '100.00' MAXRESULTS 10
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              examples:
                Queryentities200Example:
                  summary: Default queryEntities 200 response
                  x-microcks-default: true
                  value:
                    QueryResponse:
                      startPosition: 10
                      maxResults: 10
                      totalCount: 10
                      Invoice:
                      - {}
                      Customer:
                      - {}
                      Item:
                      - {}
                      Payment:
                      - {}
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /customer:
    post:
      operationId: createCustomer
      summary: Create a Customer
      description: Creates a new customer. At minimum, the request must include a DisplayName that is unique across all Customer, Employee, and Vendor objects. Additional fields such as billing address, email, and phone can be set during creation.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
            examples:
              CreatecustomerRequestExample:
                summary: Default createCustomer request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  Title: Example Title
                  GivenName: example_value
                  MiddleName: example_value
                  FamilyName: example_value
                  Suffix: example_value
                  DisplayName: example_value
                  CompanyName: example_value
                  PrintOnCheckName: example_value
                  Active: true
                  Taxable: true
                  PrimaryEmailAddr:
                    Address: example_value
                  PrimaryPhone:
                    FreeFormNumber: example_value
                  Mobile:
                    FreeFormNumber: example_value
                  Fax:
                    FreeFormNumber: example_value
                  AlternatePhone:
                    FreeFormNumber: example_value
                  BillAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  ShipAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  Notes: example_value
                  Job: true
                  ParentRef:
                    value: example_value
                    name: Example Title
                  Level: 10
                  FullyQualifiedName: example_value
                  CurrencyRef:
                    value: example_value
                    name: Example Title
                  PreferredDeliveryMethod: Print
                  Balance: 42.5
                  BalanceWithJobs: 42.5
                  SalesTermRef:
                    value: example_value
                    name: Example Title
                  PaymentMethodRef:
                    value: example_value
                    name: Example Title
                  TaxExemptionReasonId: '500123'
                  WebAddr:
                    URI: https://www.example.com
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
              examples:
                Createcustomer200Example:
                  summary: Default createCustomer 200 response
                  x-microcks-default: true
                  value:
                    Customer:
                      Id: abc123
                      SyncToken: example_value
                      Title: Example Title
                      GivenName: example_value
                      MiddleName: example_value
                      FamilyName: example_value
                      Suffix: example_value
                      DisplayName: example_value
                      CompanyName: example_value
                      PrintOnCheckName: example_value
                      Active: true
                      Taxable: true
                      Notes: example_value
                      Job: true
                      Level: 10
                      FullyQualifiedName: example_value
                      PreferredDeliveryMethod: Print
                      Balance: 42.5
                      BalanceWithJobs: 42.5
                      TaxExemptionReasonId: '500123'
                      WebAddr:
                        URI: https://www.example.com
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /customer/{customerId}:
    get:
      operationId: readCustomer
      summary: Read a Customer
      description: Retrieves the details of a customer that has been previously created. Supply the unique customer ID.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Customer retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
              examples:
                Readcustomer200Example:
                  summary: Default readCustomer 200 response
                  x-microcks-default: true
                  value:
                    Customer:
                      Id: abc123
                      SyncToken: example_value
                      Title: Example Title
                      GivenName: example_value
                      MiddleName: example_value
                      FamilyName: example_value
                      Suffix: example_value
                      DisplayName: example_value
                      CompanyName: example_value
                      PrintOnCheckName: example_value
                      Active: true
                      Taxable: true
                      Notes: example_value
                      Job: true
                      Level: 10
                      FullyQualifiedName: example_value
                      PreferredDeliveryMethod: Print
                      Balance: 42.5
                      BalanceWithJobs: 42.5
                      TaxExemptionReasonId: '500123'
                      WebAddr:
                        URI: https://www.example.com
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: updateCustomer
      summary: Update a Customer
      description: Updates an existing customer. The request body must include the Id and SyncToken. A sparse update is supported by including only the fields that need to change along with the sparse=true parameter.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/customerId'
      - name: sparse
        in: query
        description: Set to true for a sparse (partial) update
        schema:
          type: boolean
        example: true
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
            examples:
              UpdatecustomerRequestExample:
                summary: Default updateCustomer request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  Title: Example Title
                  GivenName: example_value
                  MiddleName: example_value
                  FamilyName: example_value
                  Suffix: example_value
                  DisplayName: example_value
                  CompanyName: example_value
                  PrintOnCheckName: example_value
                  Active: true
                  Taxable: true
                  PrimaryEmailAddr:
                    Address: example_value
                  PrimaryPhone:
                    FreeFormNumber: example_value
                  Mobile:
                    FreeFormNumber: example_value
                  Fax:
                    FreeFormNumber: example_value
                  AlternatePhone:
                    FreeFormNumber: example_value
                  BillAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  ShipAddr:
                    Id: abc123
                    Line1: example_value
                    Line2: example_value
                    Line3: example_value
                    Line4: example_value
                    Line5: example_value
                    City: example_value
                    CountrySubDivisionCode: example_value
                    PostalCode: example_value
                    Country: example_value
                    Lat: example_value
                    Long: example_value
                  Notes: example_value
                  Job: true
                  ParentRef:
                    value: example_value
                    name: Example Title
                  Level: 10
                  FullyQualifiedName: example_value
                  CurrencyRef:
                    value: example_value
                    name: Example Title
                  PreferredDeliveryMethod: Print
                  Balance: 42.5
                  BalanceWithJobs: 42.5
                  SalesTermRef:
                    value: example_value
                    name: Example Title
                  PaymentMethodRef:
                    value: example_value
                    name: Example Title
                  TaxExemptionReasonId: '500123'
                  WebAddr:
                    URI: https://www.example.com
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
              examples:
                Updatecustomer200Example:
                  summary: Default updateCustomer 200 response
                  x-microcks-default: true
                  value:
                    Customer:
                      Id: abc123
                      SyncToken: example_value
                      Title: Example Title
                      GivenName: example_value
                      MiddleName: example_value
                      FamilyName: example_value
                      Suffix: example_value
                      DisplayName: example_value
                      CompanyName: example_value
                      PrintOnCheckName: example_value
                      Active: true
                      Taxable: true
                      Notes: example_value
                      Job: true
                      Level: 10
                      FullyQualifiedName: example_value
                      PreferredDeliveryMethod: Print
                      Balance: 42.5
                      BalanceWithJobs: 42.5
                      TaxExemptionReasonId: '500123'
                      WebAddr:
                        URI: https://www.example.com
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    QueryResponse:
      type: object
      description: Response wrapper for query operations. Contains the array of matching entities along with pagination metadata.
      properties:
        QueryResponse:
          type: object
          properties:
            startPosition:
              type: integer
              description: Starting position of the results
            maxResults:
              type: integer
              description: Maximum number of results returned
            totalCount:
              type: integer
              description: Total count of matching entities
            Invoice:
              type: array
              items:
                $ref: '#/components/schemas/Invoice'
            Customer:
              type: array
              items:
                $ref: '#/components/schemas/Customer'
            Item:
              type: array
              items:
                $ref: '#/components/schemas/Item'
            Payment:
              type: array
              items:
                $ref: '#/components/schemas/Payment'
          example: example_value
        time:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    Customer:
      type: object
      description: A Customer represents a consumer of the service or product that the business offers. Customers can be organized as sub-customers (jobs) within a parent customer hierarchy.
      properties:
        Id:
          type: string
          description: Unique identifier for the customer
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        Title:
          type: string
          description: Title of the person (e.g., Mr., Mrs., Ms.)
          maxLength: 16
          example: Example Title
        GivenName:
          type: string
          description: Given (first) name of the customer
          maxLength: 100
          example: example_value
        MiddleName:
          type: string
          description: Middle name of the customer
          maxLength: 100
          example: example_value
        FamilyName:
          type: string
          description: Family (last) name of the customer
          maxLength: 100
          example: example_value
        Suffix:
          type: string
          description: Suffix of the person (e.g., Jr., Sr., III)
          maxLength: 16
          example: example_value
        DisplayName:
          type: string
          description: The name displayed to identify the customer. Must be unique across Customer, Employee, and Vendor objects.
          maxLength: 500
          example: example_value
        CompanyName:
          type: string
          description: The name of the company associated with the customer
          maxLength: 500
          example: example_value
        PrintOnCheckName:
          type: string
          description: Name of the customer as printed on a check
          maxLength: 110
          example: example_value
        Active:
          type: boolean
          description: Whether the customer is currently active
          default: true
          example: true
        Taxable:
          type: boolean
          description: Whether the customer is taxable
          example: true
        PrimaryEmailAddr:
          $ref: '#/components/schemas/EmailAddress'
        PrimaryPhone:
          $ref: '#/components/schemas/TelephoneNumber'
        Mobile:
          $ref: '#/components/schemas/TelephoneNumber'
        Fax:
          $ref: '#/components/schemas/TelephoneNumber'
        AlternatePhone:
          $ref: '#/components/schemas/TelephoneNumber'
        BillAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        ShipAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        Notes:
          type: string
          description: Free-form text about the customer
          maxLength: 2000
          example: example_value
        Job:
          type: boolean
          description: Whether this customer is a sub-customer (job)
          example: true
        ParentRef:
          $ref: '#/components/schemas/ReferenceType'
        Level:
          type: integer
          description: Depth level in the customer hierarchy (0 = top)
          readOnly: true
          example: 10
        FullyQualifiedName:
          type: string
          description: Fully qualified name of the entity, including parent names separated by colons
          readOnly: true
          example: example_value
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        PreferredDeliveryMethod:
          type: string
          description: Preferred delivery method for communications
          enum:
          - Print
          - Email
          - None
          example: Print
        Balance:
          type: number
          description: Open balance amount for the customer
          readOnly: true
          example: 42.5
        BalanceWithJobs:
          type: number
          description: Open balance amount including balances of sub-customers (jobs)
          readOnly: true
          example: 42.5
        SalesTermRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        TaxExemptionReasonId:
          type: string
          description: Tax exemption reason ID
          example: '500123'
        WebAddr:
          type: object
          properties:
            URI:
              type: string
              format: uri
              description: Website address
          example: example_value
        domain:
          type: string
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          example: true
      required:
      - DisplayName
    Payment:
      type: object
      description: A Payment records a payment received from a customer. Payments can be applied to one or more outstanding invoices, or left as unapplied credit.
      properties:
        Id:
          type: string
          description: Unique identifier for the payment
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        TxnDate:
          type: string
          format: date
          description: The date of the payment transaction
          example: '2026-01-15'
        TotalAmt:
          type: number
          description: Total amount of the payment
          example: 42.5
        CustomerRef:
          $ref: '#/components/schemas/ReferenceType'
        DepositToAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentRefNum:
          type: string
          description: Reference number for the payment (e.g., check number)
          maxLength: 21
          example: example_value
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        ExchangeRate:
          type: number
          description: Currency exchange rate
          example: 42.5
        Line:
          type: array
          description: Lines indicating which invoices or credit memos this payment is applied against
          items:
            $ref: '#/components/schemas/PaymentLine'
          example: []
        PrivateNote:
          type: string
          description: Private note for internal use
          maxLength: 4000
          example: example_value
        UnappliedAmt:
          type: number
          description: Amount not yet applied to invoices
          readOnly: true
          example: 42.5
        ProcessPayment:
          type: boolean
          description: Whether to process the payment through the Intuit payment gateway
          example: true
        TxnSource:
          type: string
          description: Source of the transaction
          readOnly: true
          example: example_value
        domain:
          type: string
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          example: true
      required:
      - CustomerRef
      - TotalAmt
    CustomField:
      type: object
      description: Custom field defined for the entity
      properties:
        DefinitionId:
          type: string
          description: Unique identifier of the custom field definition
          example: '500123'
        Name:
          type: string
          description: Name of the custom field
          example: Example Title
        Type:
          type: string
          description: Data type of the custom field
          enum:
          - StringType
          - BooleanType
          - NumberType
          - DateType
          example: StringType
        StringValue:
          type: string
          description: Value when Type is StringType
          example: example_value
    ReferenceType:
      type: object
      description: A reference type used throughout the API to link entities. Contains the ID value and optionally the display name of the referenced entity.
      properties:
        value:
          type: string
          description: The ID of the referenced entity
          example: example_value
        name:
          type: string
          description: An identifying name for the referenced entity
          example: Example Title
      required:
      - value
    Invoice:
      type: object
      description: An Invoice represents a sales form where the customer pays for a product or service later. It creates an accounts receivable transaction.
      properties:
        Id:
          type: string
          description: Unique identifier for the invoice (assigned by QuickBooks)
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number of the entity, used for optimistic locking. Required for updates.
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        DocNumber:
          type: string
          description: Reference number for the transaction. If not provided, QuickBooks auto-generates one.
          maxLength: 21
          example: example_value
        TxnDate:
          type: string
          format: date
          description: The date of the transaction. Defaults to the current date.
          example: '2026-01-15'
        DueDate:
          type: string
          format: date
          description: Date when the payment of the transaction is due
          example: '2026-01-15'
        PrivateNote:
          type: string
          description: A private note that is not displayed to the customer
          maxLength: 4000
          example: example_value
        CustomerMemo:
          type: object
          description: A note to the customer displayed on the invoice
          properties:
            value:
              type: string
              maxLength: 1000
          example: example_value
        CustomerRef:
          $ref: '#/components/schemas/ReferenceType'
        BillAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        ShipAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        BillEmail:
          $ref: '#/components/schemas/EmailAddress'
        Line:
          type: array
          description: Individual line items of the transaction. At least one line is required.
          items:
            $ref: '#/components/schemas/InvoiceLine'
          minItems: 1
          example: []
        TxnTaxDetail:
          $ref: '#/components/schemas/TxnTaxDetail'
        TotalAmt:
          type: number
          description: Total amount of the transaction including tax
          readOnly: true
          example: 42.5
        Balance:
          type: number
          description: The balance remaining on the invoice. A value of 0 indicates the invoice is fully paid.
          readOnly: true
          example: 42.5
        Deposit:
          type: number
          description: Deposit amount applied to the invoice
          example: 42.5
        DepositToAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        SalesTermRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        ExchangeRate:
          type: number
          description: Currency exchange rate (multicurrency enabled companies)
          example: 42.5
        ShipDate:
          type: string
          format: date
          description: Date for delivery of goods or services
          example: '2026-01-15'
        ShipMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        TrackingNum:
          type: string
          description: Shipping tracking number
          example: example_value
        ApplyTaxAfterDiscount:
          type: boolean
          description: Whether to apply tax after discount
          example: true
        PrintStatus:
          type: string
          description: Printing status of the invoice
          enum:
          - NotSet
          - NeedToPrint
          - PrintComplete
          example: NotSet
        EmailStatus:
          type: string
          description: Email delivery status of the invoice
          enum:
          - NotSet
          - NeedToSend
          - EmailSent
          example: NotSet
        GlobalTaxCalculation:
          type: string
          description: Method in which tax is applied
          enum:
          - TaxExcluded
          - TaxInclusive
          - NotApplicable
          example: TaxExcluded
        AllowOnlinePayment:
          type: boolean
          description: Whether online payment is allowed
          example: true
        AllowOnlineCreditCardPayment:
          type: boolean
          description: Whether online credit card payment is allowed
          example: true
        AllowOnlineACHPayment:
          type: boolean
          description: Whether online ACH (bank) payment is allowed
          example: true
        CustomField:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
          maxItems: 3
          example: []
        LinkedTxn:
          type: array
          items:
            $ref: '#/components/schemas/LinkedTxn'
          example: []
        domain:
          type: string
          description: Domain (e.g., QBO)
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          description: Whether this is a sparse (partial) representation
          example: true
      requi

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/intuit/refs/heads/main/openapi/intuit-customers-api-openapi.yml