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 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!
Attribute | Format | Type | Description |
|---|---|---|---|
sirens | 9 digits 000000000 | array of strings | The SIREN identification number of your supplier |
vatNumbers | 2 letters then 11 digits AA00000000000 | array of strings | The VAT identification number of your supplier |
glns | 13 digits 0000000000000 | array of strings | The GLN code of your supplier |
eins | 2 digits, 1 hyphen then 7 digits 00-0000000 | array of strings | The Employer ID Number of your supplier (USA) |
dunsNumbers | 9 digits 000000000 | array of strings | The DUNS number of your supplier |
abn | 11 digits 00000000000 | array of strings | The Australian Business Number of your supplier |
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:
Attribute | Type | Comment |
|---|---|---|
supplierClassificationTextList | array of strings - optional | free text that can for example be used to segment your suppliers in several group depending on their industry, their localisation or the buyers team managing them. This value can be filtered in the Supplier Directory interface |
wave | string - optional | free text that can for example be used to segment your suppliers in several onboarding waves. This value can be filtered in the Supplier Directory interface |
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. |
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. |
[Deprecated] emails | array of strings - optional | [Deprecated] email contact from the supplier.
|
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
|
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: <field>. Expected <correct_type_field> got <wrong_type_field> | The field <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 | 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 | 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 | 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. |
XLSX + JSON | Invalid contact data, | 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 | 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: | Global error. It means that there is at least one mandatory column missing in the sheet. | Check the columns |
Updated 9 days ago
These sections document all the endpoints that allow interaction with the Supplier Directory: