Location contacts

A contact for the location (typically another organization). Contacts for a location might include suppliers (e.g. a heating engineer or hairdresser), support services (e.g. a surgery or dentist), companies the location might recommended to service users and their family (e.g florists, funeral directors), etc.

Location contacts help to provide consistency when location managers leave and are replaced, provide a central contact list for other staff and can be used as a basis for local B2B marketing.

The location contact object

Attributes

_id
string

A unique Id for the location contact.
account_code
string

The location contact's account code, used when exporting invoices to an accounts package.
billing_comms_preference
list of strings

The billing party's preference for receiving billing related commsemail, post.
billing_consolidate_invoices
boolean

A flag indicating if invoices generated during an invoice run should be consolidated into a single invoice for the location contact.
billing_enabled
boolean

A flag indiciating if billing is enabled for the location contact.
company_name
string

The name of the location contact's company.
created
string

The date/time the location contact was created.
email
string

The location contact's email address.
email_invoices_to
list of strings

A list of email addresses to send invoices (and related documents) to.
first_name
string

The location contact's first name.
future_billing_disabled
boolean

A flag indicating that while billing is enabled for the location contact they cannot appear as an option for new contracts or invoices.
has_direct_debit_mandate
boolean

A flag indicating if the location contact has an direct debit mandate in place (in any state, pending, active or pending cancellation).
invoices_service_user_id_fields
list of strings

A list of fields to identify a service user with when generating a line item for the service user in an invoice for the location contactfull_name, initials, nhs_number, patient_id, ref.
job_title
string

The location contact's job title.
last_name
string

The location contact's last name.
locations
list of strings

A list of locations the location contact relates to.
mobile
string

The location contact's mobile number.
modified
string

The date/time the location contact was created.
multi_location
boolean

Flag indicating if the contact is applicable to multiple locations.
next_of_kin
boolean

Flag indicating that the service user contact is the next of kin for the service user.
notes
string

Additional notes for the location contact.
payment_method
string

The method the billing party is expected to use for making paymentscard, cash, cheque, standing_order, direct_debit, bac.
phone
string

The location contact's phone number.
postal_address
hash

The location contact's postal address.
- postal_address.address_1
  string
  
  Address line 1 (e.g. house name/number).
- postal_address.address_2
  string
  
  Address line 2 (e.g. street).
- postal_address.town
  string
  
  Town, city or village.
- postal_address.county
  string
  
  County.
- postal_address.postcode
  string
  
  Postal code.
- postal_address.country
  string
  
  Country.
street_address
hash

The location contact's street address.
- street_address.address_1
  string
  
  Address line 1 (e.g. house name/number).
- street_address.address_2
  string
  
  Address line 2 (e.g. street).
- street_address.town
  string
  
  Town, city or village.
- street_address.county
  string
  
  County.
- street_address.postcode
  string
  
  Postal code.
- street_address.country
  string
  
  Country.
tags
list of strings

A set of tags to help make contacts easy to find and organizer, for example you might tag a contact as 'dentist' and 'medical services'.
title
string

The location contact's title.
tradeshift_tenant_id
string

The tenant ID for the contact on Tradeshift.
website_url
string

The URL of the location contact company's website
work_phone
string

The service user contact's work phone number.

The location contact object

{
    "_id": "662edc5a835c6a1ad9675d06",
    "account_code": "OCC0004",
    "billing_comms_preference": null,
    "billing_consolidate_invoices": false,
    "billing_enabled": true,
    "company_name": "Oxfordshire County Council",
    "created": "2024-04-28 23:31:38",
    "email": "micheal.frey@oxfordshire.gov.uk",
    "email_invoices_to": null,
    "first_name": "Michael",
    "future_billing_disabled": null,
    "has_direct_debit_mandate": null,
    "invoices_service_user_id_fields": null,
    "job_title": null,
    "last_name": "Frey",
    "locations": [
        "662edc59835c6a1ad9675cce"
    ],
    "mobile": null,
    "modified": "2024-04-28 23:31:38",
    "multi_location": false,
    "next_of_kin": null,
    "notes": "Michael is only available 9am-12pm Monday-Wednesday.",
    "payment_method": null,
    "phone": "0345 050 7666",
    "postal_address": {
        "address_1": "County Hall",
        "address_2": "New Road",
        "country": "",
        "county": "",
        "postcode": "OX1 1ND",
        "town": "Oxford"
    },
    "street_address": {
        "address_1": "",
        "address_2": "",
        "country": "",
        "county": "",
        "postcode": "",
        "town": ""
    },
    "tags": [
        "LA"
    ],
    "title": "",
    "tradeshift_tenant_id": null,
    "website_url": "https://www.oxfordshire.gov.uk",
    "work_phone": null
}

