Quickstart guide

Prerequisites

Complete the Getting started guide to obtain a Bearer token
Set the base URL for all requests:

Environment	Base URL
Stage	`https://stage-api.findity.com/api/v1/admin`
Production	`https://api.findity.com/api/v1/admin`

⚠️
Use externalId endpoints. The API reference includes both externalId and internalId variants for many endpoints. The internalId endpoints are legacy and will be phased out. Always use the externalId endpoints for new integrations.

Provisioning flow overview

The Admin API follows a sequential provisioning flow. Complete each step in order, as later steps depend on resources created earlier.

Step	Action	Dependency
1	Create a customer organisation	None
2	Configure dimension fields	Organisation
3	Add dimension values	Dimension fields
4	Set up chart of accounts	Organisation
5	Add users	Organisation
6	Create approval structure	Organisation, Users, Dimensions

Step 1: Create a customer organisation

An organisation (the top-level entity representing your customer) is the foundation for all other resources. Create one before configuring dimensions, accounts, or users.

Example request

curl --request POST \
   --url https://stage-expense.findity.com/api/admin/organizations/externalid/{externalId}/ \
   --header 'Content-Type: application/json' \
   --header 'X-Findity-ApiVersion: 3' \
   --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
   --data '
    {
      "settings": {
        "templateOrganizationId": "your-template-org-id-here"
      },
      "className": "com.findity.consumer.Company",
      "externalSourceId": "your-external-source-id-here"
    }
    '

Example response

{
"id": "your-template-org-id-here",
"externalSourceId": "your-external-source-id-here",
"className": "com.findity.consumer.Company",
"lastUpdated": "2026-02-27T14:50:44Z",
"dateCreated": "2026-01-13T13:28:54Z",
"status": "NORMAL",
"name": "your-company-name",
"vat": "123456-1234",
"phone": "",
"logoId": null,
"iconId": null,
"address": {
  "street1": null,
  "street2": null,
  "street3": null,
  "city": null,
  "postalCode": null,
  "country": "Sweden",
  "countryId": "2b9fbaa2630511e18824b0dd45bff075",
  "countryCode": "SE"
},
"clientApplicationId": "16200214",
"label": null,
"isl2017Date": "2016-12-31T22:59:59Z",
"content": [],
"invoiceAddress": {
  "id": "8a5c8d119bb78195019bb78b8b660043",
  "street1": null,
  "postalCode": null,
  "city": null,
  "country": {
    "id": "2b9fbaa2630511e18824b0dd45bff075",
    "iso2": "SE",
    "iso3": "SWE",
    "name": "Sweden",
    "lastUpdated": "2018-11-20T15:57:43Z",
    "distanceUnit": "KM"
  },
  "countryCode": "SE"
},
"invoiceEmailAddress": null,
"invoiceRefOur": null,
"invoiceRefTheir": null,
"unmanagedCardTransactionEmail": null,
"licenseGroup": 0,
"licensingEnabled": "INHERITED",
"supportAccessEndDate": "2026-02-12T13:28:54Z",
"settings": {
  "useForCardTransactions": false,
  "maxNumberOfCards": 3,
  "language": "sv_SE",
  "formattingRegion": "sv_SE",
  "useNewDimensions": true,
  "userSetup": {
    "createdWithStatus": "PENDING_ACTIVATION"
  },
  "gettingStarted": {
    "completedAt": null,
    "onboardingEvents": {
      "registrationCompleteMail": {
        "active": false,
        "sent": false
      },
      "afterSignUpMail": {
        "active": false,
        "numberOfDays": null,
        "sent": false
      },
      "reminderMail1": {
        "active": false,
        "numberOfDays": null,
        "sent": false
      },
      "reminderMail2": {
        "active": false,
        "numberOfDays": null,
        "sent": false
      },
      "delete": {
        "active": false,
        "numberOfDays": null
      }
    },
    "active": false,
    "userStep": {
      "completedAt": null,
      "done": false
    },
    "expenseManagementStep": {
      "completedAt": null,
      "done": false
    },
    "integrationStep": {
      "completedAt": null,
      "done": false
    },
    "done": false,
    "mobileOnboarding": false,
    "categoriesStep": {
      "completedAt": null,
      "done": false
    }
  },
  "cardTransactionGracePeriodDays": 7,
  "externallyActivated": true,
  "design": {
    "showClientAppBackgroundImage": false,
    "darkAccentColor": "#012a2d",
    "textOnHoverColor": "#FFFFFF",
    "textOnAccentColor": "#FFFFFF",
    "accentColor": "#012a2d",
    "menuLogoUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e80acc2f60180ad1413a10199",
    "menuLogoUrl2": "https://stage-expense.findity.com/api/resources/8a5c8e9d9a77c46c019a783e7bdc0431",
    "hideInvoiceInformationOnOrgCreate": true,
    "logoUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e80acc2f60180acfedac8018a",
    "dontCopyBackgroundImgageFromTemplate": false,
    "adminSwitchOn": "admin_switch_on_ce.png",
    "useGhostButtons": true,
    "logo": "ca_ce.png",
    "favIconUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e80ad749b0180ae4aa93f063f",
    "iconUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e80ad749b0180adff15a90595",
    "backgroundImageUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e80acc2f60180acfedac8018a",
    "customCss": "/* Link color */\n.redesign a {\n    color: #000000 !important;\n}",
    "partnerHasAccentColor": false,
    "partnerHasDarkAccentColor": false,
    "partnerHasSecondaryAccentColor": false,
    "partnerHasSecondaryDarkAccentColor": false,
    "iconReadOnly": false,
    "logoReadOnly": false
  }
},
"sendEventToExternalSystem": true,
"partnerId": "241f74a3554840eb913a172d24dceb53",
"partnerName": "your-partner-name",
"partnerCode": "your-partner-code",
"payedByPartner": true,
"identityProviderId": null,
"identityProviderEnabled": false,
"reportReviewOnPartner": false,
"inheritedLicenseGroup": 2,
"inheritedLicensingEnabled": "INACTIVE",
"classType": "com.findity.consumer.Company",
"isDefault": false,
"services": [
  {
    "id": "8a5c8d119bb78195019bb78b8cbc0045",
    "useNewMileageView": false,
    "classType": "com.findity.consumer.service.ExpenseManagementService",
    "recipients": [
      {
        "id": "8a5c8d119bb78195019bb78b8deb0048",
        "status": "NORMAL",
        "dateCreated": "2026-01-13T13:28:55Z",
        "deletedAt": null,
        "classType": "com.findity.economy.accounting.GenericExpenseReportRecipient",
        "doDebitAccounting": true,
        "doCreditAccounting": true,
        "usesAutomaticAccounting": true,
        "settings": {
          "excel": {
            "includeHeaders": null
          },
          "swishCertificateInformation": {},
          "accountingType": "BOOKKEEPING",
          "isGlobal": true,
          "outputRmtInf": false,
          "ceIntegrationPaymentFile": {},
          "supportedFields": [
            "receiverSftp",
            "enableEmployeeAccountingSummary",
            "sendPdf",
            "openEmailCheckbox",
            "accountingType",
            "usesAccountingNumbers",
            "receiverEmail"
          ],
          "reportDateType": "CURRENT_DATE"
        },
        "email": "[email protected]",
        "errorEmail": null,
        "integrationPluginName": "ce-integration-standard",
        "sendSingleVerification": false,
        "usesSalaryCodes": false,
        "usesExpenseCodes": false,
        "usesAccountingNumbers": true,
        "sortOrder": 1,
        "paymentTypes": [],
        "usesBenefits": false,
        "usesExtendedSubsistenceAllowance": false,
        "usesNewAccountingStructure": true,
        "verificationListsType": "REPORT_PER_ACCOUNT",
        "basisOutputType": "SEND_PDF_AS_ATTACHMENT",
        "customRecipientName": null,
        "recipientName": "PDF fil",
        "originalRecipientName": "PDF fil",
        "requiresApiKey": false,
        "hasApiKey": null,
        "accountingNumbersSynced": false,
        "salaryCodesSynced": false,
        "usesPaymentTypes": true,
        "disableManualAccounting": false
      }
    ],
    "expenseReportNumberSeries": null,
    "receiptNumberSeries": null,
    "requireVerificationNumber": false,
    "expenseBaseCurrency": "SEK",
    "userCanTakeBackReports": false,
    "requiresAttestation": false,
    "defaultDistanceUnit": "KM",
    "defaultAmountPerDistanceUnit": 0,
    "defaultApproverId": null,
    "requiredApprovals": null,
    "usesCostCenters": false,
    "usesProjects": false,
    "requireBasis": true,
    "requireBasisForCorporateCards": true,
    "requireBasisForCorporateCardsPrivatePurchase": true,
    "usesCostCentersCustomField": false,
    "usesProjectsCustomField": false,
    "taxAccountingNumberId": "8a5c8d119bb78195019bb78b8cfa0047",
    "taxSalaryCodeId": null,
    "defaultCostCenterLocation": "NONE",
    "userCanChangeCostCenter": true,
    "usePersonalPaymentTypes": null,
    "usesPaymentBasis": false,
    "useReport": true,
    "useSingleExpense": false,
    "showOngoingReports": false,
    "setProjectAndCostCenterOnTaxAccounting": null,
    "setProjectAndCostCenterOnPaymentAccounting": null,
    "accountingNumbers": [
      {
        "id": "8a5c8d119bb78195019bb78b8cf90046",
        "number": "100",
        "text": "Expenses",
        "visible": false,
        "type": "ACCOUNTING_NUMBER"
      },
      {
        "id": "8a5c89e39c9d9c20019c9e0f4c060023",
        "number": "1819",
        "text": "VAT",
        "visible": false,
        "type": "ACCOUNTING_NUMBER"
      },
      {
        "id": "8a5c89b79c9e1024019c9e127e490001",
        "number": "4000",
        "text": "Sales revenue",
        "visible": false,
        "type": "ACCOUNTING_NUMBER"
      },
      {
        "id": "8a5c8d119bb78195019bb78b8cfa0047",
        "number": "999",
        "text": "VAT",
        "visible": false,
        "type": "ACCOUNTING_NUMBER"
      }
    ],
    "categories": [
      {
        "id": "bf10a20bead346b2a3d68b3d0f24e0bb",
        "categoryTemplateId": 434,
        "name": "Expences",
        "dateCreated": "2026-01-13T13:28:55Z",
        "accountingNumber": {
          "id": "8a5c8d119bb78195019bb78b8cf90046",
          "number": "100",
          "text": "Expenses",
          "visible": false,
          "type": "ACCOUNTING_NUMBER"
        },
        "accountingNumberId": "8a5c8d119bb78195019bb78b8cf90046",
        "accountingNumbers": [
          {
            "id": "8a5c8d119bb78195019bb78b8cf90046",
            "number": "100",
            "text": "Expenses",
            "visible": false,
            "type": "ACCOUNTING_NUMBER"
          }
        ],
        "verificationClassType": "com.findity.economy.accounting.travel.ReceiptVerification",
        "defaultTaxPercent": null,
        "mccCodes": [],
        "nonDeductableVat": false,
        "accountNumberMapping": null,
        "expenseCodeId": null,
        "salaryCodeId": null,
        "taxAccountingNumberId": null,
        "taxSalaryCodeId": null,
        "taxExpenseCodeId": null,
        "deviantTaxPercent": null,
        "budgetAmount": null,
        "budgetName": null,
        "budgetStartMonth": null,
        "presetValues": [],
        "settings": {},
        "expenseCategoryFilter": "NONE",
        "iconUrl": "https://stage-expense.findity.com/api/resources/8a49a1b45f95fc4f015f961665680001",
        "invertedIconUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e6e603c61016e6045fbc80048",
        "classType": "com.findity.economy.accounting.OtherExpenseCategory",
        "categoryGroup": "OTHER",
        "showAccounting": false,
        "showRepresentation": false,
        "presets": []
      }
    ],
    "voucherSeries": [],
    "costCenters": [],
    "projects": [],
    "customDimensionDefinitions": [],
    "customDimensions": [],
    "paymentTypes": [
      {
        "id": "3fb2c5debfb24bf6b967ae2f23538005",
        "name": "Cash",
        "accountingNumberId": "8a5c8d119bb78195019bb78b8cf90046",
        "ownerEmployeeId": null,
        "isDefault": false
      }
    ],
    "representationTypes": [
      {
        "id": "2f573194708811e1b85b00165929d3a0",
        "code": "LUNCH",
        "text": "Lunch",
        "remuneration": 90,
        "sortOrder": 1
      },
      {
        "id": "2f600102708811e1b85b00165929d3a0",
        "code": "DINNER",
        "text": "Middag",
        "remuneration": 90,
        "sortOrder": 2
      },
      {
        "id": "c26014470f7111e596875254002441aa",
        "code": "REFRESHMENTS",
        "text": "Enklare förtäring, fika etc",
        "remuneration": 60,
        "sortOrder": 3
      },
      {
        "id": "2f68e51a708811e1b85b00165929d3a0",
        "code": "OTHER",
        "text": "Övrigt",
        "remuneration": 180,
        "sortOrder": 4
      }
    ],
    "attestationSections": [],
    "allowOneDaySubsistenceAllowance": false,
    "allowFutureSubsistanceAllowance": null,
    "adminBulkSendSync": null,
    "allowOneDaySubsistenceAllowanceCustomRules": false,
    "allowOneDaySubsistenceAllowanceCustomRulesAbroad": false,
    "useOneDaySubAllowanceCustomRulesAbroadDefAmounts": false,
    "oneDaySubsistenceAllowanceMinHoursHalfDay": 0,
    "oneDaySubsistenceAllowanceMinHoursHalfDayAbroad": 0,
    "oneDaySubsistenceAllowanceMinHoursFullDay": 0,
    "oneDaySubsistenceAllowanceMinHoursFullDayAbroad": 0,
    "oneDaySubsistenceAllowanceFullDayAmount": 0,
    "oneDaySubsistenceAllowanceHalfDayAmount": 0,
    "oneDaySubsistenceAllowanceFullDayAmountAbroad": 0,
    "oneDaySubsistenceAllowanceHalfDayAmountAbroad": 0,
    "deviantFoodAmounts": false,
    "deviantHoursAndAmount": false,
    "deviantFoodAllowanceBreakfastAmount": 0,
    "deviantFoodAllowanceLunchAmount": 0,
    "deviantFoodAllowanceDinnerAmount": 0,
    "deviantFoodAllowanceBreakfastAmountAbroad": 0,
    "deviantFoodAllowanceLunchAmountAbroad": 0,
    "deviantFoodAllowanceDinnerAmountAbroad": 0,
    "deviantFoodAllowanceTaxable": false,
    "deviantFoodAllowanceTaxableAbroad": false,
    "deviantFoodAllowanceBreakfastPercent": 0,
    "deviantFoodAllowanceLunchPercent": 0,
    "deviantFoodAllowanceDinnerPercent": 0,
    "deviantFoodAllowanceAbroadBreakfastPercent": 0,
    "deviantFoodAllowanceAbroadLunchPercent": 0,
    "deviantFoodAllowanceAbroadDinnerPercent": 0,
    "subsistenceAllowanceAddPercent": 0,
    "subsistenceAllowanceAddAmount": 0,
    "subsistenceAllowanceAddPercentAccomodation": 0,
    "subsistenceAllowanceAddAmountAccomodation": 0,
    "allowReportAdminsToAttest": null,
    "allowReportAdminsToSendReports": null,
    "allowOrganizationAdminsToAttest": null,
    "allowExtendedEditing": null,
    "allowOnlyFtg": null,
    "ignoreTaxForAbroadPurchases": true,
    "bulkTransferReportsFailOnError": false,
    "temporaryApproverLimitationType": "ALL_EMPLOYEES",
    "reviewType": "NONE",
    "useTwentyFivePercentRule": false,
    "hideMarkAsPrivate": false,
    "useNewReportPreview": false,
    "allowanceType": "DEFAULT",
    "accountingSettingsId": "9327e8c57b0011e999970242ac120006",
    "accountingSettingsCountryCode": "SE",
    "usesSeparateDomesticTaxFreeSalaryCode": false,
    "useNewBulkTransferReports": true,
    "usesAccountingNumbers": true,
    "usesSalaryCodes": false,
    "usesPaymentTypes": true,
    "usesExpenseCodes": false,
    "usesBenefits": false,
    "supportsDimensions": false,
    "useAccountMapping": false,
    "showOpenEmailField": false,
    "usesNewAccountingStructure": true,
    "accountingNumbersSynced": false,
    "salaryCodesSynced": false,
    "areAccountIdsHidden": false,
    "useCreditAccountFromMileageCategory": null,
    "useCreditAccountFromSubsistenceAllowanceCategory": null,
    "reportVerificationListsType": "REPORT_PER_ACCOUNT",
    "exchangeRatePercentage": 0,
    "reportMaxNumberOfExpenses": null,
    "expenseReceiptMaxSize": null,
    "collectReports": false
  }
],
"sendEventToExternalSystemPartnerLevel": null,
"policyUrl": null
}

Step 2: Configure dimension fields

Dimension fields define the categories your customer uses to classify expenses — cost centers, projects, departments, clients, legal entities, or any custom category that fits their accounting structure. Configure the fields first, then populate them with values in Step 3.

Example request

curl --request PUT \
   --url https://stage-expense.findity.com/api/admin/organizations/externalid/{externalId}/customdimensions/ \
   --header 'Content-Type: text/plain; charset=utf-8' \
   --header 'X-Findity-ApiVersion: 3' \
   --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
   --data '[
   {
   "description":"Value",
   "level":"EXPENSE",
   "controlType":"LIST_SEARCHABLE",
   "presetLocation":"EMPLOYEE"}
  	]'

Example response

{
"result": "success",
"description": "custom dimension definition updated",
"dimensions": [
  {
    "id": "5c0f839c8a2a473da33c9f5906f6461c",
    "definition": null,
    "description": "Project",
    "type": null,
    "level": "EXPENSE",
    "presetLocation": "EMPLOYEE",
    "controlType": "LIST_SEARCHABLE",
    "userOverridable": null,
    "externalSourceId": null,
    "useDateInterval": null,
    "recipientId": null,
    "useAsRecipientFilter": null,
    "visibleIfNoPreset": null,
    "hideDimensionValues": null,
    "usedInCarbonFootprint": null,
    "deviateOnCreditRow": null,
    "deviatingCreditRowValue": null
  }
]
}

Step 3: Add dimension values

Once dimension fields exist, populate them with the specific values users can select when filing expenses. For example, the "Cost Center" field might contain values like "Marketing", "Engineering", and "Sales".

Example request

curl --request PUT \
   --url 'https://stage-expense.findity.com/api/admin/organizations/externalid/{externalId}/customdimensions/{definitionExternalId}/list/?clearBeforeUpdate=false' \
   --header 'Content-Type: text/plain; charset=utf-8' \
   --header 'X-Findity-ApiVersion: 3' \
   --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
   --data '{
     "values": [
       {
         "id": "CC-001",
         "value": "Marketing",
         "sortOrder": 1
       },
       {
         "id": "CC-002",
         "value": "Engineering",
         "sortOrder": 2
       },
       {
         "id": "CC-003",
         "value": "Sales",
         "sortOrder": 3,
         "startDate": "2026-01-01T00:00:00.000Z",
         "endDate": "2026-12-31T23:59:59.000Z"
       }
     ]
   }'

Example response

{
  "result": "success",
  "description": "custom dimension list updated",
  "values": [
    {
      "id": "CC-001",
      "value": "Marketing",
      "sortOrder": 1,
      "startDate": null,
      "endDate": null
    },
    {
      "id": "CC-002",
      "value": "Engineering",
      "sortOrder": 2,
      "startDate": null,
      "endDate": null
    },
    {
      "id": "CC-003",
      "value": "Sales",
      "sortOrder": 3,
      "startDate": "2026-01-01T00:00:00.000Z",
      "endDate": "2026-12-31T23:59:59.000Z"
    }
  ]
}

Step 4: Set up chart of accounts

The chart of accounts defines the account codes used for expense categorisation and financial reporting. Map each account to the appropriate ledger codes your customer's accounting system expects.

Example request

curl --request POST \
   --url https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/accounts \
   --header 'accept: application/json' \
   --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
   --header 'content-type: application/json' \
   --data '
    {
      "name": "Office Supplies",
      "number": "6300"
    }
    '

Example response

{
"id": "8a5c89b79c9e1024019c9e127e490001",
"meta": null,
"name": "Office Supplies",
"number": "6300"
  }

Step 5: Add users

Create user accounts for the employees who will submit, review, or approve expenses within the organisation.

Example request

curl --request PUT \
   --url 'https://stage-expense.findity.com/api/admin/organizations/externalid/{externalId}/users/?sendInvitationMail=true' \
   --header 'Content-Type: application/json' \
   --header 'X-Findity-ApiVersion: 3' \
   --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
   --data '
    [
      {
        "person": {
          "address": {
            "street1": "Street 1",
            "city": "The city",
            "postalCode": "123 45",
            "countryCode": "SE"
          },
          "externalSourceId": "{externalId}",
          "firstName": "Martin",
          "lastName": "Bekkhus",
          "email": "[email protected]"
        },
        "externalSourceId": "{externalId}",
        "employeeId": "12345",
        "organizationalUnitExternalSourceId": "1234567",
        "title": "Martin Bekkhus",
        "admin": false
      }
    ]
    '

