LedgerWire

Customer · Add

simulated in sandbox

CustomerAdd

Customers are the people and companies you invoice. In QuickBooks Desktop they live in the Customer:Job list, share a name space with vendors and employees, and carry balances that QuickBooks maintains for you.

qbXML request

CustomerAddRq
<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="13.0"?>
<QBXML>
  <QBXMLMsgsRq onError="stopOnError">
    <CustomerAddRq requestID="1">
      <CustomerAdd>
        <Name>Bayside Builders LLC</Name>
        <CompanyName>Bayside Builders LLC</CompanyName>
        <FirstName>Maria</FirstName>
        <LastName>Alvarez</LastName>
        <BillAddress>
          <Addr1>410 Harbor Way</Addr1>
          <City>Columbus</City>
          <State>OH</State>
          <PostalCode>43215</PostalCode>
        </BillAddress>
        <Phone>(614) 555-0142</Phone>
        <Email>maria@bayside.example</Email>
      </CustomerAdd>
    </CustomerAddRq>
  </QBXMLMsgsRq>
</QBXML>

JSON equivalent

POST /v1/customers
{
  "name": "Bayside Builders LLC",
  "email": "maria@bayside.example",
  "phone": "(614) 555-0142",
  "lastName": "Alvarez",
  "firstName": "Maria",
  "billAddress": {
    "city": "Columbus",
    "addr1": "410 Harbor Way",
    "state": "OH",
    "postalCode": "43215"
  },
  "companyName": "Bayside Builders LLC"
}
curl
curl -X POST https://ledgerwire.vibiz.app/v1/customers \
  -H "Authorization: Bearer $LEDGERWIRE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bayside Builders LLC","email":"maria@bayside.example","phone":"(614) 555-0142","lastName":"Alvarez","firstName":"Maria","billAddress":{"city":"Columbus","addr1":"410 Harbor Way","state":"OH","postalCode":"43215"},"companyName":"Bayside Builders LLC"}'

Run this request against your own sandbox

Add and Mod requests change data, so they run in a private sandbox, not the shared demo. Get a free key (10 seconds), then POST the request above to /v1/qbxml.

qbXML response (from the sandbox seed data)

CustomerAddRs
<?xml version="1.0" ?>
<QBXML>
  <QBXMLMsgsRs>
    <CustomerAddRs requestID="1" statusCode="0" statusSeverity="Info" statusMessage="Status OK">
      <CustomerRet>
        <ListID>80000055-1794881749</ListID>
        <TimeCreated>2026-02-22T15:05:35+00:00</TimeCreated>
        <TimeModified>2026-02-22T15:05:35+00:00</TimeModified>
        <EditSequence>1771772735</EditSequence>
        <Name>Bayside Builders LLC</Name>
        <FullName>Lakeshore Mechanical Co</FullName>
        <IsActive>true</IsActive>
        <Sublevel>0</Sublevel>
        <CompanyName>Bayside Builders LLC</CompanyName>
        <FirstName>Maria</FirstName>
        <LastName>Alvarez</LastName>
        <BillAddress>
          <Addr1>410 Harbor Way</Addr1>
          <City>Columbus</City>
          <State>OH</State>
          <PostalCode>43215</PostalCode>
        </BillAddress>
        <Phone>(614) 555-0142</Phone>
        <Email>maria@bayside.example</Email>
        <Contact>Andre Lopez</Contact>
        <TermsRef>
          <FullName>Due on receipt</FullName>
        </TermsRef>
        <JobStatus>None</JobStatus>
        <Balance>1951.00</Balance>
        <TotalBalance>1951.00</TotalBalance>
      </CustomerRet>
    </CustomerAddRs>
  </QBXMLMsgsRs>
</QBXML>

FAQ

What is required in CustomerAdd?

`name` at minimum. Elements must appear in the order the qbXML schema lists them; LedgerWire orders them for you when you send JSON.

Why does CustomerAdd fail with status 3140?

3140 means a reference (for example ParentRef or an ItemRef) points at something that does not exist in the company file. Look the record up first, or create it, and pass its ListID.

Why does CustomerAdd fail with status 3100?

The Name is already in use. QuickBooks requires unique names across customers, vendors, employees and other names, and within each item list. Query for the existing record and update it instead.

Sandbox fidelity

The LedgerWire sandbox simulates CustomerAdd with QuickBooks rules: required fields, element names, refs that must exist (3140), unique names (3100), field lengths (3070) and EditSequence locking (3200). Tax calculation, custom fields and preferences are not simulated.

More Customer messages

Other Add messages

Skip the XML: call POST /v1/customers with JSON.

Get a free sandbox key