VobeSoft API

1Introduction

The VobeSoft API lets your own systems read and change the data of your VobeSoft environment: collections, items, the rows of their lists and their files.

With the API your systems can:

• read the structure of your collections: their categories and their fields;
• read items with their values, and the rows of their lists;
• search items and rows by their values and moments, and ask what changed since your last search;
• create, update and delete items and rows;
• send files with an item or a row, and download them.

1.1 Version 1 and how it changes

This guide describes version 1; every path contains /v1/. Within version 1:

• a response may gain properties, and an error code or a field type may gain values. Ignore properties you do not know, treat an unknown error by its HTTP status, and leave fields of an unknown type alone;
• a property is never removed or renamed, and neither its meaning nor the status codes of an endpoint change.

A change that would break this becomes version 2, with its own paths, offered next to version 1 until clients have moved.

2Getting started

From a new key to a first item in five steps: one in VobeSoft, four calls.

1. Create a key in Settings, API (section 3.1). Its form shows the endpoints that are open for your organization: choose those your system needs, and give the key permissions on the collections it works with (section 4).
2. List the collections the key may read with GET /collections (8.1), and note the id of the one you need.
3. Read its structure with GET /collections/{collectionId} (8.2). It gives the ids of its categories and fields.
4. Create an item with POST /collections/{collectionId}/items and the values of its fields (10.1). The response gives the id of the new item.
5. Read the item back with GET /collections/{collectionId}/items/{itemId} (9.1).

3Authentication

Every call identifies itself with an API key: a secret token that an administrator of your organization creates in VobeSoft. The key decides which endpoints the call may use and which data it may see and change.

A key belongs to your organization, not to the person who created it. Changes made with a key show in the history of an item as changes made by the API.

3.1 Creating a key

Keys are created in VobeSoft by a user whose role may manage API keys. A key is never sent to you by VobeSoft: your organization creates and controls its own keys.

1. In VobeSoft, open Settings and choose API. The page lists the keys of your organization and what they used of your budget.
2. Choose New API key and give the key a name that tells which system uses it, for example CRM synchronization.
3. Choose an expiry date, at most two years from today. The key works up to and including that day.
4. Choose the endpoints the key may call, and give it permissions on the collections and categories it needs. Section 4 explains both.
5. If you want, give the key limits of its own below your organization's budget, so one system can never use up the budget of the others. Section 5 explains limits.
6. Choose Create key. VobeSoft shows the key once. Copy it and store it where your system reads its secrets.

3.2 What a key looks like

A key is a single line of 55 characters: a prefix of 11 characters, a dot and a secret of 43 characters.

Send the whole line, prefix and dot included, exactly as VobeSoft showed it.

3.3 Sending the key

Send the key in the X-Api-Key header of every request, over HTTPS. There is no login call and no session: each request stands on its own.

curl "https://www.vobesoft.nl/vobesoft/api/external/v1/collections" \
  -H "X-Api-Key: $VOBESOFT_API_KEY"

When the key is accepted, the call responds as usual. This one lists the collections the key may read:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Correlation-Id: 7c4f2a9e-1b3d-4e8a-9c21-7d5e0f6a3b12

{
  "totalCount": 3,
  "results": [
    { "id": 3100, "name": "Advisors" },
    { "id": 3200, "name": "Customers" },
    { "id": 3300, "name": "Policies" }
  ],
  "pageIndex": 0,
  "pageSize": 25
}

The key is only read from the X-Api-Key header. A key in the address, in a query parameter or in an Authorization header is not read, and the call is treated as one without a key. Send the header once: a request with two X-Api-Key headers is refused.

3.4 When a key is refused

A call whose key cannot be used returns 401 with the code UNAUTHENTICATED. The response is the same whatever the reason:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
X-Correlation-Id: 0b17ad0c-eccc-43d7-b7bb-771436fb94e5

{
  "code": "UNAUTHENTICATED",
  "message": "The API key is missing, invalid, disabled, or expired.",
  "correlationId": "0b17ad0c-eccc-43d7-b7bb-771436fb94e5"
}

While your environment is in maintenance, a call with a valid key returns 503 MAINTENANCE. Wait the number of seconds in the Retry-After header (300) and try again.

An accepted key can still be refused a call, when the endpoint is not granted to it or a limit is reached. Sections 4 and 5 explain those responses.

3.5 The life of a key

• Expiry. Every key has an expiry date at most two years ahead. After that day every call with the key is refused. Before then, an administrator can move the date by editing the key, to at most two years from the day of the edit.
• Disabling and enabling. An administrator can disable a key in Settings, API, and enable it again later. Both take effect from the next call.
• Changing a key. Changes to a key's name, expiry date, endpoints, permissions and limits also apply from the next call. The key itself, the line your system sends, never changes.
• Seeing use. The list of keys shows when each key was last used and what it used of your budget. A key's Access log lists its calls, newest first, each with its status, error code and correlation id.

Replacing a key without downtime

Your organization can have several keys at the same time. To replace a key, for example before it expires:

1. Create a new key with the same endpoints, permissions and limits.
2. Give the new key to your system and check that its calls succeed.
3. Disable the old key.

All keys of your organization share one budget, so the old and the new key together never get more calls than one key would (section 5).

4Endpoints and permissions

A call succeeds only when it passes three checks: the endpoint is open for your organization, the key has the endpoint, and the key has permission on the data.

4.1 Endpoints

An endpoint is a group of calls that a key is given as a whole. The names are those of the key form.

