Contact and Address relationships

Less than 10 minutes to read

Overview

This document provides guidance on the relationships formed between contacts and addresses in Sage Business Cloud Accounting and how the API can be used to create, edit and return contacts and addresses.

Creating a Customer or Vendor

When creating a customer or vendor/supplier in the web app or via the API /contacts endpoint, an entity is created with the following attributes.

id - System generated GUID.
name - The Name of the contact.
reference - A unique user derived reference to aid identification in the UI.
default_sales_ledger_account - Defines the default ledger account of the customer contact.
default_purchase_ledger_account - Defines the default ledger account of the vendor contact.
tax_number - Used to store the businesses VAT and Tax numbers.
notes - Free text to add notes relating to the business or contact.
main_address - The main address of the business.
delivery_address - The business delivery address, on customers only.
main_contact_person - The main contact person.
bank_account_details - The business bank account details.
credit_limit - The credit limit you or your vendor wish to allow the business. This is for reference and does not act as a hard stop.
credit_days - The number of credit days you or a supplier are willing to allow the business to pay.
currency - Available on businesses with multi currency enabled. Denotes the currency the business will deal in.
aux_reference - Used for Germany only to define ‘Kreditorennummer’ and ‘Debitorennummer’.
registered_number - Used for Germany only to define ‘Steuernummer’.
deletable - Boolean denoting if the contact record can be deleted.
tax_treatment - Denotes the tax treatment of the contact.
email - The email address of the contact.
tax_calculation - Used for French and Spanish vendor contacts to define VAT scheme used for France or if ‘Receargo d’equivalencia’ is applicable in Spain.
gdpr_obfuscated - EU regions can obfuscate contact data if a contact requests.

POST /contacts
Content-Type: application/json

{
  "contact": {
    "contact_type_ids": ["CUSTOMER"],
    "name": "Great Example Inc",
    "reference": "GreatExample"
    "main_address": {
      "address_type_id": "ACCOUNTS",
      "address_line_1": "10 Main Street",
      "city": "LA",
      "region": "US-CA",
      "postal_code": "90210",
      "country_group_id": "US"
    }
  }
}

Entities created with a POST request to the /contacts endpoint are created with an immediate association to a main address, and for Sage Business Cloud Accounting businesses, a delivery address (not available in Start). Only customer resources have a delivery address.

{
  // ...
  "main_address": {
    "id": "fe8fdd1df3dd40e3baf12de7770def69",
    "displayed_as": "",
    "$path": "/addresses/fe8fdd1df3dd40e3baf12de7770def69",
    "contact": {
      "id": "0021e863d2d748b0b20837f03e86d37b",
      "displayed_as": "Great Example Inc",
      "$path": "/contacts/0021e863d2d748b0b20837f03e86d37b"
    },
    "address_type": {
      "id": "ACCOUNTS",
      "displayed_as": "Accounts",
      "$path": "/address_types/ACCOUNTS"
    },
    "name": "Main Address",
    "address_line_1": "10 Main Street",
    "address_line_2": null,
    "city": "LA",
    "region": "US-CA",
    "postal_code": "90210",
    "country": {
      "id": "US",
      "displayed_as": "United States (US)",
      "$path": "/countries/US"
    },
    "country_group": {
      "id": "US",
      "displayed_as": "Other",
      "$path": "/country_groups/ALL"
    },
    "is_main_address": true,
    "created_at": "2019-10-22T14:35:30Z",
    "updated_at": "2019-10-22T14:35:30Z"
  },
  "delivery_address": {
    "id": "99248d5d46a6477e98ada0a278fd4f6d",
    "displayed_as": "Delivery Address",
    "$path": "/addresses/99248d5d46a6477e98ada0a278fd4f6d",
    "contact": {
      "id": "0021e863d2d748b0b20837f03e86d37b",
      "displayed_as": "Great Example Inc",
      "$path": "/contacts/0021e863d2d748b0b20837f03e86d37b"
    },
    "address_type": {
      "id": "DELIVERY",
      "displayed_as": "Delivery",
      "$path": "/address_types/DELIVERY"
    },
    "name": "Delivery Address",
    "address_line_1": null,
    "address_line_2": null,
    "city": null,
    "region": null,
    "postal_code": null,
    "country": {
      "id": "US",
      "displayed_as": "United States (US)",
      "$path": "/countries/US"
    },
    // ...
  },
  // ...
}

Creating contact persons

Entities created as contact_persons are not created with a direct relationship to the customer or vendor. Relationships between contacts and contact persons are formed via ‘addresses’. When creating a contact person an address_id must be passed for the contact to be successfully created. It is the relationship with the address which forms the link to the business contact and allows the contact_person to be seen in the UI.

Using the /contact_persons endpoint, additional resources can be created and associated with a business address via a POST request supporting the following attributes.

address_id - The address_id is a required parameter allowing the new contact person to be associated with the required address.
contact_person_type_ids - Specify a contact person type id most suited to the contact from an array [ACCOUNTS, SALES, PURCHASING].
name - The contact’s name.
job_title - The contact’s job title.
telephone - The contact’s telephone number.
mobile - The contact’s mobile number.
email - The contact’s email address.
fax - The contact’s fax number.
is_main_contact - Boolean denoting if the contact is the main contact. Setting this value to true will cause the current main contact to become a contact person.
is_preferred_contact - The contact is the preferred person to contact for the specified address and is the contact used to send customer statements to.

POST /contact_persons
Content-Type: application/json

{
  "contact_person": {
    "address_id": "45870b0b63a44facba19bbe839bf0531",
    "contact_person_type_ids": [
      "PURCHASING"
    ],
    "name": "Stanley Brinks",
    "job_title": "Warehouse manager",
    "telephone": "93124274534",
    "mobile": "0918789467725",
    "email": "[email protected]",
    "fax": "02353624174",
    "is_main_contact": false,
    "is_preferred": true
  }
}

The purpose of setting the is_main_contact Boolean attribute is to allow users to identify via the UI who the main contact person is for a given address. It is not possible to remove the is_main_contact attribute by passing false, the attribute must be set to true on the contact of choice. Setting the attribute to true for a secondary contact does not allow the contact to be returned via the /contact endpoint.

PUT /contact_persons/{id}
Content-Type: application/json

{
  "contact_person": {
    "is_main_contact": true
  }
}

Orphaned contact persons

Due to the relationship of ‘contact_persons’ and addresses, it is possible for ‘contact_persons’ to become orphaned from an address. In the scenario that the ‘contact_persons’ is associated with a deleted contact, the ‘contact_person’ would be returned in a GET request but the associated address would not exist. To ensure you are not returning orphaned ‘contact_persons’ it is advisable to ensure the associated address exists via a GET request to the addresses endpoint.

GET /addresses/{id}

Note - Contact records are only deletable if they have no activity and a zero balance.

Creating a new address

Sage Business Cloud Accounting allows the creation of multiple additional business addresses. A new address can only be created by passing the id of a valid ‘contact’ and not the id of a contact_person. Additional addresses are created via a POST request to the /addresses API endpoint with the following attributes.

address_type_id - Specify an address type from an array of address_type_id applicable to the address [DELIVERY, ACCOUNTS, SALES, PURCHASING].
contact_id - ID of the associated contact.
name - The name of the address.
address_line_1 - First line of the address.
city - City of the address.
is_main_address - Boolean denoting if the address is the main address.
postal_code - Postal code of the address.
region - Region of the address.
country_id - Country ID of the address.

Return all business addresses

By default, each customer or vendor is created with a main contact address and in Sage Business Cloud Accounting a delivery address on customers. Additional addresses can be created and associated with the contact but do not appear in the addresses returned for a contact record. To ensure all contact associated addresses are returned the contact id can be passed as a query parameter to the ‘addresses’ endpoint. It is not possible to pass the id of a contact_person to return addresses.

GET /addresses?contact_id=b807d75b119649c08e14068bee5c1f79