Accounting Objects

Overview

The Accounting Objects API lets your system push organisational dimension data to SoftCo's AP platform. Accounting objects are the building blocks SoftCo uses to represent how your organisation is structured — cost centres, departments, business units, projects, and similar classifications that AP users apply when coding invoices and requisitions.

SoftCo supports up to nine distinct accounting object types, each representing a different dimension of your organisational structure. Most customers configure at least one type — typically a cost centre — but you can use as many as your organisation requires. Each type is managed independently: you send a separate request per type, identified by the accountingType query parameter.

Accounting Object Types

The table below shows the range of accounting object types SoftCo supports. Your specific types and their identifiers are configured during onboarding — your SoftCo Customer Success representative will confirm which types are active for your organisation and what values to use for accountingType.

Organisation scope and the organization field

Like all SoftCo master data, accounting objects can be scoped to a specific legal entity or made available across all organisations. Use "organization": "main" for codes that apply across the entire organisation — for example, a shared set of cost centres used by all business units. For codes specific to a particular legal entity or operating company, supply that entity's organisation code. The behaviour mirrors the GL Codes API and is consistent across all master data interfaces.

When to call this endpoint

Quick Start

Here's the fastest path to a successful integration. Copy this request, swap in your credentials, your accountingType value, and a real accounting object from your ERP, then send it.

POST /accounting-objects/v1?accountingType=COSTCENTRE
x-api-key:     your-api-key-here
Content-Type:  application/Json
Client_Id:     your-client-id
Client_Secret: your-client-secret

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization":   "main",
        "code":           "1001",
        "description_en": "Sales"
        }
      ]
    }
  }
}

A successful response looks like this:

{
  "status":     "SUCCESS",
  "total":      1,
  "succeeded":  1,
  "failed":     0,
  "errors":     [],
  "message":    "All items processed successfully"
}

How It Works

Every request follows the same pipeline. Your system only needs to send once — resilience, retries, and delivery to SoftCo are handled automatically.

Authentication

All requests require an API key and OAuth 2.0 credentials. Your credentials are provided during onboarding — keep them secure and never expose them in client-side code or version control.

Requests with a missing or invalid API key are rejected by the gateway immediately and never reach the integration layer.

Required Headers

Response Codes

These response codes apply to all endpoints. Build your error handling around them from the start.

POST /accounting-objects/v1

Submit one or more accounting object records to SoftCo's AP platform. The payload is validated, transformed, and queued for delivery to the specified accounting dimension.

Query Parameter

Request Headers

Request Body

Your JSON payload wraps accounting object fields inside an objects → object → record envelope. This structure is consistent across all SoftCo master data endpoints.

A single request can carry one record or a batch of multiple records. For a single record request, record is a JSON array with only one element containing the field values. For a batch, record becomes a JSON array where each element is an object representing one accounting entry. Both forms are shown below and illustrated in the Example Request section.

Single record

Multiple records (batch)

Field Reference

All fields sit inside objects.object.record. The table below covers every field, its type, whether it's required, SoftCo defaults where applicable, and practical mapping guidance.

Example Request

The examples below use cost centre as the accounting type. Replace COSTCENTRE with your configured accountingType value and field values with your own data.

Full Example — All Fields

POST /accounting-objects/v1?accountingType=COSTCENTRE
Content-Type:  application/Json
x-api-key:     your-api-key-here
Client_Id:     your-client-id
Client_Secret: your-client-secret

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization":      "main",
        "code":              "1001",
        "description_en":    "Sales",
        "description_en_US": "Sales",
        "description_fi_fi": "Myynti",
        "description_sv_SE": "Försäljning",
        "start_date":        "2001-01-01",
        "end_date":          "2999-12-31"
        }
      ]
    }
  }
}

Minimum Required Fields

Only the three required fields. Locale descriptions and recommended fields can be added incrementally.

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization":   "main",
        "code":           "1006",
        "description_en": "Finance"
        }
      ]      
    }
  }
}

With Locale Descriptions

Include locale fields only for the locales your organisation actively uses.

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization":      "main",
        "code":              "1003",
        "description_en":    "Operations",
        "description_fi_fi": "Toiminnot",    // Finnish locale in use
        "description_sv_SE": "Operationer"   // Swedish locale in use
        }
      ]      
    }
  }
}

