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 contactaccount_code, full_name, initials, nhs_number, patient_id, ref.

  • job_title
    string

    The location contact's job title.

  • large_print_requested_for_billing
    boolean

    A flag indicating that the billing party wants to receive billing comms (invoices, statements, etc.) in larger print.

  • 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": "66bfb4bc9ab4e3d6eb73492a",
    "account_code": "OCC0004",
    "billing_comms_preference": null,
    "billing_consolidate_invoices": false,
    "billing_enabled": true,
    "company_name": "Oxfordshire County Council",
    "created": "2024-08-16 20:21:16",
    "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,
    "large_print_requested_for_billing": null,
    "last_name": "Frey",
    "locations": [
        "66bfb4bb9ab4e3d6eb734900"
    ],
    "mobile": null,
    "modified": "2024-08-16 20:21:16",
    "multi_location": false,
    "next_of_kin": null,
    "notes": "Michael is only available 9am-12pm Monday-Wednesday.",
    "payment_method": "bac",
    "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.

GET
/v1/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.

GET
/v1/location-contacts/<location_contact_id>
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": "66bfb4bc9ab4e3d6eb73492a",
    "account_code": "OCC0004",
    "billing_comms_preference": null,
    "billing_consolidate_invoices": false,
    "billing_enabled": true,
    "company_name": "Oxfordshire County Council",
    "created": "2024-08-16 20:21:16",
    "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,
    "large_print_requested_for_billing": null,
    "last_name": "Frey",
    "locations": [
        "66bfb4bb9ab4e3d6eb734900"
    ],
    "mobile": null,
    "modified": "2024-08-16 20:21:16",
    "multi_location": false,
    "next_of_kin": null,
    "notes": "Michael is only available 9am-12pm Monday-Wednesday.",
    "payment_method": "bac",
    "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
}