Suppliers

Create and manage supplier accounts via secure, RESTful API endpoints.

Overview

The Suppliers API provides secure endpoints to create and manage supplier accounts. Use Create Supplier to register a new supplier company, generate a vendor code, and automatically provision a default site, SAQ entry, and supplier user account.

LIVE https://developer.traceallglobal.com/api/v1
Key Features
  • Auto-generated vendor codes
  • Default site & SAQ provisioned
  • Supplier user account created
  • Welcome email dispatched

Bulk Upload CSV Template

Download the ready-to-use CSV template to prepare your supplier data. Fill in the required columns and upload via POST /suppliers/createSupplierBulk.

No sign-in required 20 columns · 1 example row Excel compatible (.csv)
Download Template
CSV  ·  Excel compatible

API Endpoints

POST
/suppliers/createSupplier
Create a new supplier
POST
/suppliers/createSupplierBulk
Bulk create suppliers via JSON or CSV
PUT
/suppliers/{supplierid}
Update an existing supplier
DELETE
/suppliers/{supplierid}
Soft-delete a supplier

Create a new supplier company. A vendor code is generated automatically from the company name. The endpoint also provisions a default site, an SAQ record, and a supplier user account. A welcome email with credentials is sent to the supplier contact if email is configured. Requires API permission level 2 (Editor) or higher.

Parameters

X-API-Key (header, string, Required) - Your API key for authentication. Handles JWT validation automatically.

Content-Type (header, string, Required) - Must be set to application/json.

Body (JSON) (object, Required) - All fields marked Required must be present:

  • companyname (string, Required)
  • address1 (string, Required)
  • address2 (string, Optional)
  • address3 (string, Optional)
  • city (string, Required)
  • postcode (string, Required)
  • country (integer, Required) — country ID
  • techcontactname (string, Required) — technical contact full name
  • techcontactemail (string, Required) — valid email address
  • techmobileno (string, Required)
  • tracealluserfirstname (string, Required) — supplier portal user first name
  • traceallusersurname (string, Required) — supplier portal user last name
  • tracealluseremail (string, Required) — supplier portal user email (must be unique)
  • traceallusermobileno (string, Required)
  • comcontactname (string, Required) — commercial contact full name
  • comcontactemail (string, Required) — valid email address
  • commobileno (string, Required)
  • supplier_type (integer, Required) — supplier type ID
  • risk (integer, Required) — risk level ID
  • comments (string, Optional)
Sample JSON: 
{
  "companyname": "Acme Foods Ltd",
  "address1": "10 Industrial Way",
  "address2": "",
  "address3": "",
  "city": "Manchester",
  "postcode": "M1 1AB",
  "country": 1,
  "techcontactname": "John Smith",
  "techcontactemail": "john.smith@acmefoods.co.uk",
  "techmobileno": "+44 7700 900001",
  "tracealluserfirstname": "John",
  "traceallusersurname": "Smith",
  "tracealluseremail": "john.smith@acmefoods.co.uk",
  "traceallusermobileno": "+44 7700 900001",
  "comcontactname": "Sarah Jones",
  "comcontactemail": "sarah.jones@acmefoods.co.uk",
  "commobileno": "+44 7700 900002",
  "supplier_type": 1,
  "risk": 1,
  "comments": "New supplier onboarded via API"
}
Test this endpoint
Your authentication key for API access
Provide all required supplier fields as JSON

Response Examples

JSON Response 
{
  "success": true,
  "message": "Supplier created successfully",
  "supplierid": 456,
  "siteid": 789,
  "vendorcode": "ACME001"
}
JSON Response 
{
  "success": false,
  "error": "Missing API key"
}
JSON Response 
{
  "success": false,
  "error": "Missing required field: companyname"
}
JSON Response 
{
  "success": false,
  "error": "Supplier not added, email already exists"
}
JSON Response 
{
  "success": false,
  "error": "Database error during supplier creation"
}

Code Examples

Shell Command 
curl -X POST "https://developer.traceallglobal.com/api/v1/suppliers/createSupplier" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyname": "Acme Foods Ltd",
    "address1": "10 Industrial Way",
    "address2": "",
    "address3": "",
    "city": "Manchester",
    "postcode": "M1 1AB",
    "country": 1,
    "techcontactname": "John Smith",
    "techcontactemail": "john.smith@acmefoods.co.uk",
    "techmobileno": "+44 7700 900001",
    "tracealluserfirstname": "John",
    "traceallusersurname": "Smith",
    "tracealluseremail": "john.smith@acmefoods.co.uk",
    "traceallusermobileno": "+44 7700 900001",
    "comcontactname": "Sarah Jones",
    "comcontactemail": "sarah.jones@acmefoods.co.uk",
    "commobileno": "+44 7700 900002",
    "supplier_type": 1,
    "risk": 1,
    "comments": "New supplier onboarded via API"
  }'
JavaScript Code 
fetch('https://developer.traceallglobal.com/api/v1/suppliers/createSupplier', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    companyname: 'Acme Foods Ltd',
    address1: '10 Industrial Way',
    address2: '',
    address3: '',
    city: 'Manchester',
    postcode: 'M1 1AB',
    country: 1,
    techcontactname: 'John Smith',
    techcontactemail: 'john.smith@acmefoods.co.uk',
    techmobileno: '+44 7700 900001',
    tracealluserfirstname: 'John',
    traceallusersurname: 'Smith',
    tracealluseremail: 'john.smith@acmefoods.co.uk',
    traceallusermobileno: '+44 7700 900001',
    comcontactname: 'Sarah Jones',
    comcontactemail: 'sarah.jones@acmefoods.co.uk',
    commobileno: '+44 7700 900002',
    supplier_type: 1,
    risk: 1,
    comments: 'New supplier onboarded via API'
  })
})
.then(response => response.json())
.then(data => console.log(data));
Python Code 
import requests

url = "https://developer.traceallglobal.com/api/v1/suppliers/createSupplier"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "companyname": "Acme Foods Ltd",
    "address1": "10 Industrial Way",
    "address2": "",
    "address3": "",
    "city": "Manchester",
    "postcode": "M1 1AB",
    "country": 1,
    "techcontactname": "John Smith",
    "techcontactemail": "john.smith@acmefoods.co.uk",
    "techmobileno": "+44 7700 900001",
    "tracealluserfirstname": "John",
    "traceallusersurname": "Smith",
    "tracealluseremail": "john.smith@acmefoods.co.uk",
    "traceallusermobileno": "+44 7700 900001",
    "comcontactname": "Sarah Jones",
    "comcontactemail": "sarah.jones@acmefoods.co.uk",
    "commobileno": "+44 7700 900002",
    "supplier_type": 1,
    "risk": 1,
    "comments": "New supplier onboarded via API"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
Java Code 
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

String jsonData = """
{
  "companyname": "Acme Foods Ltd",
  "address1": "10 Industrial Way",
  "address2": "",
  "address3": "",
  "city": "Manchester",
  "postcode": "M1 1AB",
  "country": 1,
  "techcontactname": "John Smith",
  "techcontactemail": "john.smith@acmefoods.co.uk",
  "techmobileno": "+44 7700 900001",
  "tracealluserfirstname": "John",
  "traceallusersurname": "Smith",
  "tracealluseremail": "john.smith@acmefoods.co.uk",
  "traceallusermobileno": "+44 7700 900001",
  "comcontactname": "Sarah Jones",
  "comcontactemail": "sarah.jones@acmefoods.co.uk",
  "commobileno": "+44 7700 900002",
  "supplier_type": 1,
  "risk": 1,
  "comments": "New supplier onboarded via API"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://developer.traceallglobal.com/api/v1/suppliers/createSupplier"))
    .header("X-API-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonData))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
PHP Code 
<?php
$url = 'https://developer.traceallglobal.com/api/v1/suppliers/createSupplier';
$headers = [
    'X-API-Key: YOUR_API_KEY',
    'Content-Type: application/json'
];
$data = [
    'companyname'           => 'Acme Foods Ltd',
    'address1'              => '10 Industrial Way',
    'address2'              => '',
    'address3'              => '',
    'city'                  => 'Manchester',
    'postcode'              => 'M1 1AB',
    'country'               => 1,
    'techcontactname'       => 'John Smith',
    'techcontactemail'      => 'john.smith@acmefoods.co.uk',
    'techmobileno'          => '+44 7700 900001',
    'tracealluserfirstname' => 'John',
    'traceallusersurname'   => 'Smith',
    'tracealluseremail'     => 'john.smith@acmefoods.co.uk',
    'traceallusermobileno'  => '+44 7700 900001',
    'comcontactname'        => 'Sarah Jones',
    'comcontactemail'       => 'sarah.jones@acmefoods.co.uk',
    'commobileno'           => '+44 7700 900002',
    'supplier_type'         => 1,
    'risk'                  => 1,
    'comments'              => 'New supplier onboarded via API',
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => $headers,
    CURLOPT_POSTFIELDS     => json_encode($data),
]);

$response = curl_exec($curl);
$result   = json_decode($response, true);
curl_close($curl);

print_r($result);
?>

Create multiple supplier accounts in a single request. Accepts either a JSON array of supplier objects (application/json) or a CSV file upload (multipart/form-data, field name file). Each row is processed independently — failures are collected and returned with a retry_payload so failed rows can be resubmitted without reprocessing successes. Requires API permission level 2 (Editor) or higher.

Parameters

X-API-Key (header, string, Required) - Your API key for authentication. Handles JWT validation automatically.

Content-Type (header, string, Required) - Either application/json for a JSON array body, or multipart/form-data for a CSV file upload.

Body (Required) - One of:

  • JSON array: An array of supplier objects. Each object uses the same fields as createSupplier. A single object is also accepted.
  • CSV file: A .csv file in form field file. Headers must match the template from getSupplierCsvTemplate (case-insensitive).
Sample JSON array (2 suppliers): 
[
  {
    "companyname": "Acme Foods Ltd",
    "address1": "10 Industrial Way",
    "address2": "",
    "address3": "",
    "city": "Manchester",
    "postcode": "M1 1AB",
    "country": 1,
    "techcontactname": "John Smith",
    "techcontactemail": "john.smith@acmefoods.co.uk",
    "techmobileno": "+44 7700 900001",
    "tracealluserfirstname": "John",
    "traceallusersurname": "Smith",
    "tracealluseremail": "john.smith@acmefoods.co.uk",
    "traceallusermobileno": "+44 7700 900001",
    "comcontactname": "Sarah Jones",
    "comcontactemail": "sarah.jones@acmefoods.co.uk",
    "commobileno": "+44 7700 900002",
    "supplier_type": 1,
    "risk": 1,
    "comments": ""
  },
  {
    "companyname": "Beta Ingredients Ltd",
    "address1": "22 Logistics Road",
    "address2": "",
    "address3": "",
    "city": "Birmingham",
    "postcode": "B1 1BB",
    "country": 1,
    "techcontactname": "Alice Brown",
    "techcontactemail": "alice.brown@betaingredients.co.uk",
    "techmobileno": "+44 7700 900010",
    "tracealluserfirstname": "Alice",
    "traceallusersurname": "Brown",
    "tracealluseremail": "alice.brown@betaingredients.co.uk",
    "traceallusermobileno": "+44 7700 900010",
    "comcontactname": "Mark Taylor",
    "comcontactemail": "mark.taylor@betaingredients.co.uk",
    "commobileno": "+44 7700 900011",
    "supplier_type": 1,
    "risk": 2,
    "comments": ""
  }
]
Test this endpoint (JSON array)
Provide a JSON array of supplier objects. Each must include all required fields.

Response Examples 

{
  "success": true,
  "total": 2,
  "created": 1,
  "failed": 1,
  "results": [
    {
      "row": 1,
      "companyname": "Acme Foods Ltd",
      "status": "success",
      "supplierid": 456,
      "siteid": 789,
      "vendorcode": "ACME001"
    },
    {
      "row": 2,
      "companyname": "Beta Ingredients Ltd",
      "status": "error",
      "message": "Email already exists: alice.brown@betaingredients.co.uk"
    }
  ],
  "retry_payload": [
    {
      "companyname": "Beta Ingredients Ltd",
      "tracealluseremail": "alice.brown@betaingredients.co.uk"
    }
  ]
}
{
  "success": false,
  "error": "Missing API key"
}
{
  "success": false,
  "error": "Request body must be a non-empty JSON array of supplier objects"
}
{
  "success": false,
  "error": "Unsupported content type. Use application/json or multipart/form-data with a CSV file."
}

Code Examples

Shell Command 
# JSON array
curl -X POST "https://developer.traceallglobal.com/api/v1/suppliers/createSupplierBulk" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"companyname":"Acme Foods Ltd","address1":"10 Industrial Way","city":"Manchester","postcode":"M1 1AB","country":1,"techcontactname":"John Smith","techcontactemail":"john@acme.co.uk","techmobileno":"+44 7700 900001","tracealluserfirstname":"John","traceallusersurname":"Smith","tracealluseremail":"john@acme.co.uk","traceallusermobileno":"+44 7700 900001","comcontactname":"Sarah Jones","comcontactemail":"sarah@acme.co.uk","commobileno":"+44 7700 900002","supplier_type":1,"risk":1}]'

# CSV file upload
curl -X POST "https://developer.traceallglobal.com/api/v1/suppliers/createSupplierBulk" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@supplier_upload_template.csv"
JavaScript Code 
const suppliers = [
  {
    companyname: 'Acme Foods Ltd',
    address1: '10 Industrial Way',
    city: 'Manchester',
    postcode: 'M1 1AB',
    country: 1,
    techcontactname: 'John Smith',
    techcontactemail: 'john@acme.co.uk',
    techmobileno: '+44 7700 900001',
    tracealluserfirstname: 'John',
    traceallusersurname: 'Smith',
    tracealluseremail: 'john@acme.co.uk',
    traceallusermobileno: '+44 7700 900001',
    comcontactname: 'Sarah Jones',
    comcontactemail: 'sarah@acme.co.uk',
    commobileno: '+44 7700 900002',
    supplier_type: 1,
    risk: 1
  }
];

fetch('https://developer.traceallglobal.com/api/v1/suppliers/createSupplierBulk', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify(suppliers)
})
.then(response => response.json())
.then(data => {
  console.log(`Created: ${data.created}, Failed: ${data.failed}`);
  if (data.retry_payload.length > 0) {
    console.log('Retry these rows:', data.retry_payload);
  }
});
Python Code 
import requests

url = "https://developer.traceallglobal.com/api/v1/suppliers/createSupplierBulk"
headers = {"X-API-Key": "YOUR_API_KEY"}

# JSON array
suppliers = [
    {
        "companyname": "Acme Foods Ltd",
        "address1": "10 Industrial Way",
        "city": "Manchester",
        "postcode": "M1 1AB",
        "country": 1,
        "techcontactname": "John Smith",
        "techcontactemail": "john@acme.co.uk",
        "techmobileno": "+44 7700 900001",
        "tracealluserfirstname": "John",
        "traceallusersurname": "Smith",
        "tracealluseremail": "john@acme.co.uk",
        "traceallusermobileno": "+44 7700 900001",
        "comcontactname": "Sarah Jones",
        "comcontactemail": "sarah@acme.co.uk",
        "commobileno": "+44 7700 900002",
        "supplier_type": 1,
        "risk": 1
    }
]

response = requests.post(url, headers=headers, json=suppliers)
data = response.json()
print(f"Created: {data['created']}, Failed: {data['failed']}")
if data.get('retry_payload'):
    print("Retry these rows:", data['retry_payload'])

# CSV file upload
# with open('suppliers.csv', 'rb') as f:
#     r = requests.post(url, headers={'X-API-Key': 'YOUR_API_KEY'}, files={'file': f})
PHP Code 
<?php
$url  = 'https://developer.traceallglobal.com/api/v1/suppliers/createSupplierBulk';
$data = [
    [
        'companyname'           => 'Acme Foods Ltd',
        'address1'              => '10 Industrial Way',
        'city'                  => 'Manchester',
        'postcode'              => 'M1 1AB',
        'country'               => 1,
        'techcontactname'       => 'John Smith',
        'techcontactemail'      => 'john@acme.co.uk',
        'techmobileno'          => '+44 7700 900001',
        'tracealluserfirstname' => 'John',
        'traceallusersurname'   => 'Smith',
        'tracealluseremail'     => 'john@acme.co.uk',
        'traceallusermobileno'  => '+44 7700 900001',
        'comcontactname'        => 'Sarah Jones',
        'comcontactemail'       => 'sarah@acme.co.uk',
        'commobileno'           => '+44 7700 900002',
        'supplier_type'         => 1,
        'risk'                  => 1,
    ],
];
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($data),
]);
$response = curl_exec($curl);
$result   = json_decode($response, true);
curl_close($curl);
echo "Created: {$result['created']}, Failed: {$result['failed']}\n";
if (!empty($result['retry_payload'])) {
    echo "Retry: " . json_encode($result['retry_payload'], JSON_PRETTY_PRINT) . "\n";
}
?>

Update one or more fields on an existing supplier company. Only the fields you include in the JSON body are changed — omitted fields are left untouched (PATCH-style). Requires API permission level 2 (Editor) or higher.

Parameters

X-API-Key (header, string, Required)

supplierid (URL path, integer, Required) — e.g. PUT /suppliers/456

Body (JSON) (object, Optional) — include only the fields you want to change:

  • companyname (string)
  • address1, address2, address3 (string)
  • city, postcode (string)
  • country (integer — country ID)
  • techcontactname, techcontactemail, techmobileno (string)
  • comcontactname, comcontactemail, commobileno (string)
  • supplier_type (integer)
  • risk (integer)
  • comments (string)
Sample JSON: 
{
  "companyname": "Updated Acme Foods Ltd",
  "city": "London",
  "postcode": "E1 6AN",
  "techcontactname": "Jane Doe",
  "techcontactemail": "jane.doe@acme.co.uk",
  "comments": "Updated via API"
}
Test this endpoint
Include only the fields you want to change.

Response Examples 

{
  "success": true,
  "message": "Supplier updated successfully",
  "supplierid": 456,
  "vendorcode": "ACME001",
  "companyname": "Updated Name Ltd"
}
{
  "success": false,
  "error": "No valid fields provided to update"
}
{
  "success": false,
  "error": "Supplier not found or already inactive"
}

Code Examples

Shell Command 
curl -X PUT "https://developer.traceallglobal.com/api/v1/suppliers/456" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyname": "Updated Acme Foods Ltd", "city": "London"}'
JavaScript Code 
fetch('https://developer.traceallglobal.com/api/v1/suppliers/456', {
  method: 'PUT',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    companyname: 'Updated Acme Foods Ltd',
    city: 'London'
  })
})
.then(r => r.json())
.then(data => console.log(data));
Python Code 
import requests

response = requests.put(
    'https://developer.traceallglobal.com/api/v1/suppliers/456',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'companyname': 'Updated Acme Foods Ltd', 'city': 'London'}
)
print(response.json())
PHP Code 
<?php
$supplierid = 456;
$url        = "https://developer.traceallglobal.com/api/v1/suppliers/$supplierid";
$data       = ['companyname' => 'Updated Acme Foods Ltd', 'city' => 'London'];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($data),
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);
print_r($result);
?>

Deactivates a supplier by setting active = 0 on the company record. Related sites and supplier users are also deactivated in the same transaction. Data is never permanently deleted — it can be reactivated manually. Requires API permission level 3 (Manager) or higher.

Parameters

X-API-Key (header, string, Required)

supplierid (URL path, integer, Required) — e.g. DELETE /suppliers/456

Test this endpoint

Response Examples 

{
  "success": true,
  "message": "Supplier deactivated successfully",
  "supplierid": 456
}
{
  "success": false,
  "error": "Missing API key"
}
{
  "success": false,
  "error": "Supplier not found or already inactive"
}

Code Examples

Shell Command 
curl -X DELETE "https://developer.traceallglobal.com/api/v1/suppliers/456" \
  -H "X-API-Key: YOUR_API_KEY"
JavaScript Code 
fetch('https://developer.traceallglobal.com/api/v1/suppliers/456', {
  method: 'DELETE',
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(data => console.log(data));
Python Code 
import requests

response = requests.delete(
    'https://developer.traceallglobal.com/api/v1/suppliers/456',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
print(response.json())
PHP Code 
<?php
$supplierid = 456;
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://developer.traceallglobal.com/api/v1/suppliers/$supplierid",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['X-API-Key: YOUR_API_KEY'],
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);
print_r($result);
?>