Vendor Data

Overview

The Vendor Data API lets your system push supplier and vendor master records to SoftCo's AP platform. Vendor data forms the cornerstone of accounts payable — every invoice processed in SoftCo is matched against a supplier record, and payment runs draw directly from the banking and payment details held here. Keeping your vendor master in sync ensures accurate invoice matching, clean payment processing, and an up-to-date supplier list for AP users.

A single call to POST /vendor-data/v1 creates or updates one or more vendor records. Vendor records carry a rich field set covering identity, contact information, address, bank account details, financial and payment settings, and procurement preferences. Each vendor can have multiple bank accounts, represented as an array within the record.

Organisation scope and the organization field

Like all SoftCo master data, vendor records are scoped to a company or legal entity using the organization field. Use "organization": "main" for vendors that are shared across the whole organisation. For vendors specific to a particular legal entity or operating company, supply that entity's organisation code. The behaviour 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 and a real vendor from your ERP, then send it. The minimum required fields are organization, code, and name — everything else can be added incrementally.

POST /vendor-data/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":         "SUP-00123",
        "name":         "Global Supplies Ltd"
        }
      ]
    }
  }
}

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 /vendor-data/v1

Submit one or more vendor records to SoftCo's AP platform. The payload is validated, transformed, and queued for delivery to the supplier master. Unlike other master data endpoints, POST /vendor-data/v1 requires no query parameters — the endpoint handles all vendor types.

Request Headers

Request Body

Your JSON payload wraps vendor 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 vendor. The outer objects → object envelope remains the same in both cases.

Vendor records also support a nested account array within each record. This array holds one or more bank account entries for the vendor — include one element per bank account. If the vendor has no banking details to send, omit the account field entirely.

Single record

Multiple records (batch)

Field Reference

All fields sit inside objects.object.record. Bank account fields sit inside the nested account array within each record. The table below covers every field, grouped by function.

Example Request

The examples below cover the most common scenarios. Replace the field values with real data from your ERP.

Full Example — All Field Groups

POST /vendor-data/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": [
        {      
        // Core Identity
        "organization":      "main",
        "code":              "SUP-00123",
        "name":              "Global Supplies Ltd",
        "status":            "active",
        "start_date":        "2020-01-01",
        "end_date":          "2999-12-31",
        "vat_number":        "GB123456789",
        "edi_id":            "EDI-GSL-001",
        // Contact & Address
        "email":             "accounts@globalsupplies.com",
        "telephone_number":  "+44 20 7946 0958",
        "address_1":         "14 Commerce Street",
        "address_2":         "Floor 3",
        "city":              "London",
        "postcode":          "EC2A 1AB",
        "country":           "United Kingdom",
        // Bank Account Details
        "account": [
          {
            "bank_name":     "Barclays Bank",
            "bank_account":  "12345678",
            "bank_sort_code":"20-00-00",
            "bank_iban":     "GB29BARC20000012345678",
            "bank_bic":      "BARCGB22",
            "bank_currency": "GBP"
          }
        ],
        // Financial & Payment Settings
        "currency":          "GBP",
        "payment_term":      "NET30",
        "default_vat":       "S20",
        "payment_method":    "BACS",
        // Procurement Preferences
        "porequired":        "YES",
        "po_language":       "EN",
        "order_confirmation":"NO"
        }
      ]
    }
  }
}

Minimum Required Fields

Only the three required fields. All other details can be added in a subsequent update call.

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization": "main",
        "code":         "SUP-00124",
        "name":         "Acme Corp"
        }
      ]
    }
  }
}

Vendor with Multiple Bank Accounts

When a vendor has more than one bank account — for example, a GBP domestic account and a EUR international account — include one object per account in the account array.

{
  "objects": {
    "object": {
      "record": [
        {      
        "organization": "main",
        "code":         "SUP-00125",
        "name":         "European Logistics GmbH",
        "currency":     "EUR",
        "account": [
          {
            // Primary EUR account
            "bank_name":     "Deutsche Bank",
            "bank_iban":     "DE89370400440532013000",
            "bank_bic":      "DEUTDEDB",
            "bank_currency": "EUR"
          },
          {
            // Secondary GBP account
            "bank_name":     "Barclays Bank",
            "bank_account":  "87654321",
            "bank_sort_code":"20-00-00",
            "bank_iban":     "GB29BARC20000087654321",
            "bank_bic":      "BARCGB22",
            "bank_currency": "GBP"
          }
        ]
        }
      ]
    }
  }
}

Batch — Multiple Vendors in One Request

When sending more than one vendor 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.

POST /vendor-data/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 vendors
        {
          "organization": "main",
          "code":         "SUP-00123",
          "name":         "Global Supplies Ltd",
          "currency":     "GBP",
          "payment_term": "NET30",
          "start_date":   "2020-01-01",
          "end_date":     "2999-12-31",
          "account": [{
            "bank_name":     "Barclays Bank",
            "bank_iban":     "GB29BARC20000012345678",
            "bank_bic":      "BARCGB22",
            "bank_currency": "GBP"
          }]
        },
        {
          "organization": "main",
          "code":         "SUP-00124",
          "name":         "Acme Corp",
          "currency":     "USD",
          "payment_term": "NET60",
          "start_date":   "2021-06-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.

Vendor not appearing in SoftCo?

If you received a 202 Accepted but the vendor 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": "name 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

Vendor Data is the third of four master data interfaces. Once all master data is in place, you're ready to start sending transactional data.

Master Data

Complete the remaining master data interface to give SoftCo the full reference data set it needs for AP processing.

Transaction Data

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