When VobeSoft closes an endpoint for your organization, every key is refused that endpoint from then on. The keys keep it, and it works again when the endpoint opens.

4.2 Permissions

A key's permissions are set per collection, per category and per list category, as for a role in VobeSoft.

The key form saves only a consistent set: create, update and delete each come with read on the same collection, category or list category; a permission on a category needs the same permission on its collection; a permission on a list category needs read on its collection.

What each call needs

5Limits

VobeSoft limits how many calls your organization makes per endpoint, how many calls one key runs at the same time, and how long one call may take.

5.1 Three windows

Every endpoint has its own limits over three windows:

A call takes its place in the minute when it ends, so a long call counts in the minute in which it finishes. A day may be unlimited; a minute and a month always have a limit. Settings, API shows the limits of every endpoint and what your organization used of them.

5.2 One budget for all keys

The limits belong to your organization and are shared by all its keys: two keys reading items share the same minute, day and month limits. Your administrator can give a key a lower limit of its own for an endpoint, so one system can never use the whole budget. Such a key is refused when either its own limit or the organization's is reached.

VobeSoft can also set a total for your organization over all endpoints together, per minute, day or month. It counts the calls of all your keys on every endpoint in the same way as the windows of 5.1. When a window of the total is used up, every endpoint is refused until that window frees up. Settings, API shows the total and what your organization used of it when your organization has one.

5.3 Calls at the same time

One key runs only a limited number of calls at the same time, over all endpoints together; Settings, API shows the number. A call over it is refused with 429 CONCURRENCY_LIMIT_REACHED and Retry-After: 1, without the limit headers of 5.4, and counts toward no window. Send the calls of one key one after another, or wait until one of its running calls has finished. Each key counts only its own calls, so another key of your organization is not held back.

5.4 Limit headers

The response to a call that passes the endpoint checks of section 4 carries the state of the tightest minute limit for that endpoint: the organization's, the key's own, or your organization's total over all endpoints:

RateLimit-Limit: 60;w=60
RateLimit-Remaining: 59
RateLimit-Reset: 60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 60

A 429 response (5.5) carries these headers for the limit that was reached instead, except CONCURRENCY_LIMIT_REACHED, which has none (5.3). After the daily limit, for example, RateLimit-Limit shows the day's limit with w=86400, RateLimit-Remaining is 0 and RateLimit-Reset gives the seconds until 00:00 UTC. The headers do not show what is left of the day and the month before a limit is reached; Settings, API does.

5.5 When a limit is reached

Wait at least the seconds of Retry-After before calling again. A call refused for a limit does not count toward your limits, but it is refused again until the window frees up, or for calls at the same time until one of the key's running calls has finished. A used up minute, day or month of one endpoint leaves the other endpoints free. Your organization's total (5.2) refuses every endpoint with the same code, and calls at the same time (5.3) count over all endpoints.

5.6 How long a call may take

A call has a time limit of one minute from the moment VobeSoft takes it up, which for a small body is once the body has arrived. When it is reached:

• a body that has not fully arrived returns 408 REQUEST_TIMEOUT and the connection closes; nothing is written;
• a search that is not answered yet returns 504 PROCESSING_TIMEOUT; narrow it with more conditions.

Every other call, and a create or update whose body has arrived, is carried out in full, also when it takes longer.

6Requests and responses

6.1 Paths

Every path starts with https://www.vobesoft.nl/vobesoft/api/external/v1 and names the data in the words of this guide: collections, their categories, their items, the rows in a list category of an item, and files. Inside a body, a field is named by its fieldId. When your organization works in a VobeSoft environment of its own, use that environment's address instead; VobeSoft tells you which.

6.2 JSON

• Bodies are JSON in UTF-8 with names in camelCase. Send Content-Type: application/json, or multipart/form-data when you send files (section 12). A body, or a part of one, in another character set than UTF-8, or with bytes that are no UTF-8, returns 400.
• A body takes only the members this guide names, each once, and every member it needs, such as a value's fieldId. Anything else, such as value instead of values, returns 400 VALIDATION_FAILED, and details tells where in the body it is. Names match whatever their case.
• Ids are whole numbers; a user is identified by a GUID. An id in a body that does not fit in 64 bits returns 400.
• An empty value is null. In a write, null clears a value.
• A JSON body is at most 1 MB, the body of a search at most 64 KB (15.3), and a multipart/form-data body at most 50 MB (12.1); a larger one returns 413 REQUEST_TOO_LARGE, at once when its Content-Length says so, else as soon as more has arrived. A part of a multipart/form-data body that holds JSON is at most 1 MB as well, and such a body has at most 25 parts.

6.3 Dates and times

Every date and time the API returns is an ISO 8601 moment in UTC, ending in Z, for example 2026-10-01T12:15:17.655Z. In a request, send ISO 8601 in one of these forms:

• a date, 2026-10-01, which is read as 00:00 UTC on that day;
• a date and time, 2026-10-01T09:30 or 2026-10-01T09:30:00, optionally with a fraction of a second, 2026-10-01T09:30:00.655.

A time may end in Z or an offset such as +02:00; without either it is read as UTC. Any other form, such as 01-10-2026, 1/10/2026 or 09:30, returns 400, so a day and a month are never swapped.

A date field holds a day. VobeSoft's screens show it without a time and store the chosen day as 00:00 UTC, so 1 October reads as 2026-10-01T00:00:00Z. Send a date field's value as a date, such as 2026-10-01.