List all location contacts

Return a list of location contacts.

Parameters

attributes
optional

default ['_id']

A list of attributes to include for fetched objects.
filters-ids
optional

A filter that accepts a list of Ids and filters the items returned to those with an Id in the list.
filters-location
optional

A filter that accepts a list of location Ids and filters location contacts by the location they relate to.
filters-modified_after
optional

A filter that accepts a date/time and filters the items returned to those modified after the date/time.
filters-modified_before
optional

A filter that accepts a date/time and filters the items returned to those modified before the date/time.
filters-q
optional

A case insensitive keyword filter applied to the following fields; account_code, company_name.
filters-tags
optional

A filter that accepts a list of tags and filters location contacts by the tags assigned to them.
page
optional

default 1

The page number to fetch.
per_page
optional

default 10

The number of items to return per page.
sort_by
optional

default _id

A list of fields the returned items can be sorted by. Fields prefixed with minus (-) sign are sorted in descending order.
- _id
- created
- modified
- company_name

Response

Returns a page of location contacts.

var locationContacts = apiClient.Request(
    HttpMethod.Get,
    "location-contacts",
    new MultiValueDict()
        .Add("attributes", "company_name", "first_name", "last_name")
        .Add("filters-location", locationId)
);

<?php

$location_contacts = $api_client->request(
    'GET',
    'location-contacts',
    [
        'attributes'=>['company_name', 'first_name', 'last_name'],
        'filters-location'=>[location_id]
    ]
);

location_contacts = api_client(
    'GET',
    'location-contacts',
    params={
        'attributes': ['company_name', 'first_name', 'last_name'],
        'filters-location': [location_id]
    }
)

location_contacts = api_client.request(
    'GET',
    'location-contacts',
    params: {
        'attributes' => ['company_name', 'first_name', 'last_name'],
        'filters-location' => [location_id]
    }
)

Response

{
    "item_count": 0,
    "items": [],
    "page": 1,
    "page_count": 1,
    "per_page": 10
}

Retrieve a location contact

Retreive a location contact object.

Response

Returns a location contact object.

var locationContact = apiClient.Request(
    HttpMethod.Get,
    $"location-contacts/{locationContactId}"
);

<?php

$location_contact = $api_client->request(
    'GET',
    'location-contacts/' . $location_contact_id
);

location_contact = api_client(
    'GET',
    f'location-contacts/{location_contact_id}'
)

location_contact = api_client.request(
    'GET',
    "location-contacts/#{location_contact_id}"
)

Response

{
    "_id": "662edc5a835c6a1ad9675d06",
    "account_code": "OCC0004",
    "billing_comms_preference": null,
    "billing_consolidate_invoices": false,
    "billing_enabled": true,
    "company_name": "Oxfordshire County Council",
    "created": "2024-04-28 23:31:38",
    "email": "micheal.frey@oxfordshire.gov.uk",
    "email_invoices_to": null,
    "first_name": "Michael",
    "future_billing_disabled": null,
    "has_direct_debit_mandate": null,
    "invoices_service_user_id_fields": null,
    "job_title": null,
    "last_name": "Frey",
    "locations": [
        "662edc59835c6a1ad9675cce"
    ],
    "mobile": null,
    "modified": "2024-04-28 23:31:38",
    "multi_location": false,
    "next_of_kin": null,
    "notes": "Michael is only available 9am-12pm Monday-Wednesday.",
    "payment_method": null,
    "phone": "0345 050 7666",
    "postal_address": {
        "address_1": "County Hall",
        "address_2": "New Road",
        "country": "",
        "county": "",
        "postcode": "OX1 1ND",
        "town": "Oxford"
    },
    "street_address": {
        "address_1": "",
        "address_2": "",
        "country": "",
        "county": "",
        "postcode": "",
        "town": ""
    },
    "tags": [
        "LA"
    ],
    "title": "",
    "tradeshift_tenant_id": null,
    "website_url": "https://www.oxfordshire.gov.uk",
    "work_phone": null
}