Understanding the Supplier Directory

The supplier directory enables retailers to import and manage their suppliers.

These suppliers will automatically be reconciled with corresponding SupplierXM manufacturer accounts depending on pre-etablished criteria (SIREN number, VAT Number and/or GLN) called reconciliation keys.

As a retailer with the supplier directory feature, you will have access to a JSON route allowing you to import your suppliers. See API reference Supplier section for more details.

Import format

The import payload must respect standard JSON format, which applied to supplier directory data will look like:

{
    "suppliers": [
        {
            "internalID": "Unique supplierID 1",
            "name": "The first Supplier's Name",
            "sirens": ["123456789"],
            "vatNumbers": ["FR01123456789"]
        },
      	{
            "internalID": "Unique supplierID 2",
            "name": "The Second Supplier's Name",
            "sirens": ["111222333", "222333444"],
            "vatNumbers": ["FRAA111222333", "FRAA222333444"],
            "wave": "onboarding wave 1"
        }
    ]
}

Another example with contacts included. The 2 contacts of the first supplier include all contact info, while the 2 contacts of the second supplier include only the mandatory contact info (emailAddress):

{
  "suppliers": [
    {
      "internalID": "ret301",
      "name": "MySupplier1",
      "sirens": ["525255931"],
      "supplierIDs": ["123456"],
      "supplyChains": ["filieremanuf1-1", "filieremanuf1-2", "filieremanuf1-3"],
      "vatNumbers": ["FR89525255931"],
      "wave": "wave1",
      "isArchived": false,
      "contacts":[
        {
          "emailAddress": "SupplierContact.ret301.1",
          "firstName":"Bastien",
          "lastName":"Testalk",
          "jobTitle":"Sourcing Mgr",
          "phoneNumber":"0612334455",
          "mobileNumber":"0755667788"
        },
        {
          "emailAddress": "SupplierContact.ret301.2",
          "firstName":"Lee",
          "lastName":"Long",
          "jobTitle":"Long job title",
          "phoneNumber":"0600101112",
          "mobileNumber":"0743101112"
        }
      ]
    },
    {
      "internalID": "ret302",
      "name": "MySupplier2",
      "contacts":[
        {
          "emailAddress": "[email protected]"
        },
        {
          "emailAddress": "[email protected]"
        }
      ]
    }
  ]
}

The root attribute suppliers must not be changed.

📘

About recommended and optional attributes

Note that you may have other reconciliation keys and custom attributes available that the ones detailed in this template.
Please refer to the specifications we sent you to get the exhaustive list of allowed attributes.

Mandatory attributes

These attributes are mandatory and must be filled with proper data.
An error will be raised if one of them is missing and the erroneous suppliers won’t be integrated.

Recommended attributes: reconciliation keys

These reconciliation key attributes are multi-valued and therefore must be of type "list" in a JSON payload even if there is only one value to fill.

For these keys to match what suppliers fill on their SupplierXM accounts, you must respect exactly the format for each key.

Ask your Salsify contacts what keys could be the more useful for you!

🚧

Reconciliation keys

We advise filling in as many attributes as possible for each of your suppliers.

These keys are used to suggest reconciliation between your suppliers' referential and the accounts already on SupplierXM. If you don't import reconciliation keys, you will have to match your suppliers manually with only their names to verify matches between your supplier and SupplierXM organizations.

Optional attributes: custom data

Examples of optional attributes that SupplierXM can receive:

Optional attributes: contacts

Several contacts can be attached to a supplier.
The only mandatory attribute of a contact object is the emailAddress.

Note that you may not need to import optional data at all: the exact list of attributes is defined between you and SupplierXM during the implementation phase according to what kind of info is relevant for you.

📘

Omitting optional attributes

Optional attributes are not mandatory and can be omitted: if not given, it will not update the data on the SupplierXM system and will keep the data as it was previously.

Update and Delete attributes

You can update, replace, delete attributes from a supplier.

If you want to delete some existing values or if you need to import an empty attribute, you can use these standard JSON formats below.

The example shows how to delete data attached to a basic attribute, and a list attribute (when you have multiple values for an attribute)

{
    "suppliers": [
        {
            "internalID": "Unique supplierID 1",
            "name": "The first Supplier's Name",
          	"basicAttribute": "",
            "listAttribute": []
        }
    ]
}

Archive suppliers

You cannot delete a supplier from the Directory.
You can archive a supplier in the Directory.

Archiving a supplier will hide it from your supplier list without breaking reconciliation or deleting any other value so that the archive is reversible.

Maximum import size & API calls

Maximum number of suppliers imported per day: 10000
Maximum number of contacts imported per day: 10000

Maximum size of the body payload for API calls: 10Mo

It is strongly recommended to make batches of your payload in one call (or a few), rather than make one call for each supplier.
Making one call for several suppliers will ease your platform import dashboard readability and the management of the error report files.

Troubleshooting

Import error messages