Locations

Locations represent the places Events are held.

Search

The following example fetches the first page of Locations in the United States or United Kingdom, including their External IDs and Custom Field values:

query LocationsByRegionName {
  locations(
    filters:[
      {field: regionName, operation: in, values: ["United States", "United Kingdom"]}
    ]
  ){
    edges{
      node{
        id
        name
        region{
          id
          code
          name
        }
        externalIds {
          name
          value
        }
        customFieldValues {
          definition {
            key
            label
          }
          value
        }
      }
    }
  }
}

Custom Field configuration

Locations support Custom Fields. Configure them in Control Panel → Custom Fields → Location, or use objectType: Location with customFields.createGlobalCustomDefinition.

Retrieve the definitions before setting values:

query LocationCustomFields {
  customFieldTemplate(type: Location) {
    customFieldDefinitions {
      key
      label
      type
      isRequired
      options { id value label }
    }
  }
}

Use a returned key as the definitionKey in the mutations below. The examples assume a text field for an office name. Supply values for every required Location Custom Field when creating a Location.

Create

location.create accepts externalIds as name/value pairs and customFieldValues as definitionKey/value pairs, alongside the standard Location fields. Pass an existing Region ID and the Custom Field key as variables:

mutation CreateLocationWithCustomData($regionId: ID!, $definitionKey: ID!) {
  location {
    create(input: {
      name: "Edinburgh Training Centre"
      regionId: $regionId
      externalIds: [{ name: "facilities_id", value: "EDI-001" }]
      customFieldValues: [{ definitionKey: $definitionKey, value: "Edinburgh" }]
    }) {
      location {
        id
        name
        externalIds { name value }
        customFieldValues { definitionKey value }
      }
      errors { label value message }
    }
  }
}

For all create parameters, see the LocationCreateInput API Reference.

Update

Use the Location's id as locationId inside LocationUpdateInput:

mutation UpdateLocationCustomData($locationId: ID!, $definitionKey: ID!) {
  location {
    update(input: {
      locationId: $locationId
      externalIds: [{ name: "facilities_id", value: "EDI-002" }]
      customFieldValues: [{ definitionKey: $definitionKey, value: "Edinburgh West" }]
    }) {
      location {
        id
        externalIds { name value }
        customFieldValues { definitionKey value }
      }
      errors { label value message }
    }
  }
}

External IDs supplied on create or update overwrite existing values with the same name. Values must remain unique for that External ID name across Locations. Omitted External IDs and Custom Fields retain their stored values. An empty list does not clear them. To clear a Custom Field, send its definitionKey with value: null, subject to the field's validation. To remove an External ID, use externalId.remove.

For all update parameters, see the LocationUpdateInput API Reference.

Find by External ID

Location lookup by External ID is also available through nodeByExternalId:

query LocationByExternalId {
  nodeByExternalId(type: Location, name: "facilities_id", value: "EDI-002") {
    id
    ... on Location {
      name
      externalIds { name value }
      customFieldValues { definitionKey value }
    }
  }
}

Custom Field values and External IDs belong to saved Locations. A Location synthesized from a private Event's free-text location returns empty lists for both.

Reporting and the Location list

Location Custom Fields and External IDs are available as output fields in Location reports and through the Location relationship in Event reports.

The Location create and edit forms show the configured Custom Fields according to the user's field permissions. In the Location list, an xID pill appears beside the name when the Location has External ID values. Select the pill to view the names and values, then select a row to copy its value.