Customers

API version 1.6.0

Customers are a central part of the Profifact application. Before clients can create invoices and offers, they must first create customers to whom the invoices and offers can be sent. This article describes how customers can be created, retrieved, updated and deleted.

Index

Introduction
Retrieving multiple customers
1. Request
2. Response
Retrieving a customer
1. Request
2. Response
Creating a customer
1. Request
2. Response
Updating a customer
1. Request
2. Response
Deleting a customer
1. Request
2. Response

Introduction

The customer model and its relations to other models

Customers belong to customer groups and are referenced by invoices, offers and reminders. Each customer may has a unique ID which is assigned automatically by Profifact and may also have a unique ID assigned by the client. The latter is called an external ID. External IDs allow clients to use their own customer IDs in Profifact an thereby associate customers in Profifact with customers in their own applications (e.g. an accounting system).
An important aspect of Profifact is the fact that it never modifies invoices and offers after they have been marked SENT (definitief in Dutch). Therefore, if the address of a customer changes, Profifact automatically creates a copy of the old address information that is used for previously created invoices and offers. Invoices and offers with status CONCEPT (concept in Dutch) are automatically updated to use the new cusotmer address information. To distinguish between the addresses of a customer, a customer returned by the Profifact service has an address ID in addition to its ID and external ID. Address IDs are assigned by Profifact and cannot be modified, but it is possible to retrieve old customer address by address ID. The archived field indicates whether the returned customer information is old or current.

Retrieving multiple customers

Clients can retrieve multiple customers by sending an HTTP GET request to /customers. Authentication is required and only customers owned by the client are returned. If no limit is specified, the maximum number of items returned is 100. If a client has more than 100 customers, multiple requests are needed to retrieve all customers.

Request

HTTP GET requests to /customers may include any of the following GET parameters:

order

A comma separated set of field names specifying the sort order of the matching items. A minus sign preceeding a field name indicates descending sort order.

offset

The offset of the first item to return from the collection of matching items.

limit

The maximum number of items to return.

groupId

The integer unique ID of a customer group belonging to the client. If specified only customers from the customer group with that ID are returned. See the article on customer groups for more information.

search

A string representing one to four search terms. If specified only customers that match all terms are returned. Terms must be separated by whitespace or enclosed in double quotes. To add a double quote inside a double quoted term, use two consecutive double quotes. If a double quote is unmatched, an extra double quote is assumed at the end of the string. The following customer properties are searched for the specified terms:

external_id
name
contactperson
address
zipcode
city
phonenumber
mobilenumber
faxnumber
email
website
vatnumber
banknumber

Examples


            // Retrieve customers 10 through 29:

            GET /customers?offset=10&limit=20 HTTP/1.1

            

            // Retrieve upto 100 customers from a particular group:

            GET /customers?groupId=98327 HTTP/1.1

            

            // Sort customers by city and then name:

            GET /customers?order=city,name HTTP/1.1

            

            // Sort customers by ID in descending order:

            GET /customers?order=-id HTTP/1.1

            

            // Retrieve customers matching search term "Jane". The third form causes a

            // double quote to be assumed at the end of the search value:

            GET /customers?search=Jane HTTP/1.1

            GET /customers?search=%22Jane%22 HTTP/1.1

            GET /customers?search=%22Jane HTTP/1.1

            

            // Retrieve customers matching search terms "Jane" and "Lowood":

            GET /customers?search=Jane%Lowood HTTP/1.1

            

            // Retrieve customers matching search term "Jane Eyre":

            GET /customers?search=%22Jane%20Eyre%22 HTTP/1.1

            

            // Retrieve customers matching search terms "Jane Eyre" and 'Edward "Ed" Rochester':

            GET /customers?search=%22Jane%20Eyre%22%20%22Edward%20%22%22Ed%22%22%20Rochester%22 HTTP/1.1

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a data structure with the members defined in the table below. See the section on data types for an explanation of property data types.

Name	Type	Description
count	int	Specifies the number of items returned.
total	int	Specifies the total number of matching items.
offset	int	Specifies the offset of the first returned item in the collection of all matching items.
items	array	The array of the customer objects selected for being returned based on the request. For each object the server returns exactly the properties defined by the Retrieving a customer response.

Retrieving a customer

Clients can retrieve a single customer by sending an HTTP GET request to /customers/RESOURCE_ID where RESOURCE_ID is a unique identifier of the requested customer. A customer can have multiple addresses over time. All of those addresses except the most recent one are marked as archived. By default, when retrieving a customer, only that most recent address is returned.

Request

As described in the introduction, a customer has multiple identifiers and each of those can be used to retrieve a customer. The following forms are supported for RESOURCE_ID:

