Customer groups

API version 1.6.0

Customers created by a client may be grouped in order to provide some additional information about the grouped customers. Every client starts with two two customer groups assigned by the Profifact application: Klanten and Gearchiveerd. This article describes how customer groups can be retrieved and created using the Profifact service.

Index

Introduction
Retrieving multiple customer groups
1. Request
2. Response
Retrieving a customer group
1. Request
2. Response
Creating a customer group
1. Request
2. Response

Introduction

The customer group model and its relations to other models

Customer groups a containers for customers. Every customer belongs to exactly one customer group and customer groups can contain any number of customers. Customer group names must be unique (i.e. a client cannot have two groups with the same name) and have one of three types:

SYSTEM_CUSTOMERS: Indicates that the group is the default customer group of a client. This type is reserved for system groups. Every client has exactly one group with this type named Klanten.
SYSTEM_ARCHIVE: Indicates that the group is used for archived customers that are hidden when selecting a customer in the Profifact front-end application. This type is reserved for system groups. Every client has exactly one group with this type named Gearchiveerd.
CUSTOM: Indicates that the group is a custom group created by the client. Clients can have any number of groups with this type.

By default, Profifact assigns two customer groups named Klanten and Gearchiveerd to new clients. These two groups are system groups and cannot be modified or removed as is indicated by their types (SYSTEM_CUSTOMERS and SYSTEM_ARCHIVE).
Clients can assign customers to customer groups. There are no restrictions on which customer group a customer is assigned to. Profifact service does not currently provide a method for assigning mutliple customers to a new customer group other than updating the customer group of each of the individual customers using the update functionality of the /customers resource.

Retrieving multiple customer groups

Clients can retrieve multiple customer groups by sending an HTTP GET request to /customergroups. Authentication is required and only customer groups owned by the client are returned. No limit to the number of items returned can be specified, because it is very uncommon for a client to have a large number of customer groups. Responses will therefore always contain all customer groups belonging to the client.

Request

HTTP GET requests to /customergroups 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.

Examples


            // Retrieve all customer groups:

            GET /customergroups HTTP/1.1

            

            // Retrieve all customer groups ordered by name:

            GET /customergroups?order=name HTTP/1.1

            

            // Retrieve customer groups sorted ascendingly by type and then descendingly by name:

            GET /customergroups?order=type,-name 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. The value of a member may be null if the type of that member is followed by a question mark.

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 group objects selected for being returned based on the request. For each object the server returns exactly the properties defined by the Retrieving a customer group response.

Retrieving a customer group

Clients can retrieve a single customer group by sending an HTTP GET request to /customergroups/RESOURCE_ID where RESOURCE_ID is a unique identifier of the requested customer group.

Request

Customer groups have two unique identifiers, an ID and a name. Both can be used to retrieve a customer group. The following forms are supported for RESOURCE_ID:

/customergoups/id:ID: Use this form to retrieve a customer group by its unique Profifact ID. Profifact customer groups IDs are positve integers that never change. This form is the default and the id: prefix may be omitted.
/customergroups/name:ID: Use this form to retrieve a customer group by its name. Alternatively, this form can be used to check the existence of a group with a particular name. If the server returns HTTP status 404 Not Found then there is no group with the specified name.

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

Examples


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

            GET /customergroups/23479 HTTP/1.1

            GET /customergroups/id:23479 HTTP/1.1

            

            // Retrieve a customer group by its name:

            GET /customergroups/name:Klanten 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 group object whose members are shown in the following table:

Name	Type	Description
id	int	The unique ID of the customer group assigned by Profifact.
type	string	The type of the customer group as defined in the introduction.
name	string	The unique name of the customer group.

Creating a customer group

A new customer group can be created by sending an HTTP POST request to /customergroups. The request body must contain values for at least the mandatory customer group 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 /customergroups are validated before a customer group 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 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 the following values of which only those whose type name does not end in a question mark are mandatory:

Name	Type	Valid values	Description
type	string	^CUSTOM$	The type of the new group. Because clients can only create groups of type CUSTOM that is the only valid value for this property.
name	string	^.{1,50}$	The name of the new customer group.

Examples


            POST /customergroups HTTP/1.1

            { "name": "My New Group", "type": "CUSTOM" }

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 group response.