Reminders
When an invoice is not settled within the payment period set by the client a customer may need to be reminded of the outstanding debt. If a first reminder is ignored a second one may be sent with a more severe tone. When a customer has not settled a debt after several reminders a notice of default may be sent to indicate that legal action will be taken if the customer does not settle the debt on a very short term. This article describes how reminders of different severities are implemented by Profifact and how the Profifact service can be used to create them.
Index
Introduction
Unsettled debts are part of any business and can consume a lot of time and energy. Notifying customers and tracking when which notifications were sent is an important aspect of it. Profifact provides a flexible yet simple approach to reminding customers of outstanding debts. Clients can create any number of reminders for one or more invoices with one of three types that increase in severity:
- INFORMAL
- Indicates that the reminder is an informal notice (in Dutch: herinnering). The customer is notified of the fact that the payment period is expired in an informal style that takes into account that the customer may not have received the invoice or may have forgotten it.
- FORMAL
- Indicates that the reminder is a formal notice (in Dutch: aanmaning). The customer is expected to be aware of the outstanding debt and has refused or neglected to settle it.
- DEFAULT
- Indicates that the reminder is a notice of default (in Dutch: ingebrekestelling). The customer is aware of the outstanding debt, has received multiple admonitions to settle it, but has not yet done so. The client is warning the customer that legal action will be taken if the debt is not settled on a very short term.
Clients may send one reminder of each type, but may for example also decide to send multiple informal notices before sending a formal notice. However a client decides, Profifact keeps track of the reminders that are created along with the payment statuses at the time of creation. This way the client builds a file for a customer that can be referred to in case of legal action such as transferring the responsibility for debt collection to a specialized agency or a bailiff.
Retrieving multiple reminders
Clients can retrieve multiple reminders by sending an HTTP GET request to /reminders. Reminders can be retrieved as a set of reminder objects or as a set of summarized reminder records. The former is useful when the client wants reminder objects exactly as returned when retrieving a single reminder. The latter is more useful if the results are to be displayed in a table.Authentication is required and only reminders 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 reminders, multiple requests are needed to retrieve all items.
Request
HTTP GET requests to /reminders 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.
- summary
- Specifies whether to return summaries or objects. Valid values are 0 to indicate reminder objects must be returned (i.e. no summarized information) and 1 to indicate that the server should return summarized reminder information. 0 is the default value and yields the same results as not specifying the summary parameter at all.
- customerId
- A unique ID of the customer whose reminders to return. If specified, only reminders of a particular customer are returned. All three ID forms defined in the support section on retrieving a customer are supported.
- invoiceId
- The integer unique ID of an invoice belonging to the client. If specified only reminders created for sets of invoices that include the invoice with the specified ID are returned.
Examples
// Retrieve reminders 8 through 15:
GET /reminders?offset=8&limit=8 HTTP/1.1
// Retrieve upto 100 reminders for a particular invoice:
GET /reminders?invoiceId=1037382 HTTP/1.1
// Sort reminders by invoice and then by type and date:
GET /reminders?order=invoiceId,type,date HTTP/1.1
// Sort reminders by ID in descending order
GET /reminders?order=-id HTTP/1.1
// Retrieve the first 100 reminder objects for a customer by ID (both are equivalent):
GET /reminders?customerId=989732 HTTP/1.1
GET /reminders?customerId=id:989732 HTTP/1.1
// Retrieve the first 100 reminder objects for a customer by address ID:
GET /reminders?customerId=addressId:5941 HTTP/1.1
// Retrieve the first 100 reminder objects for a customer by external ID:
GET /reminders?customerId=externalId:JQ88P003 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 tables below. See the section on data types for an explanation of property data types.
If the summary parameter is not specified or has value 0 the following fields are returned:
| 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 possibly empty array of the reminder objects selected for being returned based on the request. For each object the server returns exactly the properties defined by the Retrieving a reminder response. |
Otherwise, if the summary parameter is specified and has value 1 the following fields are returned:
| 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 possibly empty array of the reminder summary records selected for being returned based on the request. |
| id | int | The unique ID of the reminder assigned by Profifact. |
| customerAddressId | int | The unique ID of the version of the address of the customer associated with the reminder. Customer addresses may change over time, but a reminder always keeps a reference to the version of the address that was assigned to it when it was created. The only time the customer address ID of a reminder changes is when the client modifies the address of the customer while the reminder has status CONCEPT. The reference held by the reminder is then updated to the new version of the customer address. |
| number | int | The number assigned to the reminder by Profifact. Reminder numbers start with the year in which they were created. The year in the reminder number is always the same as the year in the date of the reminder. The last four digits of the reminder number are the index of the reminder in that year. |
| date | date | The date of the reminder. |
| type | string | The type of the reminder as defined in the introduction. |
| customerName | string | The name of the customer of the reminder. |
| amountUnpaid | decimal | The sum of the unpaid amounts of all invoices associated with the reminder at the time the reminder was created. |
| invoices | An object of key-value pairs where each key is the unique ID of an invoice associated with the reminder and each value is the number of that invoice. Reminders cannot be sorted by this property, because the results would not be meaningful. |
Retrieving a reminder
Clients can retrieve a single reminder by sending an HTTP GET request to /reminders/RESOURCE_ID where RESOURCE_ID is the unique identifier of the requested reminder.Request
Reminders can be retrieved invoices in two formats, JSON and PDF. Which of the two is returned for a particular request depends on the value of the Accept request header. If the first acceptable media type specified in the Accept header is application/json, the server returns a JSON representation of the reminder. If the first acceptable media type is application/pdf, the server returns a rendered PDF representation of the reminder.Currently, no additional GET parameters are supported for requests to /invoices/RESOURCE_ID.
Examples
// Retrieve the JSON reprsentation of a reminder by its unique ID:
GET /reminders/83922281 HTTP/1.1
Accept: application/json
// Retrieve a PDF representation of the same reminder:
GET /reminders/83922281 HTTP/1.1
Accept: application/pdf
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 the data requested by the client. Requesting a PDF representation causes the service to return binary PDF data that can be stored as a PDF file. Requesting a JSON representation causes the service to return a reminder object whose members are shown in the table below. See the section on data types for an explanation of property data types.
| Name | Type | Description |
|---|---|---|
| id | int | The unique ID of the invoice assigned by Profifact. |
| clientAddressId | int | The unique ID of the version of the client's address associated with the reminder. Client addresses may change over time, but a reminder always keeps a reference to the version of the address that was assigned to it when it was created. |
| customerAddressId | int | The unique ID of the version of the address of the customer associated with the reminder. Customer addresses may change over time, but a reminder always keeps a reference to the version of the address that was assigned to it when it was created. |
| templateId | int | The unique ID of the version of the template associated with the reminder. Reminder templates may change over time, but a reminder always keeps a reference to the version of the template that was assigned to it when the invoice was created. |
| type | string | The type of the reminder as defined in the introduction. |
| date | date | The date of the reminder. |
| number | int | The number assigned to the reminder. Reminder numbers start with the year in which they were created. The year in the reminder number is always the same as the year in the date of the reminder. The last four digits of the reminder number are the index of the reminder in that year. |
| invoices | array | The array invoices for which the reminder is a notice. A reminder is associated with at least one invoice. If a reminder is associated with multiple invoices, all invoice belong to the same customer. |
| id | int | The unique ID of the invoice assigned by Profifact. |
| number | int | The number of the invoice. Because reminders cannot be created for concept invoices, the value of this property will never be null. |
| date | date | The date of the invoice. |
| status | string | The current status of the invoice as defined in the introduction to the /invoices resource. |
| paymentPeriod | int | The payment period of the invoice in days. Valid values are in the range from 0 to 999. |
| reminderIndex | int | The index of the reminder for the invoice (i.e. the reminder is the n-th reminder for this invoice). |
| amountUnpaid | decimal | The amount of the invoice that was unpaid at the time the reminder was created. |
| total | decimal | The total amount of the invoice including VAT. |
Creating a reminder
A new reminder can be created by sending an HTTP POST request to /reminders. The request body must contain values for at least the mandatory reminder properties encoded in the content type indicated by the client through the Content-Type header. Currently only JSON encoded data is supported.Request
Creation of a reminder requires a non-empty set of invoice IDs that belong to unsettled
or uncollectible invoices owned by the client. Reminders cannot target concept or paid
invoices. The only other value that is required is the type of new reminder as defined
in the introduction. A date and a reminder number are automatically assigned. Reminders
are alwas assigned the current date. A reminder template ID may be specified, but is not
required.
Unlike invoices and offers, reminders do not have statuses. They are definitive when
created and cannot be changed or deleted. The responsibility for sending the reminder
to the customer lies with the client. See the support article on the
/remindermails
resource for how to send reminders by email using the Profifact service.
HTTP POST requests to /reminders are validated before a
reminder 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. See the section on data types for an
explanation of property data types.
| Name | Type | Valid values | Description |
|---|---|---|---|
| invoiceIds | array | A non-empty array containing the unique IDs of the invoices for which to create a new reminder. Reminders can be created for upto 10 invoices. | |
| type | string | INFORMAL, FORMAL or DEFAULT | The type of the new reminder as defined in the introduction. |
| templateId | int? | The unique ID of a reminder template. If empty or not specified the client's default reminder template is used. |
Examples
// A minimal example that creates a reminder for a single invoice:
POST /reminders HTTP/1.1
{
"invoiceIds":[ 103988 ],
"type":"INFORMAL"
}
// A more complex example that creates a reminder for multiple invoices of
// the same customer and specified the reminder template to be used:
// A minimal example that creates a reminder for a single invoice:
POST /reminders HTTP/1.1
{
"invoiceIds":[ 2689223, 9012293, 199852 ],
"type":"DEFAULT"
"templateId":444208
}