A dateRange chosen in VobeSoft's screens holds 00:00 in the time zone of the person who chose it instead. In the Netherlands a range from 1 October therefore reads as "from": "2026-09-30T22:00:00Z": two hours before UTC midnight in summer, one hour in winter. Take the day of such a moment in the Netherlands' time zone. A range your system sends as dates, such as 2026-10-01, shows as 1 October in the Netherlands.

Other moments, such as a creation date, show in the viewer's time zone. In the Netherlands that is one hour later than UTC in winter and two hours later in summer.

6.4 Paging

A call that returns a list returns one page of it:

The response gives the results of the page and totalCount, the number of results over all pages, so you know how many pages there are. This key may read three collections; asking for pages of two, the second page holds the third:

{
  "totalCount": 3,
  "results": [
    { "id": 3300, "name": "Policies" }
  ],
  "pageIndex": 1,
  "pageSize": 2
}

The number of pages is totalCount divided by pageSize, rounded up. A page past the last one is empty. A negative pageIndex or a pageSize below 1 returns 400 VALIDATION_FAILED.

6.5 What a create returns

A create returns 201 with the id of the new item or row in the body, and its path in the Location header. The path is relative to the server: resolve it against the address you called.

HTTP/1.1 201 Created
Location: /vobesoft/api/external/v1/collections/3300/items/8001
Content-Type: application/json; charset=utf-8

{ "id": 8001 }

An update and a delete return 204 without a body.

7Errors

Every error has the same body, with a fixed code to act on and the correlation id of the call.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
X-Correlation-Id: b500875a-6d03-49f8-a543-ee4cfbf560e9

{
  "code": "VALIDATION_FAILED",
  "message": "The request is invalid.",
  "correlationId": "b500875a-6d03-49f8-a543-ee4cfbf560e9",
  "details": "field 5302: expected a text"
}

7.1 Codes

7.2 What to try again

• 429 and 503: try again after the seconds of Retry-After.
• 408: nothing was written, so the same call can be sent again.
• 504: the same search sent again takes as long; narrow it first.
• 500, or no response at all: try again after a pause, a few times at most, keeping in mind what a repeat does:
  • a create that is sent again can create a second item or row;
  • an update sent again is harmless for values, but adds its files and links a second time, as files and links are added to what a field holds (12.1);
  • a delete sent again returns 404 when the first one went through: the item or row is gone, as intended.
• Every other error: do not send the same request again; it gets the same response.

8Collections and categories

The structure calls tell your system which collections, categories and fields exist, and their ids.

GET /vobesoft/api/external/v1/collections HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

{
  "totalCount": 3,
  "results": [
    { "id": 3100, "name": "Advisors" },
    { "id": 3200, "name": "Customers" },
    { "id": 3300, "name": "Policies" }
  ],
  "pageIndex": 0,
  "pageSize": 25
}

GET /vobesoft/api/external/v1/collections/3300 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

{
  "id": 3300,
  "name": "Policies",
  "categories": [
    {
      "id": 4300,
      "collectionId": 3300,
      "name": "General",
      "isList": false,
      "isReadOnly": false,
      "order": 0,
      "maxItems": null,
      "fields": [
        { "id": 5300, "name": "Policy number", "type": "autoNumber", "isRequired": false, "isReadOnly": false, "order": 1 },
        { "id": 5301, "name": "Product", "type": "choice", "isRequired": false, "isReadOnly": false, "order": 2, "isMultiSelect": false, "choiceListId": 210,
          "choices": [
            { "id": 210001, "text": "Fleet", "isActive": true },
            { "id": 210004, "text": "Liability", "isActive": true },
            { "id": 210002, "text": "Travel", "isActive": false }
          ] },
        { "id": 5302, "name": "Title", "type": "text", "isRequired": false, "isReadOnly": false, "order": 3 },
        { "id": 5303, "name": "Notes", "type": "longText", "isRequired": false, "isReadOnly": false, "order": 4 },
        { "id": 5304, "name": "Start date", "type": "date", "isRequired": false, "isReadOnly": false, "order": 5 },
        { "id": 5305, "name": "Cover period", "type": "dateRange", "isRequired": false, "isReadOnly": false, "order": 6 },
        { "id": 5306, "name": "Account manager", "type": "employee", "isRequired": false, "isReadOnly": false, "order": 7 },
        { "id": 5307, "name": "Premium", "type": "number", "isRequired": false, "isReadOnly": false, "order": 8 },
        { "id": 5313, "name": "Direct debit", "type": "checkbox", "isRequired": false, "isReadOnly": false, "order": 9 },
        { "id": 5308, "name": "Created", "type": "creationDate", "isRequired": false, "isReadOnly": false, "order": 10 },
        { "id": 5309, "name": "Signature", "type": "signature", "isRequired": false, "isReadOnly": false, "order": 11 },
        { "id": 5310, "name": "Documents", "type": "file", "isRequired": false, "isReadOnly": false, "order": 12 },
        { "id": 5311, "name": "Customer", "type": "object", "isRequired": false, "isReadOnly": false, "order": 13, "collectionId": 3200 },
        { "id": 5312, "name": "Annual premium", "type": "formula", "isRequired": false, "isReadOnly": false, "order": 14 }
      ],
      "relation": null
    },
    {
      "id": 4301,
      "collectionId": 3300,
      "name": "Claims",
      "isList": true,
      "isReadOnly": false,
      "order": 1,
      "maxItems": null,
      "fields": [
        { "id": 5320, "name": "Description", "type": "text", "isRequired": false, "isReadOnly": false, "order": 1 },
        { "id": 5321, "name": "Amount", "type": "number", "isRequired": false, "isReadOnly": false, "order": 2 },
        { "id": 5322, "name": "Attachments", "type": "file", "isRequired": false, "isReadOnly": false, "order": 3 }
      ],
      "relation": null
    }
  ]
}

GET /vobesoft/api/external/v1/collections/3300/categories/4301 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

{
  "id": 4301,
  "collectionId": 3300,
  "name": "Claims",
  "isList": true,
  "isReadOnly": false,
  "order": 1,
  "maxItems": null,
  "fields": [
    { "id": 5320, "name": "Description", "type": "text", "isRequired": false, "isReadOnly": false, "order": 1 },
    { "id": 5321, "name": "Amount", "type": "number", "isRequired": false, "isReadOnly": false, "order": 2 },
    { "id": 5322, "name": "Attachments", "type": "file", "isRequired": false, "isReadOnly": false, "order": 3 }
  ],
  "relation": null
}

9Reading items and rows

GET /vobesoft/api/external/v1/collections/3300/items/8001 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

{
  "id": 8001,
  "collectionId": 3300,
  "createdAt": "2026-10-01T12:15:17.655Z",
  "lastEditedAt": "2026-10-20T08:42:11.3172946Z",
  "lastEditedBy": { "id": "3f2b9c1e-7a4d-4e0b-9b6a-1c2d3e4f5a6b", "name": "Mila Jansen" },
  "categories": [
    {
      "id": 4300,
      "name": "General",
      "isList": false,
      "values": [
        { "fieldId": 5300, "type": "autoNumber", "value": "POL-137" },
        { "fieldId": 5301, "type": "choice", "value": [ { "id": 210004, "text": "Liability" } ] },
        { "fieldId": 5302, "type": "text", "value": "Fleet policy Van Dijk" },
        { "fieldId": 5303, "type": "longText", "value": "Renewal agreed by phone." },
        { "fieldId": 5304, "type": "date", "value": "2026-10-01T00:00:00Z" },
        { "fieldId": 5305, "type": "dateRange", "value": { "from": "2026-10-01T00:00:00Z", "to": "2026-12-31T00:00:00Z" } },
        { "fieldId": 5306, "type": "employee", "value": [ { "id": "3f2b9c1e-7a4d-4e0b-9b6a-1c2d3e4f5a6b", "name": "Mila Jansen" } ] },
        { "fieldId": 5307, "type": "number", "value": 1250.5 },
        { "fieldId": 5313, "type": "checkbox", "value": true },
        { "fieldId": 5308, "type": "creationDate", "value": "2026-10-01T12:15:17.655Z" },
        { "fieldId": 5309, "type": "signature", "value": null },
        { "fieldId": 5310, "type": "file", "value": null },
        { "fieldId": 5311, "type": "object", "value": { "itemId": 7001 } }
      ]
    },
    {
      "id": 4301,
      "name": "Claims",
      "isList": true,
      "rowCount": 1
    }
  ]
}

GET /vobesoft/api/external/v1/collections/3300/items/8001/categories/4301/rows?pageIndex=0&pageSize=25 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

{
  "totalCount": 1,
  "results": [
    {
      "id": 9001,
      "itemId": 8001,
      "lastEditedAt": "2026-10-14T13:05:40.0281533Z",
      "lastEditedBy": { "id": "7dc27c45-fc87-4d43-9799-32b2aa34d004", "name": "External API" },
      "values": [
        { "fieldId": 5320, "type": "text", "value": "Windscreen damage" },
        { "fieldId": 5321, "type": "number", "value": 350.0 },
        { "fieldId": 5322, "type": "file", "value": null }
      ]
    }
  ],
  "pageIndex": 0,
  "pageSize": 25
}

GET /vobesoft/api/external/v1/collections/3300/items/8001/categories/4301/rows/9001 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

{
  "id": 9001,
  "itemId": 8001,
  "lastEditedAt": "2026-10-14T13:05:40.0281533Z",
  "lastEditedBy": { "id": "7dc27c45-fc87-4d43-9799-32b2aa34d004", "name": "External API" },
  "values": [
    { "fieldId": 5320, "type": "text", "value": "Windscreen damage" },
    { "fieldId": 5321, "type": "number", "value": 350.0 },
    { "fieldId": 5322, "type": "file", "value": null }
  ]
}

9.4 When an item or row was last edited

Every item and row tells when it was last edited and by whom, in the reads above and in the searches of chapter 15.

An item's lastEditedAt moves when:

• one of its fields changes, saved in VobeSoft's screens, through this API, or by an import that keeps history;
• a row is added to, changed in or removed from one of its lists;
• a row of a linking list is added, changed or removed on the other side: the linked item of a one to many row, and the paired row of a many to many row with that row's item.

A row's lastEditedAt moves when the row is added or changed; its item's moves with it. It does not move for:

• a file added or linked in VobeSoft's document management;
• a change saved without history, such as by some imports and background processes;
• a value VobeSoft computes, such as a formula or mirror field, that changes because something else changed;
• the link of an existing many to many row, the item an item leaves in a one to many list, the row an object field shows in the list of the item it links, and the rows of other items that go when an item is deleted;
• reading.

A deleted item or row is not found any more; nothing reports its deletion.

10Creating, updating and deleting items

Your organization's rules apply to every write; a write they refuse is not saved.