/customers/id:ID: Use this form to retrieve a customer by its unique Profifact ID. Profifact customers IDs are positve integers that never change, not even if a customer is assigned a new address. This form is the default and the id: prefix may be omitted. Retrieving a customer by its unique Profifact ID always returns the current non-archived customer address.
/customers/addressId:ID: Use this form to retrieve a customer by the unique ID of one of the customer's addresses. This form is particularly useful when retrieving the customer address of a particular invoice or offer, because invoices and offers reference customer addresses, not customers. Depending on the specified ID, this form may return either an archived or the current non-archived customer address. Like customer IDs, customer address IDs are positive integers.
/customers/externalId:ID: Use this form to retrieve a customer by its unique client assigned ID. Client assigned customer IDs are controlled by the client and may be changed by the client. Client assigned IDs can be 1 to 16 characters in length and are case sensitive. This form always returns the current non-archived customer address.

Currently, no additional GET parameters are supported for requests to /customers/RESOURCE_ID.

Examples


            // Retrieve a customer by its unique ID (both forms are identical):

            GET /customers/23479 HTTP/1.1

            GET /customers/id:23479 HTTP/1.1

            

            // Retrieve a customer by one of its address IDs:

            GET /customers/addressId:126838 HTTP/1.1

            

            // Retrieve a customer by its external ID:

            GET /customers/externalID:C1038741 HTTP/1.1

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a customer object whose members are shown in the following table. See the section on data types for an explanation of property data types.

Name	Type	Description
id	int	The unique ID of the customer assigned by Profifact.
addressId	int	The unique ID of the customer address returned for the customer.
externalId	string?	The case sensitive unique ID of the customer assigned by the client.
groupId	int	The unique ID of the customer group to which the customer belongs.
countryId	string	The two-letter country code of the customer.
archived	boolean	Specifies whether the returned customer address is archived (i.e. not the most recent address).
name	string	The name of the customer.
contact	string?	The contact of the customer.
address	string	The address (street, number and extension) of the customer.
zipCode	string	The zip code of the customer.
city	string	The city of the customer.
country	string	The full country name of the customer.
phone	string?	The phone number of the customer.
mobile	string?	The mobile phone number of the customer.
fax	string?	The fax number of the customer.
email	string?	The email address of the customer.
website	string?	The domain name or URL of the customer's website.
vatNumber	string?	The VAT number of the customer.
bankAccountNumber	string?	The international bank account number (IBAN) of the customer.
paymentPeriod	int?	The payment period assigned to the customer. A payment period defines a number of days after an invoice is sent during which the customer is expected to fulfill payment. If the value of this property is null the global payment period in the billing settings of the client applies instead.
comments	string?	The comments added to the customer by the client.

Creating a customer

A new customer can be created by sending an HTTP POST request to /customers. The request body must contain values for at least the mandatory customer properties encoded in the content type indicated by the client through the Content-Type header. Currently only JSON encoded data is supported.

Request

HTTP POST requests to /customers are validated before a customer is created. Valid requests must provide valid values for the mandatory fields listed in the table below. If specified, values for optional fields must be valid as well. If specified, a country ID must be a valid two letter country code of a country known to Profifact. By default customers are assumed to reside in The Netherlands (country code nl). If a customer group ID is specified, it must be the unique ID of a customer group owned by the client. If no customer group ID is specified, the new customer is added to the client's customer group that has type SYSTEM_CUSTOMERS (i.e. the default customer group named "Klanten"). Finally, if an external ID is specified, it must not be same as the external ID of any other customer belonging to the client. Clients may provide values for the following properties. See the section on data types for an explanation of property data types.

Name	Type	Valid values	Description
externalId	string?	^.{1,16}$	The case sensitive unique ID of the customer assigned by the client.
groupId	int?		The unique ID of the customer group to which to add the customer.
countryId	string?	^[a-z]{2}$	The two-letter country ID of the customer. Defaults to nl if not specified. Validation of zip codes, VAT numbers and bank account numbers may differ according to the specified country ID. E.g. for country ID nl a valid zip code consist of four digits and two letters whereas zip codes for other country IDs have not such restrictions.
name	string	^.{2,50}$	The name of the customer.
contact	string?	^.{2,50}$	The contact of the customer.
address	string	^.{2,64}$	The address (street, number and extension) of the customer.
zipCode	string	^[1-9][0-9]{0,3} ?[A-Za-z]{2}$ or ^.{2,12}$	The zip code of the customer. Validation depends on the country code specified for the customer. Validation is stricter for customers from The Netherlands.
city	string	^.{2,50}$	The city of the customer.
phone	string?	^[+0]([0-9][ -.]?){5,20}$	The phone number of the customer.
mobile	string?	^[+0]([0-9][ -.]?){5,20}$	The mobile phone number of the customer.
fax	string?	^[+0]([0-9][ -.]?){5,20}$	The fax number of the customer.
email	string?	^[A-Za-z0-9._%+-]+@([A-Za-z0-9-]+\.)+[A-Za-z]{2,6}$	The email address of the customer.
website	string?	^.{1,50}$	The domain name or URL of the customer's website.
vatNumber	string?	^[Nn][Ll]([ .]?[0-9]){9,14}[ .]?[Bb][ .]?[0-9]{2}$ or ^[A-Za-z0-9 .]{6,24}$	The VAT number of the customer. Validation of VAT numbers depends on the country code specified for the customer. Validation is stricter for Dutch customers.
bankAccountNumber	string?	^[Nn][Ll][ .]?[0-9]{2}[ .]?[A-Za-z]{4}([ .]?[0-9]){10}$ or ^[A-Za-z]{2}[ .]?[0-9]{2}([ .]?[A-Za-z0-9]){10,60}$	The international bank account number (IBAN) of the customer. Validation of bank account numbers depends on the country code specified for the customer. Validation is stricter for Dutch customers.
paymentPeriod	int?	0 - 999	The payment period assigned to the customer. A payment period defines a number of days after an invoice is sent during which the customer is expected to fulfill payment. If no value is specified the global payment period in the billing settings of the client applies instead.
comments	string?	^.{0,65535}$	Any client assigned comments for the customer.

Examples


            POST /customers HTTP/1.1

            { "name": "Customer", "address": "Kalverstraat 1", "zipCode": "1012NX", "city": "Amsterdam" }

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 201 Created is returned and the response body contains exactly the same information as the Retrieving a customer response.

Updating a customer

The update method of the Profifact service supports creation of new customers and updating of existing customers. Contrary to the create method a resource ID is required for every HTTP PUT request to /customers/RESOURCE_ID. If the specified resource ID exists, the customer with that ID is updated and otherwise a new customer is created with that ID. When updating an existing customer only the changes have to be specified.
Updating a customer causes a new customer address to be created if the current address is referenced by one or more non-concept invoices or offers. Profifact uses this method to ensure that customer information used by an invoice or offer never changes after an invoice or offer has reached status SENT. Invoices and offers with status CONCEPT never cause this behavior, but are automatically set to the latest customer address if the behavior is triggered by a non-concept invoice or offer.

Request

HTTP PUT requests to /customers/RESOURCE_ID must provide a customer reference that indicates the customer to be updated. The following forms are supported for RESOURCE_ID:

/customers/id:ID: Use this form to update a customer by its unique Profifact ID. Profifact customers IDs are positve integers that never change, not even if a customer is assigned a new address. This form is the default and the id: prefix may be omitted. Using this form it is not possible to create a new customer, because the Profifact customer ID is not assigned by the client.
/customers/externalId:ID: Use this form to update a customer by its unique client assigned ID or to update the exiting customer with that ID. Client assigned customer IDs are controlled by the client and may be changed by the client. Client assigned IDs can be 1 to 16 characters in length and are case sensitive. Use this form as an update-or-create operation similar to the MySQL replace statement.

Examples


            // Update the name of a customer by its Profifact ID:

            PUT /customers/32974 HTTP/1.1

            { "name": "New Name" }

            

            // Create a new customer by specifying a non-existing external ID:

            PUT /customers/externalId:NON-EXISTING HTTP/1.1

            { "name": "Customer", "address": "Kalverstraat 1", "zipCode": "1012NX", "city": "Amsterdam", "externalId": "NON-EXISTING" }

            

            // Update the payment period and bank account number of a customer by its existing external ID:

            PUT /customers/externalId:EXISTING HTTP/1.1

            { "paymentPeriod": 90, "bankAccountNumber": "NL00BANK0123456879" }

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK or HTTP status 201 Created is returned depending on whether a new customer was created. The response body contains exactly the same information as the Retrieving a customer response.

Deleting a customer

The Profifact service allows clients to delete customers, but only customers that are not referenced by invoices or offers. Once an invoice or offer is created for a customer, the customer cannot be removed, because the customer's address is needed for that invoice or offer. It is still possible to modify the customer (see Updating a customer).

Request

To delete a customer, send an HTTP DELETE request to /customers/RESOURCE_ID where RESOURCE_ID is a unique identifier of the customer as defined by the Retrieving a customer request.

Examples


            // Delete a customer by its Profifact ID:

            DELETE /customers/32974 HTTP/1.1

            

            // Delete a customer by its external ID:

            DELETE /customers/externalId:EXAMPLE02 HTTP/1.1

            

            // Delete a customer by the unique ID of its customer address:

            DELETE /customers/addressId:37432 HTTP/1.1

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For valid requests that cause a customer to be deleted and for requests to delete non-existing customers HTTP status 204 No Content is returned. If the client attempts to delete a customer that is referenced by one or more invoices or offers, the server returns HTTP status 403 Forbidden to indicate that it will not allow the client to delete the customer.