Understanding the Supplier Directory

This page details how the supplier directory is handled on SupplierXM and how it is handled by the APIs.

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.

AttributeTypeComment
internalIDstring - compulsoryUnique identifier for a supplier. Generated by you, you must ensure that you provide a unique and persistent ID for each one of your suppliers.
namestring - compulsoryThe name of your supplier.

Recommended attributes: reconciliation keys

These reconciliation keys attributes are multi-valued and therefore must be lists even if there is only one value to inform.

AttributeTypeComment
sirensarray of stringsthe SIREN identification number of your supplier.

Note: import the SIREN without any blank (e.g. import 123456789, not 123 456 789)
vatNumbersarray of stringsThe "VAT identification number" / "numéro de TVA intracommunautaire" of your supplier.
glnsarray of stringsThe GLN codes of your supplier.

🚧

Reconciliation keys

We strongly advise filling in at least one of these attributes for each supplier in order to increase the chances of matching suggestions.

SIRENs and VAT Numbers are used as keys for the 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:

AttributeTypeComment
supplierIDsarray of strings - optionalIf you use another kind of supplier ID in addition to the unicity key internalID.

any kind of supplier ID you use in your systems.
wavestring - optionalfree text that can for example be used to segment your suppliers in several onboarding waves.
supplyChainsarray of strings - optionalan exemple of the referentials you can add to your supplier directory: values that you can define for each supplier. Once a supplier will be reconciled with a SupplierXM account, the supplier will have this list of allowed values while filling the product data.
[Deprecated] emailsarray of strings - optional[Deprecated] email contact from the supplier.
emails are now integrated as emailAddress into the contacts object.

Optional attributes: contacts

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

AttributeTypeComment
emailAddressstring - compulsoryemail address of your contact. A contact must have at least this info filled.

the pair supplier internalID + contact emailAddress acts as a unicity key: you can have only 1 occurence of an email address for 1 same supplier.
firstNamestring - optionalFirst Name of the contact
lastNamestring - optionalLast Name of the contact
jobTitlestring - optionalJob title of the contact
phoneNumberstring - optionalPhone number / Main phone number
mobileNumberstring - optionalMobile phone number / secondary phone number

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.

AttributeTypeComment
isArchivedboolean - optionaltrue: archives the supplier
false: displays the supplier

- false by default, if the attribute is missing in the payload.

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

Import typeMessageDescriptionAction
XLSX + JSONMissing key: <name_key>The supplier has a mandatory field missing: <name_key>.Fill it and re-import the file.
XLSX + JSONInvalid type for key: . Expected <correct_type_field> got <wrong_type_field>The field is not filled properly.Change the type of this field to the one precised in the message: <correct_type_field>.
XLSX + JSONInvalid data {} does not belong to the available attributeA dynamic field is in the payload but this field is not available or not created for this organization.Check the columns and their "attributes" names.
XLSX + JSONInvalid data <name_field>. <error_msg>A dynamic field cannot be casted. This is a type error, for example a string instead of an integerCorrect the value accordingly
XLSX + JSONInvalid data <name_field>. {} is not a valid date expected format YYYY-MM-DDa date field does not have the good format. This is a “cast” error.Correct the value accordingly
XLSX + JSONThe token is not yet valid (nbf)Technical problem caused by a desynchronization between the services clocksContact support
XLSX + JSONInvalid attribute in contact: <name_field> is not allowedwith <name_field> the name of the field which should not be a contact field. Field name in contacts not allowed"XLSX: remove the column and re-import the file.
JSON: emove the key not allowed and re-import."
XLSX + JSONInvalid contact data, <name_field> is mandatoryOne of the supplier contacts does not have a mandatory field.Check which contacts of this supplier and fill the mandatory field value.
JSONMissing root key suppliersThe key suppliers is mandatory when importing a JSON.Add the rootkey suppliers
JSONroot key suppliers must be a listThe key suppliers does not contain a list as value.Check the rootkey suppliers
JSONJSONDecodeError('Expecting property % enclosed in double quotes:)The imported JSON is not well formatted.Check your file for example with a tool like the JSONFormatter online to correct the file
JSONJSONDecodeError('Extra data: line 1 column 3 (char 2)',)The imported JSON is not well formatted.Check your file for example with a tool like the JSONFormatter online to correct the file
XLSXInvalid data internalId, it is present in the Contacts sheet but has no reference in the Suppliers sheet.An internalId in the Contacts sheet cannot be found in the Suppliers sheetCheck that every contact has a corresponding row in the Suppliers sheet, with the same internalId
XLSXKeyError('Worksheet Suppliers does not exist.')Missing the worksheet Suppliers.Add the Supplier sheet
XLSXInvalid file, mandatory columns are missing: <list_columns_missing>Global error. It means that there is at least one mandatory column missing in the sheet.Check the columns

What’s Next

These sections document all the endpoints that allow interaction with the Supplier Directory: