⚙️ Introduction

This job is designed to create and update Accounts and their shipping/billing 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 addresses within DJUST platform.

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

Payload structure example

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

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",
    "address":[
       {
          "addressExternalId":"ADDR54321",
          "addressFullName":"Jane Smith",
          "addressCountry":"Canada",
          "addressCity":"Toronto",
          "addressZipCode":"M5H 2N2",
          "addressStreetName":"456 Queen St W",
          "unlinkAddress":"false",
  				"shippingAddress":"true",
  				"billingAddress":"true"
       },
       {
          "addressExternalId":"ADDR98765",
          "addressFullName":"Robert Smith",
          "addressCountry":"USA",
          "addressCity":"San Francisco",
          "addressZipCode":"94103",
          "addressStreetName":"789 Market St",
        	"unlinkAddress":"false",
  					"shippingAddress":"true",
  				"billingAddress":"false"
       }
    ]
 },
 {
    "accountName":"John",
    "accountManagerName":"Smith",
    "accountWebsite": "string",
    "accountExternalId":"09876543561",
    "customerTagExternalId": "string",
    "accountVatNumber": "string",
    "companyRegistrationName":"Bertrand & Co. LLC",
    "businessRegistrationNumber":"GRU987654321",
    "address":[
       {
          "addressExternalId":"ADDR9999",
          "addressFullName":"John Doe",
          "addressCountry":"USA",
          "addressCity":"NY",
          "addressZipCode":"M5H 2N2",
          "addressStreetName":"54 Queen St W",
          "unlinkAddress":"false",
          "shippingAddress":"true",
  				"billingAddress":"true"
       },
       {
          "addressExternalId":"ADDR98765",
          "addressFullName":"Robert Smith",
          "addressCountry":"USA",
          "addressCity":"San Francisco",
          "addressZipCode":"94103",
          "addressStreetName":"789 Market St",
          "unlinkAddress":"false",
          "shippingAddress":"true",
  				"billingAddress":"true"
       }
    ]
 }
]

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",
    "unlinkAddress":"false",
  	"shippingAddress":"true",
  	"billingAddress":"true"
 },
 {
    "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",
    "unlinkAddress":"false",
    "shippingAddress":"true",
    "billingAddress":"false"
 }
]

📋 Fields

Field	Definition	Required on creation	Required on update	Default value
`Account Name`	Account name	✅
`Account Manager Name`	Account manager name
`Account External Id`	Unique external identifier	✅	✅
`Account Website`	Website URL
`Company Registration Name`	Registered company name	✅
`Business Registration Number`	Business registration number	✅
`Customer Tag External Id`	External customer tag ID
`Account Vat Number`	VAT number of the Account
`Deleted`	Deletes the Account			`FALSE`
`Inactive`	Deactivates the Account			`FALSE`
`Address External Id`	External identifier of the address	✅	☑️ (Only required when updating the Address)
`Address Full Name`	Full name associated with the address	✅
`Address Country`	Country of the address	✅
`Address City`	City of the address	✅
`Address Zip Code`	Zip code of the shipping address	✅
`Address Street Name`	Street name of the shipping address	✅
`Address Label`	Label for identifying the address
`Address Additional Street Name`	Additional information about the address
`Address Phone Number`	Phone number associated with the address
`Unlink Address from Account`	Boolean to unlink an address from an Account			`FALSE`
`Shipping Address`	Boolean to define an address as a shipping address			`TRUE`
`Billing Address`	Boolean to define an address as a billing address			`TRUE`

☑️ Conditionally required

🔗 Data Mapping

The way you map the data may vary depending on how the shipping/billing addresses are sent.

Shipping/Billing addresses as a list of objects

When mapping Accounts that include nested data structures (such as the addresses), 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",
  "address":[
     {
        "addressExternalId":"ADDR54321",
        "addressFullName":"Jane Smith",
        "addressCountry":"Canada",
        "addressCity":"Toronto",
        "addressZipCode":"M5H 2N2",
        "addressStreetName":"456 Queen St W",
        "unlinkAddress":"false",
				"shippingAddress":"true",
        "billingAddress":"true"
     }
  ]
}
]

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",
  "unlinkAddress":"false",
  "shippingAddress":"true",
  "billingAddress":"true"
}
]

⚠️
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 addresses.
By default, an address will defined as shipping and billing address.
An address can be unlinked from the Account
An address can be associated with multiple Accounts. In this case, you still have to provided all the mandatory information related to the address and not only its Address External Id
It is not possible to update an existing address that is already associated with another Account while simultaneously linking it to this new Account
It is not possible to update the Account External Id and the Address External Id
Empty fields in standard columns do not delete the recorded values
Empty fields in Custom Fields delete the recorded values

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