Batch — Multiple Records in One Request

When sending more than one accounting object in a single request, record becomes a JSON array where each element follows the same field structure as a single-record request. All records in a batch must belong to the same accountingType — if you need to send records for different types, use separate requests.

POST /accounting-objects/v1?accountingType=COSTCENTRE
Content-Type:  application/Json
x-api-key:     your-api-key-here
Client_Id:     your-client-id
Client_Secret: your-client-secret

{
  "objects": {
    "object": {
      "record": [                    // record is an array when sending multiple objects
        {
          "organization":    "main",
          "code":            "1001",
          "description_en":  "Sales",
          "start_date":      "2001-01-01",
          "end_date":        "2999-12-31"
        },
        {
          "organization":    "main",
          "code":            "1002",
          "description_en":  "Marketing",
          "start_date":      "2001-01-01",
          "end_date":        "2999-12-31"
        }
      ]
    }
  }
}

Validation

Your payload is validated before anything else happens. If validation fails, you get a 400 immediately with a specific error message — nothing is queued or forwarded. Fix the payload and retry.

What gets checked

Validation summary

Troubleshooting

The most common issue is a 400 Bad Request caused by a validation failure. The response body always includes an error_message field that tells you exactly what went wrong. Below are the errors you're most likely to encounter and how to fix them.

Record not appearing in SoftCo?

If you received a 202 Accepted or 207 Multi-Status but the accounting object has not appeared in SoftCo after several minutes, there is no need to take immediate action — the integration queue manages retries automatically. If it still hasn't appeared after a reasonable period, contact your SoftCo Customer Success representative with the approximate timestamp of your request and they can check the queue and delivery status on your behalf. Resending the record is also safe — SoftCo processes all master data as incremental updates, so the data will simply be refreshed.

Unsure of your accountingType values?

The valid accountingType identifiers for your organisation are configured in SoftCo during onboarding. If you are unsure which values to use, or if you need to confirm which accounting dimension types are active for your organisation, contact your SoftCo Customer Success representative.

Example Responses

The response structure is consistent across all outcomes. The HTTP status code and the status field together tell you exactly what happened.

202 Accepted — All Records Processed

Every record in the request was validated and queued successfully. Delivery to SoftCo is asynchronous and typically completes within minutes.

{
  "status":     "SUCCESS",
  "total":      1,
  "succeeded":  1,
  "failed":     0,
  "errors":     [],
  "message":    "All items processed successfully"
}

207 Multi-Status — Partial Success

Some records in a batch passed and were queued; others failed validation. Check the errors array to identify which records need to be fixed and resubmitted.

{
  "status":     "PARTIAL",
  "total":      2,
  "succeeded":  1,
  "failed":     1,
  "errors": [
    {
      "index":  2,
      "error":  "description_en is required."
    }
  ],
  "message":    "Your request was partially successful. Out of 2 items, 1 were processed successfully and 1 failed."
}

400 Bad Request — Invalid Request Structure

The request envelope is missing or malformed. No records were processed. The expected_format field describes the correct structure.

{
  "status":          "FAILED",
  "total":           0,
  "succeeded":       0,
  "failed":          0,
  "errors": [
    {
      "index":       0,
      "error":       "The request is missing the objects section."
    }
  ],
  "message":         "No items could be processed. Expected format: objects → object → record (record must be a non-empty array of items).",
  "expected_format": "objects → object → record (record must be a non-empty array of items)"
}

401 Unauthorized

API key missing or invalid. Request rejected at the gateway before reaching the integration layer.

{
  "status":   "FAILED",
  "message": "Unauthorized — API key is missing or invalid"
}

What's Next

Accounting Objects are typically set up alongside GL Account Codes and Vendor Data as part of your master data foundation. Once all master data interfaces are in place, you're ready to start sending transactional data.

Master Data

Complete the remaining master data interfaces to give SoftCo the reference data it needs for AP coding, supplier management, and catalogue purchasing.

Transaction Data

Once your master data interfaces are in place, you're ready to start sending transactional data. These interfaces drive the day-to-day AP processing workflows in SoftCo.