POSTing Contacts with Merge's Accounting Unified API

Last updated: April 27, 2026

A Contact is an individual or business entity to which products and services are sold to or purchased from. The Contact Common Model contains both Customers, in which products and services are sold to, and Vendors (or Suppliers), in which products and services are purchased from.

  • A Contact is a Vendor/Supplier if the is_supplier property is true.

  • A Contact is a Customer if the is_customer property is true.

Requirements

The key setup items to confirm upfront are listed below. These requirements are consistent across all most ERP integrations. We also recommend reviewing the Integration nuances sections to understand ERP-specific behavior.

Non-negotiables

The two topics below are required for every POST Contacts use case.

1. Vendors vs Customers

Set is_supplier = true for vendor/suppliers and is_customer = true for customers. This convention is consistent across all ERPs supported by Merge.

Xero does not allow either value to be set via API - see Integration nuances below for details.

2. Name

name is commonly required when creating a contact, whether the contact is a vendor/supplier or a customer. Make sure to include name in your request.

Request samples

Create a vendor / supplier

{
  "model": {
    "name": "Aesop Vendor",
    "is_supplier": true,
    "is_customer": null,
    "email_address": "[email protected]",
    "status": null,
    "currency": "USD",
    "addresses": [
      {
        "type": "DEFAULT",
        "street_1": "212 E 53rd St",
        "street_2": "4th Floor",
        "city": "New York",
        "country_subdivision": "NY",
        "country": "US",
        "zip_code": "10027"
      },
      {
        "type": "PAYTO",
        "street_1": "415 Charleston Ave",
        "city": "Holly Oak",
        "state": "DE",
        "country": "US",
        "zip_code": "19809"
      }
    ],
    "phone_numbers": [
      {
        "number": "+1234567891",
        "type": "Mobile"
      },
      {
        "number": "+1234567890",
        "type": "Default"
      }
    ]
  }
}

Create a customer

{
  "model": {
    "name": "Customer Aesop",
    "is_customer ": true,
    "is_supplier": null,
    "email_address": "[email protected]",
    "status": null,
    "currency": "USD",
    "addresses": [
      {
        "type": "DEFAULT",
        "street_1": "212 E 53rd St",
        "street_2": "4th Floor",
        "city": "New York",
        "country_subdivision": "NY",
        "country": "US",
        "zip_code": "10027"
      },
      {
        "type": "PAYTO",
        "street_1": "415 Charleston Ave",
        "city": "Holly Oak",
        "state": "DE",
        "country": "US",
        "zip_code": "19809"
      }
    ],
    "phone_numbers": [
      {
        "number": "+1234567891",
        "type": "Mobile"
      },
      {
        "number": "+1234567890",
        "type": "Default"
      }
    ],
    "integration_params": {
      "sage­_customer­_or­_vendor­_id": "12345"
    }
  }
}

Integration nuances

NetSuite

Integration param

When creating a contact, set the is_person integration param field to true or false. This allows Merge to determine

Request examples for NetSuite POST Contact

Vendor

{
  "model": {
    "name": "Create vendor with remote fields",
    "status": "ACTIVE",
    "company": "{company_info_uuid}",
    "currency": "GBP",
    "tax_number": null,
    "is_customer": false,
    "is_supplier": true,
    "email_address": "[email protected]",
    "addresses": [
      {
        "type": "DEFAULT",
        "street_1": "212 E 53rd St",
        "street_2": "4th Floor",
        "city": "New York",
        "country_subdivision": "NY",
        "country": "US",
        "zip_code": "10027"
      },
      {
        "type": "PAYTO",
        "street_1": "415 Charleston Ave",
        "city": "Holly Oak",
        "state": "DE",
        "country": "US",
        "zip_code": "19809"
      }
    ],
    "phone_numbers": [
      {
        "type": "MOBILE",
        "number": "+1234567890"
      },
      {
        "type": "PHONE",
        "number": "+1234567890"
      }
    ],
    "remote_fields": [
      {
        "remote_field_class": "{uuid}",
        "value": {
          "remote_id": "1"
        }
      },
      {
        "remote_field_class": "{uuid}",
        "value": "Fedex"
      }
    ],
    "integration_params": {
      "is_person": false
    },
    "linked_account_params": null
  }
}

Customer

{
  "model": {
    "name": "Creating Customer",
    "status": "ACTIVE",
    "company": "{company_info_uuid}",
    "currency": "GBP",
    "tax_number": null,
    "is_customer": true,
    "is_supplier": false,
    "email_address": "[email protected]",
    "addresses": [
      {
        "type": "DEFAULT",
        "street_1": "212 E 53rd St",
        "street_2": "4th Floor",
        "city": "New York",
        "country_subdivision": "NY",
        "country": "US",
        "zip_code": "10027"
      },
      {
        "type": "PAYTO",
        "street_1": "415 Charleston Ave",
        "city": "Holly Oak",
        "state": "DE",
        "country": "US",
        "zip_code": "19809"
      }
    ],
    "phone_numbers": [
      {
        "type": "MOBILE",
        "number": "+1234567890"
      },
      {
        "type": "PHONE",
        "number": "+1234567890"
      }
    ],
    "remote_fields": [
      {
        "remote_field_class": "{uuid}",
        "value": {
          "remote_id": "1"
        }
      },
      {
        "remote_field_class": "{uuid}",
        "value": true
      }
    ],
    "integration_params": {
      "is_person": true
    },
    "linked_account_params": null
  }
}

QuickBooks Online

Project or Job-Based Use Cases

QuickBooks Online (QBO) models Jobs and sub-customers as part of the Customer object, which lets teams organize work under a single parent customer for project- or job-based workflows (for example, tracking projects, job codes, or locations while still rolling up reporting).

Merge supports this by allowing you to create QBO Customer records as either top-level customers, or Jobs/sub-customers (including linking them to a parent customer when needed) via integration params

Integration parameters

The following integration_params can be used to set QBO-specific fields when creating or updating customers and vendors.

  • job (Customers only)

    • Boolean. Supported when creating a customer

      • true: the record is a Job / sub-customer

      • false or null: the record is a top-level customer (not a Job)

  • notes (Customers only)

    • String. Supported for customers

    • Use this field for free-form notes about the customer

    • Maximum length: 2000 characters

  • parent_ref (Customers only)

    • Reference. Supported when creating a customer

    • Use parent_ref to set the immediate parent customer for a Job / sub-customer in QBO’s Customer:Job hierarchy

    • Required when creating a customer where job = true

    • Value should be the parent customer’s identifier (pass the parent record’s Contact.remote_id)

  • bill_with_parent (Customers only)

    • Boolean. Supported when creating a customer, and only valid for Jobs / sub-customers entities

      • true: bill this Job/sub-customer with its parent

      • false or null: do not bill with the parent

  • WebAddr.URI (Customers and Vendors)

    • String. Supported for customers and vendors

    • Sets the website URL

    • Maximum length: 1000 characters

Request examples for QuickBooks Online POST Contact

Vendor

{
   "model": {
      "name": "Create Vendor",
      "status": "ACTIVE",
      "currency": "USD",
      "addresses": [
         {
            "type": "SHIPPING",
            "street_1": "1000 Broadway",
            "street_2": "1st Floor",
            "city": "New York",
            "state": "NY",
            "country": "USA",
            "zip_code": "10027"
         },
         {
            "type": "BILLING",
            "street_1": "123 E 12th St",
            "street_2": "Apt 100",
            "city": "New York",
            "state": "NY",
            "country": "USA",
            "zip_code": "10027"
         }
      ],
      "phone_numbers": [
         {
            "type": "MOBILE",
            "number": "+1234567890"
         },
         {
            "type": "PHONE",
            "number": "+1234567890"
         }
      ],
      "tax_number": "12-3456789",
      "is_supplier": true,
      "email_address": "[email protected]",
      "integration_params": {
         "WebAddr.URI": "https://merge.dev"
      },
      "linked_account_params": null
   }
}

Customer

{
  "model": {
    "name": "Create Customer",
    "status": "ACTIVE",
    "currency": "USD",
    "addresses": [
      {
        "type": "SHIPPING",
        "street_1": "1000 Broadway",
        "street_2": "1st Floor",
        "city": "New York",
        "state": "NY",
        "country": "USA",
        "zip_code": "10027"
      },
      {
        "type": "BILLING",
        "street_1": "123 E 12th St",
        "street_2": "Apt 100",
        "city": "New York",
        "state": "NY",
        "country": "USA",
        "zip_code": "10027"
      }
    ],
    "phone_numbers": [
      {
        "type": "MOBILE",
        "number": "+1234567890"
      },
      {
        "type": "PHONE",
        "number": "+1234567890"
      }
    ],
    "tax_number": "12-3456789",
    "is_customer": true,
    "email_address": "[email protected]",
    "integration_params": {
      "Notes": "This is a customer test contact. This is not a subcustomer",
      "WebAddr.URI": "https://merge.dev"
    },
    "linked_account_params": null
  }
}

Create a Job or SubCustomer on QBO's Customer object

{
   "model": {
      "name": "Create Job/Sub-customer",
      "status": "ACTIVE",
      "currency": "USD",
      "addresses": [
         {
            "type": "SHIPPING",
            "street_1": "1000 Broadway",
            "street_2": "1st Floor",
            "city": "New York",
            "state": "NY",
            "country": "USA",
            "zip_code": "10027"
         },
         {
            "type": "BILLING",
            "street_1": "123 E 12th St",
            "street_2": "Apt 100",
            "city": "New York",
            "state": "NY",
            "country": "USA",
            "zip_code": "10027"
         }
      ],
      "phone_numbers": [
         {
            "type": "MOBILE",
            "number": "+1234567890"
         },
         {
            "type": "PHONE",
            "number": "+1234567890"
         }
      ],
      "tax_number": "12-3456789",
      "is_customer": true,
      "email_address": "[email protected]",
      "integration_params": {
         "Notes": "This is a subcustomer",
         "job": true,
         "bill_with_parent": true
      },
      "linked_account_params": null
   }
}

