Overview

Suppliers on the SMS represent organisations that you can allocate spending to in the Procurement Scorecards. To make it super-easy to work with suppliers using the API, you will be able to use your own unique supplier codes when creating, updating or reading a suppliers details and even when doing other activities via the API such as loading procurement scorecards.

The **following** actions are available for the Supplier API:

Heart Beat

Typical JSON response:

{account: "Widgets Cape Town"}

Typical XML response:

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<account>Widgets Cape Town</account>

</hash>

View Supplier

 Typical response:

{

  black_person_with_disability: "false",

  cost_centre: "",

  custom_1: "",

  custom_2: "",

  custom_3: "",

  custom_4: "",

  designated_group_supplier: "false",

  primary_email: "",

  empowering_supplier: "false",

  enterprise_development_recipient: "false",

  exclude_from_procurement_calculations: "false",

  fax_number: "",

  first_time_supplier: "false",

  greater_than_five_percent_equity_by_black_individuals: "false",

  minimum_three_year_contract: "false",

  postal_address: "",

  property_service_provider: "false",

  province: "",

  recipient_of_supplier_development_contributions: "false",

  registered_name: "",

  registration_number: "",

  street_address: "",

  telephone_number: "",

  town: "Cape Town",

  trading_name: "African Widgets - Cape Town",

  vat_number: "1234567890",

  vendor_code: "BEE001",

  website: "",

  created_at: "04/03/2011 13:24:00",

  updated_at: "11/07/2011 09:11:31"

}

Create Supplier

Typical JSON request:

{

  "supplier": {

    "trading_name": "African Widgets - Durban",

    "vendor_code": "BEE003",

    "registered_name": "African Widgets Durban (Pty) Ltd",

    "registration_number": "12345678",

    "vat_number": "1234567890",

    "cost_centre": "Durban North",

    "website": "www.african-widgets.com",

    "primary_email": "test-person@example.com",

    "street_address": "1 Aloe Way",

    "postal_address": "1 Aloe Way",

    "town": "Durban",

    "telephone_number": "",

    "fax_number": "",

    "exclude_from_procurement_calculations": "true",

    "enterprise_development_recipient": "true",

    "black_person_with_disability": "true",

    "property_service_provider": "true",

    "greater_than_five_percent_equity_by_black_individuals": "true",

    "empowering_supplier": "true",

    "minimum_three_year_contract": "true",

    "recipient_of_supplier_development_contributions": "true",

    "first_time_supplier": "true",

    "designated_group_supplier": "true",

    "custom_1": "African Custom 1",

    "custom_2": "",

    "custom_3": "",

    "custom_4": ""

  }

}

Typical successful JSON response:

{

  black_person_with_disability: "true",

  cost_centre: "Durban North",

  custom_1: "African Custom 1",

  custom_2: "",

  custom_3: "",

  custom_4: "",

  designated_group_supplier: "true",

  primary_email: "test-person@example.com",

  empowering_supplier: "true",

  enterprise_development_recipient: "true",

  exclude_from_procurement_calculations: "true",

  fax_number: "",

  first_time_supplier: "true",

  greater_than_five_percent_equity_by_black_individuals: "true",

  minimum_three_year_contract: "true",

  postal_address: "1 Aloe Way",

  property_service_provider: "true",

  province: "",

  recipient_of_supplier_development_contributions: "true",

  registered_name: "African Widgets Durban (Pty) Ltd",

  registration_number: "12345678",

  street_address: "1 Aloe Way",

  telephone_number: "",

  town: "Durban",

  trading_name: "African Widgets - Durban",

  vat_number: "1234567890",

  vendor_code: "BEE003",

  website: "www.african-widgets.com",

  created_at: "03/10/2014 09:21:12",

  updated_at: "03/10/2014 09:21:12"

}

Typical failed JSON response:

{

  errors: [

    "'trading_name' can't be blank"

    "'vat_number' must be a valid vat number"

  ]

}

Typical XML request:

<?xml version="1.0"?>

<supplier>

  <trading_name>African Widgets - Durban</trading_name>

  <vendor_code>BEE004</vendor_code>

  <registered_name>African Widgets Durban (Pty) Ltd</registered_name>

  <registration_number>12345678</registration_number>

  <vat_number>1234567890</vat_number>

  <cost_centre>Durban North</cost_centre>

  <website>www.african-widgets.com</website>

  <primary_email>test-person@example.com</primary_email>

  <street_address>1 Aloe Way</street_address>

  <postal_address>1 Aloe Way</postal_address>

  <town>Durban</town>

  <telephone_number></telephone_number>

  <fax_number></fax_number>

  <exclude_from_procurement_calculations>true</exclude_from_procurement_calculations>

  <enterprise_development_recipient>true</enterprise_development_recipient>

  <black_person_with_disability>true</black_person_with_disability>

  <property_service_provider>true</property_service_provider>

  <greater_than_five_percent_equity_by_black_individuals>true

    </greater_than_five_percent_equity_by_black_individuals>

  <empowering_supplier>true</empowering_supplier>

  <minimum_three_year_contract>true</minimum_three_year_contract>

  <recipient_of_supplier_development_contributions>true

    </recipient_of_supplier_development_contributions>

  <first_time_supplier>true</first_time_supplier>

  <designated_group_supplier>true</designated_group_supplier>

  <custom_1>African Custom 1</custom_1>

  <custom_2></custom_2>

  <custom_3></custom_3>

  <custom_4></custom_4>

</supplier>

Typical successful XML response

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<black-person-with-disability>true</black-person-with-disability>

<cost-centre>Durban North</cost-centre>

<custom-1>African Custom 1</custom-1>

