File categories

Labels attachments are filed under ("Receipts", "Signed contracts"). Per company. The target of filecategoryid on an attachment. name is unique per company, case-insensitive and trimmed: the File Categories screen does not enforce that, so a duplicate created there is something the API will refuse to add a third of, and creating a name that matches a cancelled category revives it (200, the original id, record_reactivated in _meta.warnings) rather than adding a second row.

The object#

Field	Type	Description
idread-only	integer	NolaPro id. What `filecategoryid` on an attachment stores.
name	string(255)	The category name as it appears in the file list. Trimmed on input. Unique per company, case-insensitive, so `receipts` and `Receipts` are the same category.
cancelread-only	boolean	True once cancelled. Attachments filed under a cancelled category keep pointing at it.
externalid	string(100)	Your own key for this category. Scoped to your company.
lastchangedateread-only	string	Last modification, as recorded by the code that made it. This column is not maintained by the database, so it is informational only and does NOT drive `modifiedsince` - this resource has no delta cursor.

Endpoints#

GET/filecategories 200403

List file categories.

Requires scope setup:read.

Parameters

Name	In	Type	Notes
name	query	string	Partial match, case insensitive.
cancel	query	string	Defaults to `false`. Pass `true` for cancelled only, or `any`.
externalid	query	string	Exact match on your own key. Scoped to your company.
include	query	string	Comma-separated extras to embed. Only `custom_fields` is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions.

When it fails

Status	Code	Meaning
403	insufficient_scope	Token lacks `setup:read`.

curl \
  'https://acme.nolapro.com/!/api/v2/filecategories' \
  -H 'Authorization: Bearer $NP_TOKEN'

$ch = curl_init('https://acme.nolapro.com/!/api/v2/filecategories');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NP_TOKEN')],
  CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);

import os, requests

r = requests.get(
    "https://acme.nolapro.com/!/api/v2/filecategories",
    headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"},
)
r.raise_for_status()

const res = await fetch(
  'https://acme.nolapro.com/!/api/v2/filecategories',
  {
    method: 'GET',
    headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` },
  }
);
const data = await res.json();

using System.Net.Http.Json;

var token = Environment.GetEnvironmentVariable("NP_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

var res = await http.GetAsync(
    "https://acme.nolapro.com/!/api/v2/filecategories");
res.EnsureSuccessStatusCode();

POST/filecategories 201400409403

Create a file category.

Creates a category for this company. If an active category already has that name (case-insensitive, trimmed) the request is refused with 409 duplicate and the body names its id. If a cancelled one does, it is reactivated instead: the response is 200, not 201, carries the original id, and _meta.warnings contains record_reactivated.

Requires scope setup:write.

Parameters

Name	In	Type	Notes
Idempotency-Key	header	string	Makes the write safely retryable. Any unique string per logical operation; a UUID is fine. The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing. The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers `409 idempotency_replay` rather than silently handing back the old response. Keys are remembered for 24 hours.

Body

Field	Type	Description
idread-only	integer	NolaPro id. What `filecategoryid` on an attachment stores.
name	string(255)	The category name as it appears in the file list. Trimmed on input. Unique per company, case-insensitive, so `receipts` and `Receipts` are the same category.
cancelread-only	boolean	True once cancelled. Attachments filed under a cancelled category keep pointing at it.
externalid	string(100)	Your own key for this category. Scoped to your company.
lastchangedateread-only	string	Last modification, as recorded by the code that made it. This column is not maintained by the database, so it is informational only and does NOT drive `modifiedsince` - this resource has no delta cursor.

When it fails

Status	Code	Meaning
400	invalid_request	`name` was missing, empty, whitespace only, or over 255 characters.
409	duplicate	An active category already has that name. The body names its id.
403	insufficient_scope	Token lacks `setup:write`.

curl -X POST \
  'https://acme.nolapro.com/!/api/v2/filecategories' \
  -H 'Authorization: Bearer $NP_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-key' \
  -d '{
    "id": 3,
    "name": "Receipts",
    "cancel": false,
    "externalid": "RCPT",
    "lastchangedate": "2026-09-21T14:02:11Z"
}'

$ch = curl_init('https://acme.nolapro.com/!/api/v2/filecategories');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NP_TOKEN')],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS     => json_encode([
    'id' => 3,
    'name' => 'Receipts',
    'cancel' => false,
    'externalid' => 'RCPT',
    'lastchangedate' => '2026-09-21T14:02:11Z',
  ]),
]);
$res = json_decode(curl_exec($ch), true);

import os, requests

r = requests.post(
    "https://acme.nolapro.com/!/api/v2/filecategories",
    headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"},
    json={
        "id": 3,
        "name": "Receipts",
        "cancel": False,
        "externalid": "RCPT",
        "lastchangedate": "2026-09-21T14:02:11Z",
    },
)
r.raise_for_status()

const res = await fetch(
  'https://acme.nolapro.com/!/api/v2/filecategories',
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` },
    body: JSON.stringify({
      id: 3,
      name: "Receipts",
      cancel: false,
      externalid: "RCPT",
      lastchangedate: "2026-09-21T14:02:11Z",
    }),
  }
);
const data = await res.json();