Example response

{
"result": "success",
"description": "users updated",
"ongoingReports": [],
"movedReports": []
  }

Step 6: Create approval structure with dimensions

The approval structure defines who can approve expense reports and in what order. Approvers are assigned to specific dimension values — for example, assigning a manager as the approver for the "Marketing" cost center. When a user submits an expense tagged with that dimension value, the report routes to the assigned approver automatically.

⚠️
Enable approval first. Approval must be activated for the organisation in the Admin UI before the API endpoints work. This is a one-time manual step.

Example request

curl --request PUT \
   --url https://stage-expense.findity.com/api/admin/organizations/externalid/{externalId}/customdimensions/{definitionExternalId}/list/approvers/ \
   --header 'Content-Type: text/plain; charset=utf-8' \
   --header 'X-Findity-ApiVersion: 3' \
   --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
   --data '{
     "values": [
       {
         "id": "CC-001",
         "approvers": [
           {
             "externalSourceId": "approver-ext-001",
             "sortOrder": 0,
             "personExternalSourceId": "person-ext-001"
           }
         ]
       },
       {
         "id": "CC-002",
         "approvers": [
           {
             "externalSourceId": "approver-ext-002",
             "sortOrder": 0,
             "personExternalSourceId": "person-ext-002"
           },
           {
             "externalSourceId": "approver-ext-003",
             "sortOrder": 1,
             "personExternalSourceId": "person-ext-003"
           }
         ]
       }
     ]
   }'

Example response

{
  "result": "success",
  "description": "approvers updated",
  "values": [
    {
      "id": "CC-001",
      "approvers": [
        {
          "externalSourceId": "approver-ext-001",
          "sortOrder": 0,
          "personExternalSourceId": "person-ext-001",
          "delete": false
        }
      ]
    },
    {
      "id": "CC-002",
      "approvers": [
        {
          "externalSourceId": "approver-ext-002",
          "sortOrder": 0,
          "personExternalSourceId": "person-ext-002",
          "delete": false
        },
        {
          "externalSourceId": "approver-ext-003",
          "sortOrder": 1,
          "personExternalSourceId": "person-ext-003",
          "delete": false
        }
      ]
    }
  ]
}

Next steps

Organisations

Manage organisation settings, lookup, and report counters.

Dimensions

Configure dimension fields and manage value lists.

Users

Add, update, and remove employees from an organisation.

Chart of Accounts

Set up and maintain account codes for expense categorisation.

Approval Structure

Define approval workflows and routing rules.

Expense API

Start working with expense reports after provisioning is complete.