<custom-2></custom-2>

<custom-3></custom-3>

<custom-4></custom-4>

<designated-group-supplier>true</designated-group-supplier>

<primary-email>test-person@example.com</primary-email>

<empowering-supplier>true</empowering-supplier>

<enterprise-development-recipient>true</enterprise-development-recipient>

<exclude-from-procurement-calculations>true</exclude-from-procurement-calculations>

<fax-number></fax-number>

<first-time-supplier>true</first-time-supplier>

<greater-than-five-percent-equity-by-black-individuals>true</greater-than-five-percent-equity-by-black-individuals>

<minimum-three-year-contract>true</minimum-three-year-contract>

<postal-address>1 Aloe Way</postal-address>

<property-service-provider>true</property-service-provider>

<province></province>

<recipient-of-supplier-development-contributions>true</recipient-of-supplier-development-contributions>

<registered-name>African Widgets Durban (Pty) Ltd</registered-name>

<registration-number>12345678</registration-number>

<street-address>1 Aloe Way</street-address>

<telephone-number></telephone-number>

<town>Durban</town>

<trading-name>African Widgets - Durban</trading-name>

<vat-number>1234567890</vat-number>

<vendor-code>BEE004</vendor-code>

<website>www.african-widgets.com</website>

<created-at>08/10/2014 10:42:03</created-at>

<updated-at>08/10/2014 10:42:03</updated-at>

</hash>

Typical failed XML response:

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<errors type="array">

<error>'trading_name' can't be blank</error>

<error>'vat_number' must be a valid vat number</error>

</errors>

</hash>

Update Supplier

Typical JSON request:

{

  "supplier": {

    "postal_address": "PO Box 555",

    "exclude_from_procurement_calculations": "false",

    "enterprise_development_recipient": "false",

    "custom_2": "Johnnys client"

  }

}

Typical successful JSON response:

{

  black_person_with_disability: "true",

  cost_centre: "Durban North",

  custom_1: "African Custom 1",

  custom_2: "Johnnys client",

  custom_3: "",

  custom_4: "",

  designated_group_supplier: "true",

  primary_email: "test-person@example.com",

  empowering_supplier: "true",

  enterprise_development_recipient: "false",

  exclude_from_procurement_calculations: "false",

  fax_number: "",

  first_time_supplier: "true",

  greater_than_five_percent_equity_by_black_individuals: "true",

  minimum_three_year_contract: "true",

  postal_address: "PO Box 555",

  property_service_provider: "true",

  province: "",

  recipient_of_supplier_development_contributions: "true",

  registered_name: "African Widgets Durban (Pty) Ltd",

  registration_number: "12345678",

  street_address: "1 Aloe Way",

  telephone_number: "",

  town: "Durban",

  trading_name: "African Widgets - Durban",

  vat_number: "1234567890",

  vendor_code: "BEE003",

  website: "www.african-widgets.com",

  created_at: "03/10/2014 09:21:12",

  updated_at: "03/10/2014 09:21:12"

}

Typical failed JSON response:

{

  errors: [

    "'trading_name' can't be blank"

    "'vat_number' must be a valid vat number"

  ]

}

Typical XML request:

<?xml version="1.0"?>

<supplier>

  <postal_address>PO Box 555</postal_address>

  <exclude_from_procurement_calculations>false</exclude_from_procurement_calculations>

  <enterprise_development_recipient>false</enterprise_development_recipient>

  <custom_2>Johnnys client</custom_2>

</supplier>

Typical successful XML response:

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<black-person-with-disability>false</black-person-with-disability>

<cost-centre>Durban North</cost-centre>

<custom-1>African Custom 1</custom-1>

<custom-2>Johnnys client</custom-2>

<custom-3></custom-3>

<custom-4></custom-4>

<designated-group-supplier>false</designated-group-supplier>

<primary-email>test-person@example.com</primary-email>

<empowering-supplier>false</empowering-supplier>

<enterprise-development-recipient>false</enterprise-development-recipient>

<exclude-from-procurement-calculations>false</exclude-from-procurement-calculations>

<fax-number></fax-number>

<first-time-supplier>false</first-time-supplier>

<greater-than-five-percent-equity-by-black-individuals>false</greater-than-five-percent-equity-by-black-individuals>

<minimum-three-year-contract>false</minimum-three-year-contract>

<postal-address>PO Box 555</postal-address>

<property-service-provider>false</property-service-provider>

<province></province>

<recipient-of-supplier-development-contributions>false</recipient-of-supplier-development-contributions>

<registered-name>African Widgets Durban (Pty) Ltd</registered-name>

<registration-number>12345678</registration-number>

<street-address>1 Aloe Way</street-address>

<telephone-number></telephone-number>

<town>Durban</town>

<trading-name>African Widgets - Durban</trading-name>

<vat-number>1234567890</vat-number>

<vendor-code>BEE004</vendor-code>

<website>www.african-widgets.com</website>

<created-at>08/10/2014 10:42:03</created-at>

<updated-at>08/10/2014 11:10:31</updated-at>

</hash>

Typical failed XML response:

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<errors type="array">

<error>'trading_name' can't be blank</error>

<error>'vat_number' must be a valid vat number</error>

</errors>

</hash>

Delete Supplier

Typical successful response: 

No content for a deleted resource

Typical failed JSON response:

{

  errors: "Supplier not found"

}

Typical failed XML response:

<?xml version="1.0" encoding="UTF-8"?>

<hash>

<errors>Supplier not found</errors>

</hash>

Supplier Read Fields

Note that all fields will be returned as strings, even fields of date or boolean data types.

Supplier Write Fields