API reference

Vendors and bills

Endpoints and input schemas from the console's API registry.

GET /api/vendors

List vendors

Needs the vendors.read permission on the API key's role.

No request-body schema is supplied for this operation in the registry.

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off

POST /api/vendors

Create a vendor

Needs the vendors.write permission on the API key's role.

JSON request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "code": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 30
        },
        {
          "type": "null"
        }
      ]
    },
    "regNo": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ]
    },
    "taxId": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ]
    },
    "address": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ]
    },
    "email": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "string",
              "format": "email",
              "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
            },
            {
              "type": "null"
            }
          ]
        },
        {
          "type": "string",
          "const": ""
        }
      ]
    },
    "phone": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50
        },
        {
          "type": "null"
        }
      ]
    },
    "website": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "category": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentTermsDays": {
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "currency": {
      "type": "string",
      "maxLength": 10
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "ON_HOLD",
        "BLOCKED"
      ]
    },
    "relatedParty": {
      "type": "boolean"
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 5000
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "name"
  ]
}

Documented responses

  • 200 — OK
  • 201 — Created
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off

GET /api/vendors/{id}

Read a vendor

Needs the vendors.read permission on the API key's role.

Path parameters

  • id — required path parameter

No request-body schema is supplied for this operation in the registry.

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off
  • 404 — Not found in this company

PATCH /api/vendors/{id}

Change a vendor

Needs the vendors.write permission on the API key's role.

Path parameters

  • id — required path parameter
JSON request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "code": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 30
        },
        {
          "type": "null"
        }
      ]
    },
    "regNo": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ]
    },
    "taxId": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 60
        },
        {
          "type": "null"
        }
      ]
    },
    "address": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ]
    },
    "email": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "string",
              "format": "email",
              "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
            },
            {
              "type": "null"
            }
          ]
        },
        {
          "type": "string",
          "const": ""
        }
      ]
    },
    "phone": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50
        },
        {
          "type": "null"
        }
      ]
    },
    "website": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "category": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentTermsDays": {
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "currency": {
      "type": "string",
      "maxLength": 10
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "ON_HOLD",
        "BLOCKED"
      ]
    },
    "relatedParty": {
      "type": "boolean"
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 5000
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off
  • 404 — Not found in this company

DELETE /api/vendors/{id}

Delete a vendor

Needs the vendors.write permission on the API key's role.

Path parameters

  • id — required path parameter

No request-body schema is supplied for this operation in the registry.

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off
  • 404 — Not found in this company

GET /api/vendor-bills

List vendor bills

Needs the bills.read permission on the API key's role.

No request-body schema is supplied for this operation in the registry.

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off

POST /api/vendor-bills

Create a vendor bill

Needs the bills.write permission on the API key's role.

JSON request schema
{
  "type": "object",
  "properties": {
    "expenseScope": {
      "type": "string",
      "enum": [
        "COMPANY",
        "PROJECT",
        "UNCLASSIFIED",
        "PAYROLL"
      ]
    },
    "expenseCategory": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "Rent",
            "Utilities",
            "Internet & telephone",
            "Subscriptions",
            "Insurance",
            "Cleaning",
            "Maintenance",
            "Professional fees",
            "Office supplies",
            "Other"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "outletId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "serviceFrom": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "serviceTo": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "obligationId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "obligationMonth": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(19|[2-9]\\d)\\d{2}-(0[1-9]|1[0-2])$"
        },
        {
          "type": "null"
        }
      ]
    },
    "vendorId": {
      "type": "string",
      "minLength": 1
    },
    "purchaseOrderId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "projectId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "vendorInvoiceNo": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "billDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "dueDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "items": {
      "minItems": 1,
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "description": {
            "type": "string",
            "maxLength": 10000
          },
          "quantity": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000
          },
          "unitPrice": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000
          },
          "amount": {
            "type": "number",
            "minimum": 0
          },
          "itemType": {
            "type": "string",
            "enum": [
              "standard",
              "payment",
              "section"
            ]
          },
          "percentage": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "taxInclusive": {
            "type": "boolean"
          },
          "taxCode": {
            "type": "string",
            "maxLength": 50
          },
          "taxCodeId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "classificationCode": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^\\d{3}$"
              },
              {
                "type": "string",
                "const": ""
              }
            ]
          },
          "unitCode": {
            "type": "string",
            "maxLength": 3
          },
          "taxRate": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "appliedTaxRate": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "taxAmount": {
            "type": "number",
            "minimum": 0
          },
          "discountAmount": {
            "type": "number",
            "minimum": 0
          },
          "notes": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "description",
          "quantity",
          "unitPrice",
          "amount"
        ]
      }
    },
    "taxAmount": {
      "type": "number",
      "minimum": 0
    },
    "currency": {
      "type": "string",
      "maxLength": 10
    },
    "fxRate": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000000
        },
        {
          "type": "null"
        }
      ]
    },
    "overPoReason": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 5000
        },
        {
          "type": "null"
        }
      ]
    },
    "files": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fileUrl": {
            "type": "string",
            "format": "starts_with",
            "pattern": "^\\/api\\/files\\/vendor-files\\/.*"
          },
          "fileName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "fileSize": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "fileUrl",
          "fileName",
          "fileSize"
        ]
      }
    }
  },
  "required": [
    "vendorId",
    "vendorInvoiceNo",
    "billDate",
    "items"
  ]
}

Documented responses

  • 200 — OK
  • 201 — Created
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off

GET /api/vendor-bills/{id}

Read a vendor bill

Needs the bills.read permission on the API key's role.

Path parameters

  • id — required path parameter

No request-body schema is supplied for this operation in the registry.

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off
  • 404 — Not found in this company

Other policy and state errors may also apply. See API key permissions and limits and the complete OpenAPI document.