using System.Net.Http.Json;

var token = Environment.GetEnvironmentVariable("NP_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

var body = new {
    id = 3,
    name = "Receipts",
    cancel = false,
    externalid = "RCPT",
    lastchangedate = "2026-09-21T14:02:11Z",
};

var req = new HttpRequestMessage(HttpMethod.Post,
    "https://acme.nolapro.com/!/api/v2/filecategories") {
    Content = JsonContent.Create(body),
};
req.Headers.Add("Idempotency-Key", "your-unique-key");

var res = await http.SendAsync(req);
res.EnsureSuccessStatusCode();

Response 201

{
    "id": 3,
    "name": "Receipts",
    "cancel": false,
    "externalid": "RCPT",
    "lastchangedate": "2026-09-21T14:02:11Z"
}

GET/filecategories/{id} 200404

Retrieve one category.

Requires scope setup:read.

Parameters

Name	In	Type	Notes
idrequired	path	integer	The category id.
include	query	string	Comma-separated extras to embed. Only `custom_fields` is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions.

When it fails

Status	Code	Meaning
404	not_found	No category with that id.

curl \
  'https://acme.nolapro.com/!/api/v2/filecategories/104' \
  -H 'Authorization: Bearer $NP_TOKEN'

$ch = curl_init('https://acme.nolapro.com/!/api/v2/filecategories/104');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NP_TOKEN')],
  CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);

import os, requests

r = requests.get(
    "https://acme.nolapro.com/!/api/v2/filecategories/104",
    headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"},
)
r.raise_for_status()

const res = await fetch(
  'https://acme.nolapro.com/!/api/v2/filecategories/104',
  {
    method: 'GET',
    headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` },
  }
);
const data = await res.json();

using System.Net.Http.Json;

var token = Environment.GetEnvironmentVariable("NP_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

var res = await http.GetAsync(
    "https://acme.nolapro.com/!/api/v2/filecategories/104");
res.EnsureSuccessStatusCode();

Response 200

{
    "id": 3,
    "name": "Receipts",
    "cancel": false,
    "externalid": "RCPT",
    "lastchangedate": "2026-09-21T14:02:11Z"
}

PATCH/filecategories/{id} 200400404409

Update a category.

Requires scope setup:write.

Parameters

Name	In	Type	Notes
idrequired	path	integer	The category id.
Idempotency-Key	header	string	Makes the write safely retryable. Any unique string per logical operation; a UUID is fine. The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing. The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers `409 idempotency_replay` rather than silently handing back the old response. Keys are remembered for 24 hours.

Body

Field	Type	Description
idread-only	integer	NolaPro id. What `filecategoryid` on an attachment stores.
name	string(255)	The category name as it appears in the file list. Trimmed on input. Unique per company, case-insensitive, so `receipts` and `Receipts` are the same category.
cancelread-only	boolean	True once cancelled. Attachments filed under a cancelled category keep pointing at it.
externalid	string(100)	Your own key for this category. Scoped to your company.
lastchangedateread-only	string	Last modification, as recorded by the code that made it. This column is not maintained by the database, so it is informational only and does NOT drive `modifiedsince` - this resource has no delta cursor.

When it fails

Status	Code	Meaning
400	invalid_request	`name` was empty or too long.
404	not_found	No category with that id.
409	duplicate	Another active category already has that name.

curl -X PATCH \
  'https://acme.nolapro.com/!/api/v2/filecategories/104' \
  -H 'Authorization: Bearer $NP_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-key' \
  -d '{
    "id": 3,
    "name": "Receipts",
    "cancel": false,
    "externalid": "RCPT",
    "lastchangedate": "2026-09-21T14:02:11Z"
}'

$ch = curl_init('https://acme.nolapro.com/!/api/v2/filecategories/104');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NP_TOKEN')],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'PATCH',
  CURLOPT_POSTFIELDS     => json_encode([
    'id' => 3,
    'name' => 'Receipts',
    'cancel' => false,
    'externalid' => 'RCPT',
    'lastchangedate' => '2026-09-21T14:02:11Z',
  ]),
]);
$res = json_decode(curl_exec($ch), true);

import os, requests

r = requests.patch(
    "https://acme.nolapro.com/!/api/v2/filecategories/104",
    headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"},
    json={
        "id": 3,
        "name": "Receipts",
        "cancel": False,
        "externalid": "RCPT",
        "lastchangedate": "2026-09-21T14:02:11Z",
    },
)
r.raise_for_status()

const res = await fetch(
  'https://acme.nolapro.com/!/api/v2/filecategories/104',
  {
    method: 'PATCH',
    headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` },
    body: JSON.stringify({
      id: 3,
      name: "Receipts",
      cancel: false,
      externalid: "RCPT",
      lastchangedate: "2026-09-21T14:02:11Z",
    }),
  }
);
const data = await res.json();

using System.Net.Http.Json;

var token = Environment.GetEnvironmentVariable("NP_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

var body = new {
    id = 3,
    name = "Receipts",
    cancel = false,
    externalid = "RCPT",
    lastchangedate = "2026-09-21T14:02:11Z",
};

var req = new HttpRequestMessage(HttpMethod.Patch,
    "https://acme.nolapro.com/!/api/v2/filecategories/104") {
    Content = JsonContent.Create(body),
};
req.Headers.Add("Idempotency-Key", "your-unique-key");

var res = await http.SendAsync(req);
res.EnsureSuccessStatusCode();

Response 200

{
    "id": 3,
    "name": "Receipts",
    "cancel": false,
    "externalid": "RCPT",
    "lastchangedate": "2026-09-21T14:02:11Z"
}

DELETE/filecategories/{id} 200403404

Cancel a category.

Sets the cancel flag. Nothing is removed, and attachments already filed under it keep their filecategoryid. Needs setup:cancel, which setup:write does not imply. Cancelling an already cancelled category succeeds.

Requires scope setup:cancel.

Parameters

Name	In	Type	Notes
idrequired	path	integer	The category id.
Idempotency-Key	header	string	Makes the write safely retryable. Any unique string per logical operation; a UUID is fine. The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing. The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers `409 idempotency_replay` rather than silently handing back the old response. Keys are remembered for 24 hours.

When it fails

Status	Code	Meaning
403	insufficient_scope	Token has `setup:write` but not `setup:cancel`.
404	not_found	No category with that id.

curl -X DELETE \
  'https://acme.nolapro.com/!/api/v2/filecategories/104' \
  -H 'Authorization: Bearer $NP_TOKEN'

$ch = curl_init('https://acme.nolapro.com/!/api/v2/filecategories/104');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NP_TOKEN')],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'DELETE',
]);
$res = json_decode(curl_exec($ch), true);

import os, requests

r = requests.delete(
    "https://acme.nolapro.com/!/api/v2/filecategories/104",
    headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"},
)
r.raise_for_status()

const res = await fetch(
  'https://acme.nolapro.com/!/api/v2/filecategories/104',
  {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` },
  }
);
const data = await res.json();

using System.Net.Http.Json;

var token = Environment.GetEnvironmentVariable("NP_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

var req = new HttpRequestMessage(HttpMethod.Delete,
    "https://acme.nolapro.com/!/api/v2/filecategories/104");

var res = await http.SendAsync(req);
res.EnsureSuccessStatusCode();

Response 200

{
    "id": 3,
    "name": "Receipts",
    "cancel": false,
    "externalid": "RCPT",
    "lastchangedate": "2026-09-21T14:02:11Z"
}

POST/filecategories/batch 207400

Create many.

Always answers 207, one result per item. Each item is validated exactly as a single POST is, including the duplicate and reactivation rules.

Requires scope setup:write.

Parameters

Name	In	Type	Notes
Idempotency-Key	header	string	Makes the write safely retryable. Any unique string per logical operation; a UUID is fine. The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing. The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers `409 idempotency_replay` rather than silently handing back the old response. Keys are remembered for 24 hours.

Body array

Field	Type	Description
idread-only	integer	NolaPro id. What `filecategoryid` on an attachment stores.
name	string(255)	The category name as it appears in the file list. Trimmed on input. Unique per company, case-insensitive, so `receipts` and `Receipts` are the same category.
cancelread-only	boolean	True once cancelled. Attachments filed under a cancelled category keep pointing at it.
externalid	string(100)	Your own key for this category. Scoped to your company.
lastchangedateread-only	string	Last modification, as recorded by the code that made it. This column is not maintained by the database, so it is informational only and does NOT drive `modifiedsince` - this resource has no delta cursor.

When it fails

Status	Code	Meaning
400	invalid_request	The envelope was wrong - not an array, or over the size cap.

curl -X POST \
  'https://acme.nolapro.com/!/api/v2/filecategories/batch' \
  -H 'Authorization: Bearer $NP_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-key' \
  -d '[
    {
        "id": 3,
        "name": "Receipts",
        "cancel": false,
        "externalid": "RCPT",
        "lastchangedate": "2026-09-21T14:02:11Z"
    }
]'

$ch = curl_init('https://acme.nolapro.com/!/api/v2/filecategories/batch');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('NP_TOKEN')],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'POST',
  CURLOPT_POSTFIELDS     => json_encode([
    [
      'id' => 3,
      'name' => 'Receipts',
      'cancel' => false,
      'externalid' => 'RCPT',
      'lastchangedate' => '2026-09-21T14:02:11Z',
    ],
  ]),
]);
$res = json_decode(curl_exec($ch), true);

import os, requests

r = requests.post(
    "https://acme.nolapro.com/!/api/v2/filecategories/batch",
    headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"},
    json=[
        {
            "id": 3,
            "name": "Receipts",
            "cancel": False,
            "externalid": "RCPT",
            "lastchangedate": "2026-09-21T14:02:11Z",
        },
    ],
)
r.raise_for_status()

const res = await fetch(
  'https://acme.nolapro.com/!/api/v2/filecategories/batch',
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` },
    body: JSON.stringify([
      {
        id: 3,
        name: "Receipts",
        cancel: false,
        externalid: "RCPT",
        lastchangedate: "2026-09-21T14:02:11Z",
      },
    ]),
  }
);
const data = await res.json();

using System.Net.Http.Json;

var token = Environment.GetEnvironmentVariable("NP_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

var body = new[] {
    new {
        id = 3,
        name = "Receipts",
        cancel = false,
        externalid = "RCPT",
        lastchangedate = "2026-09-21T14:02:11Z",
    },
};

var req = new HttpRequestMessage(HttpMethod.Post,
    "https://acme.nolapro.com/!/api/v2/filecategories/batch") {
    Content = JsonContent.Create(body),
};
req.Headers.Add("Idempotency-Key", "your-unique-key");

var res = await http.SendAsync(req);
res.EnsureSuccessStatusCode();

Webhook subscriptions →

Subscriptions that push events to your server instead of you polling for them. A subscription belongs to the token that created it and only ever delivers events that token has the scope to read. The envelope, signature verification and the retry schedule are in - read that first; this page is the subscription object and the event catalogue.

Request log →

What this token has been doing. Useful when a call failed hours ago and nobody kept the response.