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.

Attribute

Type

Comment

internalID

string - compulsory

Unique identifier for a supplier. Generated by you, you must ensure that you provide a unique and persistent ID for each one of your suppliers.

name

string - compulsory

The 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.

Attribute

Type

Comment

sirens

array of strings

the SIREN identification number of your supplier.

Note: import the SIREN without any blank (e.g. import 123456789, not 123 456 789)

vatNumbers

array of strings

The "VAT identification number" / "numéro de TVA intracommunautaire" of your supplier.

glns

array of strings

The 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:

Attribute

Type

Comment

supplierIDs

array of strings - optional

If you use another kind of supplier ID in addition to the unicity key internalID.

any kind of supplier ID you use in your systems.

wave

string - optional

free text that can for example be used to segment your suppliers in several onboarding waves.

supplyChains

array of strings - optional

an 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] emails

array 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.

Attribute

Type

Comment

emailAddress

string - compulsory

email 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.

firstName

string - optional

First Name of the contact

lastName

string - optional

Last Name of the contact

jobTitle

string - optional

Job title of the contact

phoneNumber

string - optional

Phone number / Main phone number

mobileNumber

string - optional

Mobile 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.

Attribute

Type

Comment

isArchived

boolean - optional

true: 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 type

Message

Description

Action

XLSX + JSON

Missing key: <name_key>

The supplier has a mandatory field missing: <name_key>.

Fill it and re-import the file.

XLSX + JSON

Invalid 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 + JSON

Invalid data {} does not belong to the available attribute

A 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 + JSON

Invalid data <name_field>. <error_msg>

A dynamic field cannot be casted. This is a type error, for example a string instead of an integer

Correct the value accordingly

XLSX + JSON

Invalid data <name_field>. {} is not a valid date expected format YYYY-MM-DD

a date field does not have the good format. This is a “cast” error.

Correct the value accordingly

XLSX + JSON

The token is not yet valid (nbf)

Technical problem caused by a desynchronization between the services clocks

Contact support

XLSX + JSON

Invalid attribute in contact: <name_field> is not allowed

with <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 + JSON

Invalid contact data, <name_field> is mandatory

One of the supplier contacts does not have a mandatory field.

Check which contacts of this supplier and fill the mandatory field value.

JSON

Missing root key suppliers

The key suppliers is mandatory when importing a JSON.

Add the rootkey suppliers

JSON

root key suppliers must be a list

The key suppliers does not contain a list as value.

Check the rootkey suppliers

JSON

JSONDecodeError('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

JSON

JSONDecodeError('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

XLSX

Invalid 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 sheet

Check that every contact has a corresponding row in the Suppliers sheet, with the same internalId

XLSX

KeyError('Worksheet Suppliers does not exist.')

Missing the worksheet Suppliers.

Add the Supplier sheet

XLSX

Invalid 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: