⚙️ Introduction

This job is designed to create and update Accounts and their Shipping Addresses by connecting your API gateway to DJUST using the API Connector. It processes data sent in JSON format from a REST API.

📂 Accepted Payload Structure

The accepted payload format specifies the structure required for successful data transmission through the API Connector. Ensuring the payload adheres to this format guarantees efficient integration of Accounts and their Shipping Addresses within DJUST platform.

There are two possible structures depending on how the Shipping Address is sent. Regardless of the structure, the JSON must always be a list of objects.

Payload structure example

  [
    //object 1
  	\{
  	},
    //object 2
  	\{
  	},
    etc.
  ]

Shipping Address sent in a list of objects

[
 {
    "accountName":"Smith",
    "accountManagerName":"Smith",
    "accountWebsite": "string",
    "accountExternalId":"0987654321",
    "customerTagExternalId": "string",
    "accountVatNumber": "string",
    "companyRegistrationName":"Smith & Co. LLC",
    "businessRegistrationNumber":"BRN987654321",
    "deleted": "false",
    "inactive": "false",
    "shippingAddress":[
       {
          "addressExternalId":"ADDR54321",
          "addressFullName":"Jane Smith",
          "addressCountry":"Canada",
          "addressCity":"Toronto",
          "addressZipCode":"M5H 2N2",
          "addressStreetName":"456 Queen St W"
       },
       {
          "addressExternalId":"ADDR98765",
          "addressFullName":"Robert Smith",
          "addressCountry":"USA",
          "addressCity":"San Francisco",
          "addressZipCode":"94103",
          "addressStreetName":"789 Market St"
       }
    ]
 },
 {
    "accountName":"John",
    "accountManagerName":"Smith",
    "accountWebsite": "string",
    "accountExternalId":"09876543561",
    "customerTagExternalId": "string",
    "accountVatNumber": "string",
    "companyRegistrationName":"Bertrand & Co. LLC",
    "businessRegistrationNumber":"GRU987654321",
    "shippingAddress":[
       {
          "addressExternalId":"ADDR9999",
          "addressFullName":"John Doe",
          "addressCountry":"USA",
          "addressCity":"NY",
          "addressZipCode":"M5H 2N2",
          "addressStreetName":"54 Queen St W"
       },
       {
          "addressExternalId":"ADDR98765",
          "addressFullName":"Robert Smith",
          "addressCountry":"USA",
          "addressCity":"San Francisco",
          "addressZipCode":"94103",
          "addressStreetName":"789 Market St"
       }
    ]
 }
]

Shipping Address sent with flat object structure

[
 {
    "accountName":"Smith",
    "accountManagerName":"Smith",
    "accountWebsite": "string",
    "accountExternalId":"0987654321",
    "customerTagExternalId": "string",
    "accountVatNumber": "string",
    "companyRegistrationName":"Smith & Co. LLC",
    "businessRegistrationNumber":"BRN987654321",
    "deleted": "false",
    "inactive": "false",
    "addressExternalId":"ADDR54321",
    "addressFullName":"Jane Smith",
    "addressCountry":"Canada",
    "addressCity":"Toronto",
    "addressZipCode":"M5H 2N2",
    "addressStreetName":"456 Queen St W"
 },
 {
    "accountName":"John",
    "accountManagerName":"Smith",
    "accountWebsite": "string",
    "accountExternalId":"09876543561",
    "customerTagExternalId": "string",
    "accountVatNumber": "string",
    "companyRegistrationName":"John & Co. LLC",
    "businessRegistrationNumber":"GRU987654321",
    "addressExternalId":"ADDR9999",
    "addressFullName":"John Doe",
    "addressCountry":"USA",
    "addressCity":"NY",
    "addressZipCode":"M5H 2N2",
    "addressStreetName":"54 Queen St W"
 }
]

📋 Fields

Field	Definition	Required on creation	Required on update	Editable	Default value
`accountName`	Account name	✅		✅
`accountManagerName`	Account manager name			✅
`accountExternalId`	Unique external identifier	✅	✅
`accountWebsite`	Website URL			✅
`companyRegistrationName`	Registered company name	✅		✅
`businessRegistrationNumber`	Business registration number	✅		✅
`customerTagExternalId`	External customer tag ID			✅
`accountVatNumber`	VAT number of the Account			✅
`deleted`	Deletes the Account			✅	`FALSE`
`inactive`	Deactivates the Account			✅	`FALSE`
`addressExternalId`	External identifier of the shipping address	✅	☑️ (Only required when updating the Shipping Address)
`addressFullName`	Full name associated with the shipping address	✅		✅
`addressCountry`	Country of the shipping address	✅		✅
`addressCity`	City of the shipping address	✅		✅
`addressZipCode`	Zip code of the shipping address	✅		✅
`addressStreetName`	Street name of the shipping address	✅		✅
`addressLabel`	Label for identifying the shipping address			✅
`addressAdditionalStreetName`	Additional information about the shipping address			✅
`addressPhoneNumber`	Phone number associated with the shipping address			✅

✅ Required ☑️ Conditionally required

🔗 Data Mapping

The way you map the data may vary depending on how the Shipping Addresses are sent.

Shipping Addresses as a list of objects

When mapping Accounts that include nested data structures (such as Shipping Address), it is essential to map the parent parameter (representing the array of objects) first before mapping the fields within each object inside the array.

[
{
  "accountName":"Smith",
  "accountExternalId":"0987654321",
  "companyRegistrationName":"Smith & Co. LLC",
  "businessRegistrationNumber":"BRN987654321",
  "shippingAddress":[
     {
        "addressExternalId":"ADDR54321",
        "addressFullName":"Jane Smith",
        "addressCountry":"Canada",
        "addressCity":"Toronto",
        "addressZipCode":"M5H 2N2",
        "addressStreetName":"456 Queen St W"
     }
  ]
}
]

Accounts with flat object structures

When mapping Accounts where the data is structured as a flat list of objects, each object in the array contains both account information and address attributes at the same level. In this format, the mapping approach differs from nested data structures

[
{
  "accountName":"Smith",
  "accountManagerName":"Smith",
  "accountWebsite": "string",
  "accountExternalId":"0987654321",
  "customerTagExternalId": "string",
  "accountVatNumber": "string",
  "companyRegistrationName":"Smith & Co. LLC",
  "businessRegistrationNumber":"BRN987654321",
  "deleted": "false",
  "inactive": "false",
  "addressExternalId":"ADDR54321",
  "addressFullName":"Jane Smith",
  "addressCountry":"Canada",
  "addressCity":"Toronto",
  "addressZipCode":"M5H 2N2",
  "addressStreetName":"456 Queen St W"
}
]

⚠️
Required Custom Fields
Custom Fields that are required on DJUST must be provided in the API response

🧠 Key Business Rules & Notes

An Account can have one or more Shipping Addresses
A Shipping Address can be associated with multiple Accounts. In this case, you still have to provided all the mandatory information related to the Shipping Address and not only its addressExternalId
It is not possible to import a Billing Address
It is not possible to update an existing Address that is already associated with another Account while simultaneously linking it to this new Account
Empty fields in standard columns do not delete the recorded values
Empty fields in Custom Fields delete the recorded values

📌
Best Practices
✔️ Map the Shipping Address correctly based on its structure
✔️ Map the required Custom Fields
✔️ Follow data formatting guidelines for optimal import results