Sage Intacct

Document sequence and required integration parameters

In some Sage Intacct instances, if document sequencing is not enabled, Sage Intacct requires you to provide a customer or vendor ID in the request. To include this value, set:

  • integration_param.sage_customer_or_vendor_id = the target Sage Intacct Customer ID (or Vendor ID, depending on the object you’re creating).

How we send this to Sage Intacct

If integration_param.sage_customer_or_vendor_id is included in the POST payload, we pass it through to Sage Intacct as:

  • CUSTOMERID (for customers), or

  • VENDORID (for vendors)

If it’s not included, we omit CUSTOMERID / VENDORID and Sage Intacct will automatically determine the ID.

Request examples for Sage Intacct POST Contact

Vendor

{
  "model": {
    "name": "Aesop Vendor",
    "is_supplier": true,
    "is_customer": null,
    "email_address": "[email protected]",
    "status": null,
    "currency": "USD",
    "addresses": [
      {
        "type": "DEFAULT",
        "street_1": "212 E 53rd St",
        "street_2": "4th Floor",
        "city": "New York",
        "country_subdivision": "NY",
        "country": "US",
        "zip_code": "10027"
      },
      {
        "type": "PAYTO",
        "street_1": "415 Charleston Ave",
        "city": "Holly Oak",
        "state": "DE",
        "country": "US",
        "zip_code": "19809"
      }
    ],
    "phone_numbers": [
      {
        "number": "+1234567891",
        "type": "Mobile"
      },
      {
        "number": "+1234567890",
        "type": "Default"
      }
    ]
  }
}

Customer

{
  "model": {
    "name": "Customer Aesop",
    "is_customer ": true,
    "is_supplier": null,
    "email_address": "[email protected]",
    "status": null,
    "currency": "USD",
    "addresses": [
      {
        "type": "DEFAULT",
        "street_1": "212 E 53rd St",
        "street_2": "4th Floor",
        "city": "New York",
        "country_subdivision": "NY",
        "country": "US",
        "zip_code": "10027"
      },
      {
        "type": "PAYTO",
        "street_1": "415 Charleston Ave",
        "city": "Holly Oak",
        "state": "DE",
        "country": "US",
        "zip_code": "19809"
      }
    ],
    "phone_numbers": [
      {
        "number": "+1234567891",
        "type": "Mobile"
      },
      {
        "number": "+1234567890",
        "type": "Default"
      }
    ],
    "integration_params": {
      "sage­_customer­_or­_vendor­_id": "12345"
    }
  }
}

Xero

Character limits

Xero name field supports up to 255 characters.

Xero does not support angle brackets, white space at the start or end, or repeating spaces for the name field.

Setting isSupplier and isCustomer

You may attempt to set is_supplier and is_customer in your requests, but Xero does not allow their isSupplier and isCustomer fields to be set via PUT or POST in their API.

These fields are automatically set by Xero after activity occurs on the contact:

  • isSupplier is set when an AP transaction (e.g., a bill) is created for the contact

  • isCustomer is set when an AR transaction (e.g., an invoice) is created for the contact

Suggested approach: If you would like the appropriate flag to be set shortly after creating a contact, create an AR invoice or AP bill for that contact soon after the contact is created.

Address types

If you include an address object in your request set the address_type as either of these two values

  • SHIPPING

  • BILLING

In the request to Xero, these map to:

  • SHIPPING → POBOX (default mailing address)

  • BILLING → STREET

Request example for Xero POST Contact

Creating a contact

{
  "model": {
    "name": "Dunder Mifflin",
    "is_supplier": false,
    "is_customer": false,
    "email_address": "[email protected]",
    "tax_number": "361552883",
    "status": "ACTIVE",
    "currency": "USD",
    "company": null,
    "addresses": [
      {
          "type": "BILLING",
          "street_1": "11 Park Ave S",
          "street_2": "Suite 1",
          "city": "New York",
          "state": "NY",
          "country_subdivision": "NY",
          "country": "US",
          "zip_code": "10016"
      }
    ],
    "phone_numbers": [
        {
            "number": "+1 (833) 732-3324",
            "type": "DEFAULT"
        }
    ]
  }
}

Conclusion

POSTing Contacts through Merge's Accounting Unified API follows a consistent pattern, but each platform has its own requirements that can cause failures if overlooked. When in doubt, use the GET /contacts/meta/post endpoint before writing your integration. It returns the required fields for the specific Linked Account you're targeting, saving debugging time later.

If you run into issues or have questions about a specific integration, reach out to Merge Support for assistance.