API - Customers - Create or Update | API

Create a new customer, or update an existing one, with a POST request to the Customers endpoint.

Action	Method	URL	API key permission	Package
Create	`POST`	`https://rental.software/api6/customers`	Customers: Full Access	WP/API
Update	`POST`	`https://rental.software/api6/customers/{customer_id}`	Customers: Full Access	WP/API

To update an existing customer, put the Customer ID in the URL, for example /api6/customers/234567, and send the fields you want to change. Any fields not sent will remain the same.

Note: updates use POST. A PUT request is refused with HTTP 405.

Request

All of the parameters below are optional. Send them as form fields or as a JSON body.

POST /api6/customers/?apiKey=YOUR_API_KEY {
  firstname: Jordan
  lastname: Rivera
  name: Jordan Rivera
  organization: Big Company
  cellphone: 330-555-0144
  homephone: 330-555-0142
  officephone: 330-555-0143
  fax: 330-555-0145
  street: 123 Happy St.
  city: Harperville
  state: OH
  zip: 44444
  country: United States
  custtags: Individual,Birthday,Funny
  cleartags: 1
  email: jordan.rivera@example.com
  customertype: Residential
  custnotes: Has a rabid cat.
  customfields_ids: {"35854": "custom field response"}
}

Parameter	Description
`firstname`, `lastname`	Customer name
`name`	Full name in one field. Use this instead of `firstname` and `lastname` if you only have one name box. It is split into first and last name for you
`organization`	Company or organization name
`cellphone`, `homephone`, `officephone`, `fax`	Phone numbers. We format these if we can, so you can send numbers only
`email`	Email address
`street`, `city`, `state`, `zip`, `country`	Address
`customertype`	Should match one of the customer types defined in your account
`custnotes`	Notes saved on the customer
`custtags`	Comma separated tags to attach to the customer
`cleartags`	`1` or `0`. Set to `1` if you want `custtags` to replace the tags already saved
`customfields_ids`	Custom field answers as a JSON string: `{"custom field id": "custom field response"}`. You can find the IDs in the `customfields_ids` of a retrieved customer
`locationid`	Multi-location accounts only. The location to create the customer under. If you do not send it and the API key is limited to certain locations, the customer is created under the key's first location
`_body`	Send `true` to get the full customer record back instead of the short response

Things to Know When Updating

A field sent with an empty value is treated the same as a field that was not sent. You cannot blank out a field through the API.
Send customfields_ids as a JSON string, even when the rest of the request is a JSON body.

Example

curl -X POST "https://rental.software/api6/customers" \
  -d "apiKey=YOUR_API_KEY" \
  -d "name=Jordan Rivera" \
  -d "email=jordan.rivera@example.com" \
  -d "cellphone=330-555-0144" \
  -d "customertype=Residential"

For a complete PHP sample see API - PHP Example.

Response

Status	Meaning	`recordid` contains
`201` Created	A new customer was created	The new customer ID
`200` OK	The existing customer was updated	The customer ID
`409` Conflict	A matching customer already exists, so a new one was not created	The ID of the existing (duplicate) customer

{
  "status": 201,
  "message": "Created",
  "recordid": 533297,
  "request_time": 1760000000
}

Treat both 201 and 409 as success when all you need is the customer ID. Duplicates are detected using the duplicate customer settings of your account. Depending on those settings, the existing customer may be updated with the values you sent.

Errors

Status	Message	What to do
`403`	Permission access restricted	Set Customers to Full Access on the API key
`403`	Location access restricted	The customer belongs to a location the key cannot access
`404`	Customer not found	The customer ID in the URL does not exist in your account
`405`	Only accepts GET, POST, and DELETE requests	Use POST to create or update

Deleting a Customer

Send a DELETE request with the Customer ID in the URL. The key needs Customers Full Access.

DELETE /api6/customers/234567?apiKey=YOUR_API_KEY

A customer that has leads is not removed. It is marked inactive instead, so the leads keep their customer.

API - Customers - Create or Update