POST /vobesoft/api/external/v1/collections/3300/items HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{
  "values": [
    { "fieldId": 5301, "value": [210004] },
    { "fieldId": 5302, "value": "Fleet policy Van Dijk" },
    { "fieldId": 5303, "value": "Renewal agreed by phone." },
    { "fieldId": 5304, "value": "2026-10-01" },
    { "fieldId": 5305, "value": { "from": "2026-10-01", "to": "2026-12-31" } },
    { "fieldId": 5306, "value": ["3f2b9c1e-7a4d-4e0b-9b6a-1c2d3e4f5a6b"] },
    { "fieldId": 5307, "value": 1250.5 },
    { "fieldId": 5313, "value": true },
    { "fieldId": 5311, "value": { "itemId": 7001 } }
  ]
}

HTTP/1.1 201 Created
Location: /vobesoft/api/external/v1/collections/3300/items/8001
Content-Type: application/json; charset=utf-8

{ "id": 8001 }

{
  "createdFrom": { "fieldId": 5311, "itemId": 7001 },
  "values": [
    { "fieldId": 5302, "value": "Fleet policy Van Dijk" }
  ]
}

PATCH /vobesoft/api/external/v1/collections/3300/items/8001 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{
  "values": [
    { "fieldId": 5307, "value": 1500 },
    { "fieldId": 5303, "value": null }
  ]
}

HTTP/1.1 204 No Content

DELETE /vobesoft/api/external/v1/collections/3300/items/8001 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

HTTP/1.1 204 No Content

11List rows

A list category holds rows. Some lists hold values of their own; others link items of another collection. How you add a row depends on the kind of list.

A list category your organization marks as read only in VobeSoft (isReadOnly in the structure, 8.2) takes no new, changed or deleted rows, whatever the key's permissions. Such a write returns 403 PERMISSION_DENIED with category {id}: read only, before its body is read.

11.1 Three kinds of list

The relation of a list category in the structure (8.2) tells which kind it is.

The customers collection of the example has one list of each linking kind:

[
  {
    "id": 4201,
    "collectionId": 3200,
    "name": "Policies",
    "isList": true,
    "isReadOnly": false,
    "order": 1,
    "maxItems": null,
    "fields": [
      { "id": 5201, "name": "Policy", "type": "object", "isRequired": false, "isReadOnly": false, "order": 1, "collectionId": 3300 }
    ],
    "relation": {
      "kind": "oneToMany",
      "linkFieldId": 5201,
      "relatedCollectionId": 3300,
      "relatedFieldId": 5311,
      "relatedCategoryId": null
    }
  },
  {
    "id": 4202,
    "collectionId": 3200,
    "name": "Advisors",
    "isList": true,
    "isReadOnly": false,
    "order": 2,
    "maxItems": null,
    "fields": [
      { "id": 5202, "name": "Advisor", "type": "object", "isRequired": false, "isReadOnly": false, "order": 1, "collectionId": 3100 }
    ],
    "relation": {
      "kind": "manyToMany",
      "linkFieldId": 5202,
      "relatedCollectionId": 3100,
      "relatedFieldId": 5110,
      "relatedCategoryId": 4101
    }
  }
]

How the two sides stay in step

• One to many. A row in the customer's list and the policy's Customer field are the same link. Adding the row sets the field; setting the field (10.1, 10.2) adds the row. Adding a policy that is in another customer's list moves it to this customer. Deleting the row clears the policy's field; the policy stays.
• Many to many. Adding a row on one side adds the matching row on the other side; deleting either row deletes both. The items themselves stay.

Permissions for a linking list

Besides its permission on the list category (4.2), the key needs on the other side:

• One to many, to add or delete a row: read on the other collection, and update on the category of the field that points back (the policy's Customer field).
• Many to many, to add, update or delete a row: read on the other collection, and the same permission on the list on the other side (the advisor's Customers).

A maximum of rows

A list category with a maxItems (8.2) holds at most that many rows per item, counting every row that is not deleted, also one a user is still adding. A write that would add a row to a full list returns 409 LIST_FULL, naming the list and the item, for example category 4201 of item 7001: holds at most 1 row. Every way of adding a row counts:

• adding a row to a plain or a linking list (11.2, 11.3);
• the matching row a many to many add creates in the other item's list;
• setting the link field of a one to many relation, as a value or as createdFrom (10.1, 10.2), which adds the item to the other item's list.

An item the list links already returns ALREADY_LINKED instead.

POST /vobesoft/api/external/v1/collections/3300/items/8001/categories/4301/rows HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{
  "values": [
    { "fieldId": 5320, "value": "Windscreen damage" },
    { "fieldId": 5321, "value": 350 }
  ]
}

HTTP/1.1 201 Created
Location: /vobesoft/api/external/v1/collections/3300/items/8001/categories/4301/rows/9001
Content-Type: application/json; charset=utf-8

{ "id": 9001 }

{
  "code": "VALIDATION_FAILED",
  "message": "The request is invalid.",
  "correlationId": "70058f7a-c7f2-4a40-9411-84ac7f888bea",
  "details": "link: this list links no item; send the row's values"
}

POST /vobesoft/api/external/v1/collections/3200/items/7001/categories/4201/rows HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{ "link": { "itemId": 8002 } }

HTTP/1.1 201 Created
Location: /vobesoft/api/external/v1/collections/3200/items/7001/categories/4201/rows/9101
Content-Type: application/json; charset=utf-8

{ "id": 9101 }

{
  "totalCount": 2,
  "results": [
    { "id": 9101, "values": [ { "fieldId": 5201, "type": "object", "value": { "itemId": 8002 } } ] },
    { "id": 9100, "values": [ { "fieldId": 5201, "type": "object", "value": { "itemId": 8001 } } ] }
  ],
  "pageIndex": 0,
  "pageSize": 25
}

POST /vobesoft/api/external/v1/collections/3200/items/7001/categories/4202/rows HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{ "link": { "itemId": 7101 } }

HTTP/1.1 201 Created
Location: /vobesoft/api/external/v1/collections/3200/items/7001/categories/4202/rows/9201
Content-Type: application/json; charset=utf-8

{ "id": 9201 }

{
  "totalCount": 1,
  "results": [
    { "id": 9202, "values": [ { "fieldId": 5110, "type": "object", "value": { "itemId": 7001 } } ] }
  ],
  "pageIndex": 0,
  "pageSize": 25
}

{
  "code": "ALREADY_LINKED",
  "message": "The item is already linked in this list.",
  "correlationId": "6ce146c6-3cf1-423f-a305-fb8857db1502"
}

{
  "code": "VALIDATION_FAILED",
  "message": "The request is invalid.",
  "correlationId": "9ced30f6-f749-462e-9759-7588019ac4fd",
  "details": "field 5201: a new row of this relation list takes the item it links in link, not in values"
}

PATCH /vobesoft/api/external/v1/collections/3300/items/8001/categories/4301/rows/9001 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{ "values": [ { "fieldId": 5321, "value": 400 } ] }

HTTP/1.1 204 No Content

DELETE /vobesoft/api/external/v1/collections/3200/items/7001/categories/4202/rows/9201 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

HTTP/1.1 204 No Content

12Files

Files travel with the create or update of an item or a row, in one request; a download is a short lived link.

12.1 Sending files

To send files, send the request as multipart/form-data instead of JSON. Each part has a name:

Files are added to what the field already holds. This request creates a policy with a title and one document:

POST /vobesoft/api/external/v1/collections/3300/items HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: multipart/form-data; boundary=vobesoft-boundary

--vobesoft-boundary
Content-Disposition: form-data; name="values"
Content-Type: application/json

[ { "fieldId": 5302, "value": "Fleet policy Van Dijk" } ]
--vobesoft-boundary
Content-Disposition: form-data; name="5310"; filename="policy-schedule.pdf"
Content-Type: application/pdf

(the bytes of the file)
--vobesoft-boundary--

curl "https://www.vobesoft.nl/vobesoft/api/external/v1/collections/3300/items" \
  -H "X-Api-Key: $VOBESOFT_API_KEY" \
  -F 'values=[{"fieldId":5302,"value":"Fleet policy Van Dijk"}];type=application/json' \
  -F "5310=@policy-schedule.pdf;type=application/pdf"

The response is the same as for a JSON create: 201 with the new id. The same parts work for an update (10.2, 11.4) and for adding a row (11.2).

Limits on files

• The whole request is at most 50 MB, its parts and files together, in at most 25 parts. A part that holds JSON (values, createdFrom, link) is at most 1 MB, as a JSON body is (6.2); a file part is not.
• Each file field keeps the limits set for it in VobeSoft, such as the largest file and the file types allowed. A file over them returns 400, naming the field and the file's position among the files of that field: field 5310: upload 2 is larger than the field allows (10 MB).
• A file part needs a file name. A part whose name is not values, createdFrom, link or the id of a field returns 400.
• Of a file name, VobeSoft keeps only what follows its last / or \. That name has at most 255 characters, is not only dots, and holds no control or format characters, nor any character Windows refuses in a file name (" * : < > ? |). Otherwise the call returns 400, naming the file, for example field 5310: upload 1 has a name that cannot be stored.
• The body needs a boundary in its Content-Type, and part headers that can be read; otherwise the call returns 400.

12.2 Links and removing files

In values, the value of a file field adds links and removes files:

• links and remove each take at most 1000 entries.
• A link's name has at most 255 characters and holds no control or format characters; otherwise the call returns 400, for example field 5310: link 1 has a name that cannot be stored.
• A link's address is stored, and read back, in its ASCII form: an international domain name in its punycode form, other characters escaped. In that form it has at most 2048 characters.

One update can add a file, add a link and remove a file at once:

PATCH /vobesoft/api/external/v1/collections/3300/items/8003 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: multipart/form-data; boundary=vobesoft-boundary

--vobesoft-boundary
Content-Disposition: form-data; name="values"
Content-Type: application/json

[ { "fieldId": 5310, "value": {
    "links": [ { "name": "Policy in the portal", "url": "https://portal.example.com/policies/4711" } ],
    "remove": [ 60011 ] } } ]
--vobesoft-boundary
Content-Disposition: form-data; name="5310"; filename="signed-offer.pdf"
Content-Type: application/pdf

(the bytes of the file)
--vobesoft-boundary--

The response is 204. Without files to upload, send the same values as a JSON body.

12.3 Files in an item

A file field reads as a list of its files and links:

{ "fieldId": 5310, "type": "file", "value": [
  { "id": 60012, "fileName": "Policy in the portal", "contentType": null, "sizeInBytes": null, "url": "https://portal.example.com/policies/4711" },
  { "id": 60013, "fileName": "signed-offer.pdf", "contentType": "application/pdf", "sizeInBytes": 1024, "url": null }
] }

GET /vobesoft/api/external/v1/files/60013 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}

{
  "url": "https://….blob.core.windows.net/…?sv=…&se=2026-10-01T12%3A21%3A14Z&sr=b&sp=r&rscd=…&rsct=application%2Fpdf&sig=…",
  "expiresAt": "2026-10-01T12:21:14.3580792Z"
}

13Value reference

Every value reads as { "fieldId", "type", "value" } and is written as { "fieldId", "value" }. The type decides the shape of value.

• An empty value reads as null, and null clears a value in a write.
• Writing a read only type returns 400: field 5300: fields of this type cannot be written.
• A field your organization marks as read only in VobeSoft, or a field of a read only category (isReadOnly in the structure, 8.2), cannot be written either, whatever the key's permissions: 400 VALIDATION_FAILED with field {id}: read only. Only the link of createdFrom (10.1) and of a row added to a linking list (11.3) is set through such a field.
• A text longer than 500 characters is refused with field 5302: longer than 500 characters, and a text longer than its field allows with that length, for example field 5302: longer than 40 characters. A number must be finite: NaN and Infinity are refused with field 5307: expected a number, and a number above its field's maximum with field 5307: above its maximum of 100.
• A choice is written by its id; the choices of the field in the structure (8.2) list the ids it takes. This is the same for a field with a choice list and a field with choices of its own. A text is refused with field 5301: expected a list of choice ids, and a choice the field does not have is refused with field 5301: 210099 is not a choice of this field.
• A user shows its name only when the user belongs to your organization; otherwise name is null.
• An employee value names users of your organization only: another id is refused with field 5306: user 2 is not a user of the organization, by its position in the list. A user named twice is stored once. The list takes at most 1000 entries and 100 different users.
• An item linked by an object field must be an item of the collection the field links to, a collection the key may read: otherwise field {id}: links a collection the key cannot read, or field {id}: the linked item is not an active item of the collection the field links to.
• A required field (isRequired, 8.2) cannot be cleared: null, an empty text, an empty list or a date range without either end is refused with field {id}: required. A cleared text with a default value gets that value instead. A new item or row needs a value in every required field the key may write (10.1, 11.2). Checkbox and file fields are never asked, nor the types the API does not write.

13.1 Signatures

A signature reads as its image, an SVG in base64, with when and by whom it was signed:

{ "fieldId": 5309, "type": "signature", "value": {
  "contentType": "image/svg+xml",
  "base64": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIC4uLg==",
  "signedAt": "2026-10-01T14:02:11Z",
  "signedBy": { "id": "3f2b9c1e-7a4d-4e0b-9b6a-1c2d3e4f5a6b", "name": "Mila Jansen" }
} }

14Good practice

• Log every call with its status, its code and its correlation id.
• Wait when asked. On 429 and 503, wait the seconds of Retry-After. On 500, wait and try again a few times, each time waiting longer.
• Keep ids, not names, and read the structure again when your organization changes it: a field that no longer exists is refused with not a field of this collection.
• Send only what changes. An update changes only the fields it names, so leave out the others.
• Mind time zones. Store and compare moments in UTC (6.3).
• Never send your key to a download link. The link needs none (12.4).
• Ask for what changed with a search, instead of reading every item again (15.7).

15Searching items and rows

A search finds the items of a collection, or the rows of a list, by their values and moments, one page at a time.

A search is a POST with a JSON body that holds the conditions and the order (15.3 to 15.5). It returns items as 9.1 shows them and rows as 9.2 shows them, with only what the key may read. The searches are endpoints of their own, Search items and Search rows, with limits of their own (chapter 5).

POST /vobesoft/api/external/v1/collections/3300/items/search?pageIndex=0&pageSize=25 HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{
  "criteria": {
    "operator": "and",
    "conditions": [
      { "fieldId": 5302, "operator": "contains", "value": "Van Dijk" },
      { "fieldId": 5301, "operator": "equals", "value": [210004] }
    ]
  },
  "sort": [ { "property": "lastEditedAt", "direction": "descending" } ]
}

{
  "totalCount": 1,
  "results": [
    {
      "id": 8001,
      "collectionId": 3300,
      "createdAt": "2026-10-01T12:15:17.655Z",
      "lastEditedAt": "2026-10-20T08:42:11.3172946Z",
      "lastEditedBy": { "id": "3f2b9c1e-7a4d-4e0b-9b6a-1c2d3e4f5a6b", "name": "Mila Jansen" },
      "categories": [
        {
          "id": 4300,
          "name": "General",
          "isList": false,
          "values": [
            { "fieldId": 5301, "type": "choice", "value": [ { "id": 210004, "text": "Liability" } ] },
            { "fieldId": 5302, "type": "text", "value": "Fleet policy Van Dijk" }
          ]
        },
        {
          "id": 4301,
          "name": "Claims",
          "isList": true,
          "rowCount": 1
        }
      ]
    }
  ],
  "pageIndex": 0,
  "pageSize": 25
}

POST /vobesoft/api/external/v1/collections/3300/categories/4301/rows/search HTTP/1.1
Host: www.vobesoft.nl
X-Api-Key: {your key}
Content-Type: application/json

{
  "criteria": {
    "operator": "and",
    "conditions": [
      { "fieldId": 5321, "operator": "greaterThan", "value": 100 },
      { "fieldId": 5302, "operator": "contains", "value": "Van Dijk" }
    ]
  },
  "sort": [ { "fieldId": 5321, "direction": "descending" } ]
}

{
  "totalCount": 1,
  "results": [
    {
      "id": 9001,
      "itemId": 8001,
      "lastEditedAt": "2026-10-14T13:05:40.0281533Z",
      "lastEditedBy": { "id": "7dc27c45-fc87-4d43-9799-32b2aa34d004", "name": "External API" },
      "values": [
        { "fieldId": 5320, "type": "text", "value": "Windscreen damage" },
        { "fieldId": 5321, "type": "number", "value": 350.0 },
        { "fieldId": 5322, "type": "file", "value": null }
      ]
    }
  ],
  "pageIndex": 0,
  "pageSize": 25
}

15.3 The body

criteria is a group: an operator, and or or, and its conditions. A member of conditions is a condition or a group of its own. A condition names a field by fieldId, or a moment of the item or row by property (15.4), with an operator and, except for isEmpty and isNotEmpty, a value.

{
  "criteria": {
    "operator": "and",
    "conditions": [
      { "fieldId": 5302, "operator": "contains", "value": "Van Dijk" },
      { "fieldId": 5304, "operator": "greaterThan", "value": { "daysFromToday": -30 } },
      {
        "operator": "or",
        "conditions": [
          { "fieldId": 5301, "operator": "equals", "value": [210004, 210001] },
          { "fieldId": 5306, "operator": "isEmpty" }
        ]
      },
      { "path": [5311], "fieldId": 5205, "operator": "equals", "value": "Utrecht" },
      { "property": "lastEditedAt", "operator": "greaterThan", "value": "2026-10-01T00:00:00Z" }
    ]
  },
  "sort": [
    { "property": "lastEditedAt", "direction": "descending" },
    { "fieldId": 5302, "direction": "ascending" }
  ]
}

This finds the policies whose title holds Van Dijk, whose start date lies after the day 30 days ago, whose product is one of two or that have no account manager, whose customer (5311) has Utrecht as its text field 5205, and that were edited after 1 October; the most recently edited first.

• Both criteria and sort may be left out. Send JSON (application/json), at most 64 KB.
• The body is read strictly, as every body is (6.2), so a misspelled name never widens a search. The values of operator, property and direction are written as this chapter writes them.
• A group holds at least one condition. Groups nest at most two levels below criteria.
• A search holds at most 50 conditions. A condition's list of values holds at most 100 entries, all lists together at most 1000.

15.4 Conditions

The operators are equals, notEquals, greaterThan, lessThan, between, contains, notContains, isEmpty and isNotEmpty. Which of them a field takes, and what its value looks like, depends on its type in the structure (8.2):

A choice is named by its id, as a read returns it. A choice of a field's own choices whose text is empty or holds a comma cannot be searched.

Fields of a list. In an item search, a condition on a field of a list category finds the items of which some row matches; an item without rows matches none. In a row search the field of the list tests the row itself (15.2).

Paths. In an item search, path follows one or two object fields to the item whose field the condition tests: "path": [5311] tests the policy's customer. Each step is an object field of a normal category, and the field at the end is a field of a normal category of the collection the last step links. Under and, conditions whose paths start with the same field test the same linked item.

Moments. A condition with property tests a moment of the item or, in a row search, of the row itself; a row's createdAt is when it was added, which a read of the row does not show. A moment is read to the millisecond:

Every field a search names, in a condition, a path or the order, must be one the key may read. A field it may not read returns the same 404 as a field that does not exist.

15.5 Order

sort lists at most three keys, each a field, { "fieldId": 5302 }, or a property, { "property": "id" }, "createdAt" or "lastEditedAt", with a direction, ascending or descending.

• VobeSoft adds id as a last key in the direction of your last key, so the pages of a search never overlap or skip a result. Without sort the newest come first, by id descending, as in 9.2.
• An item or row without a lastEditedAt comes first when sorting by it ascending, and last when descending.
• An item search sorts by fields of the collection's normal categories, a row search by fields of the searched list. The rows of a one to many list (11.1) sort by the properties only. Mirror and formula fields do not sort.

15.6 Errors

A search that cannot be answered returns the first mistake in details: where it is in the body, or which field it concerns, and what is wrong. It never repeats a value you sent.

The texts of details are written for a person reading your log; let your system act on the code (chapter 7).

15.7 Find what changed

To keep your system in step with VobeSoft, ask for what changed since your last search instead of reading every item again:

1. Read everything once: search with "sort": [ { "property": "id", "direction": "ascending" } ] and read every page, each a call within your limits (chapter 5). Keep the highest lastEditedAt you saw; that is your cursor.
2. At every poll, search for lastEditedAt after your cursor minus five minutes, sorted by lastEditedAt ascending, and read every page.
3. Skip a result you already handled with the same id and lastEditedAt.
4. Keep the highest lastEditedAt as your new cursor.

{
  "criteria": {
    "operator": "and",
    "conditions": [
      { "property": "lastEditedAt", "operator": "greaterThan", "value": "2026-10-20T08:37:11.3172946Z" }
    ]
  },
  "sort": [ { "property": "lastEditedAt", "direction": "ascending" } ]
}

• An edit gets its moment when VobeSoft saves it, and a long save, such as an import, shows only when it is done. The five minutes catch an edit whose moment lies just before your last poll but that it could not see yet; step 3 drops what you already have.
• Pages are read live, so items can move between pages while you read them, and a full read is not a snapshot of one moment.
• The same works for rows with a row search (15.2), on the row's own lastEditedAt.
• Which changes move lastEditedAt, and which do not, is in 9.4. A deleted item or row is not reported: compare the ids of a full read now and then to find what is gone.

AEndpoint reference

Every path starts with https://www.vobesoft.nl/vobesoft/api/external/v1. The endpoint column names the endpoint as the key form in Settings, API shows it.

A path that starts with … continues the path above it: rows hang under their item, /collections/{collectionId}/items/{itemId}/categories/{listCategoryId}/rows.

BChanges to this guide