General Ledger Account Codes

Overview

The General Ledger Account Codes API lets your system push GL account master data to SoftCo's AP platform on demand. SoftCo uses this data to populate the GL account list that AP users see when coding invoices — so keeping it current in SoftCo means fewer manual lookups and fewer coding errors.

You control when data is sent. There's no scheduled sync to configure — call this endpoint whenever an account is created, updated, or needs to be deactivated in SoftCo.

When to call this endpoint

Quick Start

Here's the fastest path to a successful integration. Copy this request, swap in your credentials and a real GL account from your ERP, and send it.

POST /general-ledger-codes/v1
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":           "52111",
        "type":           "DEDUCTABLE",
        "description_en": "Office Supplies"
        }
      ]
    }
  }
}

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. The integration is designed so that 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 /general-ledger-codes/v1

Submit one or more GL account records to SoftCo's AP platform. The payload is validated, transformed, and queued for delivery.

Request Headers

Request Body

Your JSON payload wraps GL account 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 GL account. 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, valid values, SoftCo defaults where applicable, and practical mapping guidance.

Example Request

A complete request with all fields. Replace credentials and field values with your own data.

POST /general-ledger-codes/v1
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":              "52111",
        "type":              "DEDUCTABLE",
        "description_en":    "Office Supplies",
        "description_en_US": "Office Supplies",
        "description_fi_FI": "Toimistotarvikkeet",
        "description_sv_SE": "Kontorsmaterial",
        "tax_code":          "I0",
        "catalog_product":   "YES",
        "product_group":     "MARKETING",
        "start_date":        "2001-01-01",
        "end_date":          "2999-12-31"
        }
      ]
    }
  }
}

Minimum Required Fields

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

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization":   "main",
        "code":           "72315",
        "type":           "DEDUCTABLE",
        "description_en": "Telephone"
        }
      ]      
    }
  }
}

With Locale Descriptions

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

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization":      "main",
        "code":              "72315",
        "type":              "DEDUCTABLE",
        "description_en":    "Telephone",
        "description_fi_FI": "Puhelin",    // Finnish locale in use
        "description_sv_SE": "Telefon"     // Swedish locale in use
        }
      ]  
    }
  }
}

Batch — Multiple Records in One Request

When sending more than one GL account in a single request, record becomes a JSON array where each element follows the same field structure as a single-record request. The outer objects → object envelope stays exactly the same. This is particularly useful for initial data loads or synchronising a set of related accounts at once.

POST /general-ledger-codes/v1
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 accounts
        {
          "organization":    "main",
          "code":            "52111",
          "type":            "DEDUCTABLE",
          "description_en":  "Office Supplies",
          "tax_code":        "I0",
          "catalog_product": "YES",
          "product_group":   "MARKETING",
          "start_date":      "2001-01-01",
          "end_date":        "2999-12-31"
        },
        {
          "organization":    "main",
          "code":            "56120",
          "type":            "DEDUCTABLE",
          "description_en":  "Travel & Accommodation",
          "tax_code":        "I0",
          "catalog_product": "YES",
          "product_group":   "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 but the GL account 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.

Example Responses

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 were queued; one or more failed validation. Only the failed 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. 1 of 2 records were queued for delivery."
}

400 Bad Request — Invalid Request Structure

The request envelope is missing or malformed. No records were processed.

{
  "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 as the request structure was invalid.",
  "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

GL Codes are typically one of several master data types you'll need to sync before go-live. Once GL Codes are in place, most integrations continue with vendor data and accounting objects.

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.