Locations

Location is a dimension that is used to represent the geographic locations of offices or facilities, or to represent divisions in a company. Once you have defined some locations, you can set locations on transactions, and that information can be used to provide new insights in reports.

You can create a hierarchy of locations to reflect how locations are organized within your company.

List locations

get/objects/company-config/location

Returns up to 100 locations from the collection with a key, ID, and link for each location. This operation is mostly for use in testing; use the query service to find locations that meet certain criteria and specify the properties that are returned.

SecurityOAuth2
Responses
200

OK

400

Bad Request

Request samples 
Response samples 
application/json
{
  • "ia::result": [
    • {
      • "key": "1",
      • "id": "US-PNW",
      • "href": "/objects/company-config/location/1"
      },
    • {
      • "key": "96",
      • "id": "US-EAST",
      • "href": "/objects/company-config/location/96"
      },
    • {
      • "key": "21",
      • "id": "US-SOUTH",
      • "href": "/objects/company-config/location/21"
      }
    ],
  • "ia::meta": {
    • "totalCount": 3,
    • "start": 1,
    • "pageSize": 100,
    • "next": null,
    • "previous": null
    }
}
Create a location
post/objects/company-config/location
Creates a new location. You can think of this as adding a new value to the dimension that you can use to tag transactions for reporting.


SecurityOAuth2 
Request 
Request Body schema: application/json
required
Create location object


id
required
string
Unique identifier for the location.


 
 Example:  "1-Lyon"
name
required
string
Name of the location.


 
 Example:  "Lyon-France"
status
string
 Default:  "active"
Status of the dimension object:


    

  • active - Transactions can be posted to this dimension member and it can be used in reports.
    • 

  • activeNonPosting - Transactions cannot be posted to the dimension member but it can be used in reports.
    • 

  • inactive - The dimension member cannot be used for transactions or reports.
    • 



 Enum: "active" "activeNonPosting" "inactive"  
 Example:  "active"
taxId
string
State tax ID or VAT registration number.


 
 Example:  "US4321112"
startDate
string <date> 
Start date of operation at this location.


 
 Example:  "2021-01-01"
endDate
string <date> 
End date of operation at this location.


 
 Example:  "2022-04-01"
object
The list of contacts for the location.


 
object
The primary location contact specifies the company name, address, and other details as they should appear on invoices, bills, and other forms.


 
key
string
System-assigned unique key for the contact.


 
 Example:  "21"
id
string
Contact ID.


 
 Example:  "jsmith"
lastName
string or null
 Deprecated 
Last name.


 
 Example:  "Smith"
firstName
string or null
 Deprecated 
First name.


 
 Example:  "John"
middleName
string or null
 Deprecated 
Middle name.


 
 Example:  "Archibald"
prefix
string or null
 Deprecated 
Prefix, such as Mr., Mrs., or Ms.


 
 Example:  "Mr"
printAs
string
 Deprecated 
The contact's name as it will appear on documents.


 
 Example:  "John Smith"
email1
string or null
 Deprecated 
Primary email address.


 
 Example:  "[email protected]"
email2
string or null
 Deprecated 
Secondary email address.


 
 Example:  "[email protected]"
phone1
string or null
 Deprecated 
Primary phone number.


 
 Example:  "14085551212"
phone2
string or null
 Deprecated 
Secondary phone number.


 
 Example:  "14085559876"
mobile
string or null
 Deprecated 
Mobile phone number.


 
 Example:  "14085554420"
pager
string or null
 Deprecated 
Pager number.


 
 Example:  "14085559987"
fax
string or null
 Deprecated 
Fax number.


 
 Example:  "14085555309"
URL1
string or null
 Deprecated 
Web page address for this contact.


 
 Example:  "https://mycompany.com"
URL2
string or null
 Deprecated 
Secondary web page address.


 
 Example:  "https://anothercompany.com"
companyName
string or null
 Deprecated 
Name of the company.


 
 Example:  "AlcoSoft Inc"
object
Mailing address.


 
object
The address for receiving goods and services, if different from the primary contact address.


 
key
string
System-assigned unique key for the contact.


 
 Example:  "21"
id
string
Contact ID.


 
 Example:  "jsmith"
lastName
string or null
 Deprecated 
Last name.


 
 Example:  "Smith"
firstName
string or null
 Deprecated 
First name.


 
 Example:  "John"
middleName
string or null
 Deprecated 
Middle name.


 
 Example:  "Archibald"
prefix
string or null
 Deprecated 
Prefix, such as Mr., Mrs., or Ms.


 
 Example:  "Mr"
printAs
string
 Deprecated 
The contact's name as it will appear on documents.


 
 Example:  "John Smith"
email1
string or null
 Deprecated 
Primary email address.


 
 Example:  "[email protected]"
email2
string or null
 Deprecated 
Secondary email address.


 
 Example:  "[email protected]"
phone1
string or null
 Deprecated 
Primary phone number.


 
 Example:  "14085551212"
phone2
string or null
 Deprecated 
Secondary phone number.


 
 Example:  "14085559876"
mobile
string or null
 Deprecated 
Mobile phone number.


 
 Example:  "14085554420"
pager
string or null
 Deprecated 
Pager number.


 
 Example:  "14085559987"
fax
string or null
 Deprecated 
Fax number.


 
 Example:  "14085555309"
URL1
string or null
 Deprecated 
Web page address for this contact.


 
 Example:  "https://mycompany.com"
URL2
string or null
 Deprecated 
Secondary web page address.


 
 Example:  "https://anothercompany.com"
companyName
string or null
 Deprecated 
Name of the company.


 
 Example:  "AlcoSoft Inc"
object
Mailing address.


 
locationReportingTitle
string
Location information displayed in reports, in addition to the location name. For example, a location title might include the address and manager name.


 
 Example:  "Seattle Sales Office"
object
Parent location, for location hierarchies.


 
key
string
Parent location key.


 
 Example:  "65"
id
string
Parent location ID.


 
 Example:  "1-France"
object
The employee that manages the location.


 
key
string
Manager's employee key.


 
 Example:  "81"
id
string
ID of the manager employee.


 
 Example:  "anne.jason"
Responses 
201
Created


400
Bad Request


Request samples 
application/json
{
  • "id": "loc22",
  • "name": "22-India",
  • "description": "All India offices",
  • "status": "active"
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "234",
    • "id": "22-India",
    • "href": "/objects/company-config/location/234"
    },
  • "ia::meta": {
    • "totalCount": 1
    }
}
Get a location
get/objects/company-config/location/{key}
Returns detailed information for a specified location.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for a location.


 
 Example:  92
Responses 
200
OK


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "id": "WEN",
    • "key": "6",
    • "name": "Wenatchee",
    • "parent": {
      • "id": "PNW--Pacific Northwest",
      • "key": "5",
      • "href": "/objects/company-config/location/5"
      },
    • "manager": {
      • "name": "miller, dan",
      • "id": "EE-0000123--miller, dan",
      • "key": "2",
      • "href": "/objects/company-config/employee/2"
      },
    • "contacts": {
      • "primary": {
        },
      • "shipTo": {
        }
      },
    • "startDate": "2021-01-01",
    • "endDate": "2021-04-01",
    • "status": "active",
    • "audit": {
      • "createdDateTime": "2022-02-11T09:07:07Z",
      • "modifiedDateTime": "2022-02-11T09:07:07Z",
      • "createdBy": "110",
      • "modifiedBy": "110",
      • "createdByUser": {
        },
      • "modifiedByUser": {
        }
      },
    • "locationReportingTitle": "Seattle Sales Office",
    • "taxId": "US4321112",
    • "href": "/objects/company-config/location/102"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Update a location
patch/objects/company-config/location/{key}
Updates an existing location by setting field values. Any fields not provided remain unchanged.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for a location.


 
 Example:  92
Request Body schema: application/json
name
string
Name of the location.


 
 Example:  "Lyon-France"
status
string
 Default:  "active"
Status of the dimension object:


    

  • active - Transactions can be posted to this dimension member and it can be used in reports.
    • 

  • activeNonPosting - Transactions cannot be posted to the dimension member but it can be used in reports.
    • 

  • inactive - The dimension member cannot be used for transactions or reports.
    • 



 Enum: "active" "activeNonPosting" "inactive"  
 Example:  "active"
taxId
string
State tax ID or VAT registration number.


 
 Example:  "US4321112"
startDate
string <date> 
Start date of operation at this location.


 
 Example:  "2021-01-01"
endDate
string <date> 
End date of operation at this location.


 
 Example:  "2022-04-01"
object
The list of contacts for the location.


 
object
The primary location contact specifies the company name, address, and other details as they should appear on invoices, bills, and other forms.


 
key
string
System-assigned unique key for the contact.


 
 Example:  "21"
id
string
Contact ID.


 
 Example:  "jsmith"
lastName
string or null
 Deprecated 
Last name.


 
 Example:  "Smith"
firstName
string or null
 Deprecated 
First name.


 
 Example:  "John"
middleName
string or null
 Deprecated 
Middle name.


 
 Example:  "Archibald"
prefix
string or null
 Deprecated 
Prefix, such as Mr., Mrs., or Ms.


 
 Example:  "Mr"
printAs
string
 Deprecated 
The contact's name as it will appear on documents.


 
 Example:  "John Smith"
email1
string or null
 Deprecated 
Primary email address.


 
 Example:  "[email protected]"
email2
string or null
 Deprecated 
Secondary email address.


 
 Example:  "[email protected]"
phone1
string or null
 Deprecated 
Primary phone number.


 
 Example:  "14085551212"
phone2
string or null
 Deprecated 
Secondary phone number.


 
 Example:  "14085559876"
mobile
string or null
 Deprecated 
Mobile phone number.


 
 Example:  "14085554420"
pager
string or null
 Deprecated 
Pager number.


 
 Example:  "14085559987"
fax
string or null
 Deprecated 
Fax number.


 
 Example:  "14085555309"
URL1
string or null
 Deprecated 
Web page address for this contact.


 
 Example:  "https://mycompany.com"
URL2
string or null
 Deprecated 
Secondary web page address.


 
 Example:  "https://anothercompany.com"
companyName
string or null
 Deprecated 
Name of the company.


 
 Example:  "AlcoSoft Inc"
object
Mailing address.


 
object
The address for receiving goods and services, if different from the primary contact address.


 
key
string
System-assigned unique key for the contact.


 
 Example:  "21"
id
string
Contact ID.


 
 Example:  "jsmith"
lastName
string or null
 Deprecated 
Last name.


 
 Example:  "Smith"
firstName
string or null
 Deprecated 
First name.


 
 Example:  "John"
middleName
string or null
 Deprecated 
Middle name.


 
 Example:  "Archibald"
prefix
string or null
 Deprecated 
Prefix, such as Mr., Mrs., or Ms.


 
 Example:  "Mr"
printAs
string
 Deprecated 
The contact's name as it will appear on documents.


 
 Example:  "John Smith"
email1
string or null
 Deprecated 
Primary email address.


 
 Example:  "[email protected]"
email2
string or null
 Deprecated 
Secondary email address.


 
 Example:  "[email protected]"
phone1
string or null
 Deprecated 
Primary phone number.


 
 Example:  "14085551212"
phone2
string or null
 Deprecated 
Secondary phone number.


 
 Example:  "14085559876"
mobile
string or null
 Deprecated 
Mobile phone number.


 
 Example:  "14085554420"
pager
string or null
 Deprecated 
Pager number.


 
 Example:  "14085559987"
fax
string or null
 Deprecated 
Fax number.


 
 Example:  "14085555309"
URL1
string or null
 Deprecated 
Web page address for this contact.


 
 Example:  "https://mycompany.com"
URL2
string or null
 Deprecated 
Secondary web page address.


 
 Example:  "https://anothercompany.com"
companyName
string or null
 Deprecated 
Name of the company.


 
 Example:  "AlcoSoft Inc"
object
Mailing address.


 
locationReportingTitle
string
Location information displayed in reports, in addition to the location name. For example, a location title might include the address and manager name.


 
 Example:  "Seattle Sales Office"
object
Parent location, for location hierarchies.


 
key
string
Parent location key.


 
 Example:  "65"
id
string
Parent location ID.


 
 Example:  "1-France"
object
The employee that manages the location.


 
key
string
Manager's employee key.


 
 Example:  "81"
id
string
ID of the manager employee.


 
 Example:  "anne.jason"
Responses 
200
OK


400
Bad Request


Request samples 
application/json
{
  • "manager": {
    • "key": "12"
    },
  • "contacts": {
    • "primary": {
      • "id": "john.doe"
      },
    • "shipTo": {
      • "id": "jane.daw"
      }
    }
}
Response samples 
application/json
{
  • "ia::result": {
    • "key": "12",
    • "id": "SW",
    • "href": "/objects/company-config/location/12"
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 1,
    • "totalError": 0
    }
}
Delete a location
delete/objects/company-config/location/{key}
Deletes a location. You can delete a location if it is not being used or referenced. Deleted locations cannot be recovered.


SecurityOAuth2 
Request 
path Parameters
key
required
string
System-assigned key for a location.


 
 Example:  92
Responses 
204
No Content


400
Bad Request


Request samples 
Response samples 
application/json
{
  • "ia::result": {
    • "ia::error": {
      • "code": "invalidRequest",
      • "message": "A POST request requires a payload",
      • "errorId": "REST-1028",
      • "additionalInfo": {
        },
      • "supportId": "Kxi78%7EZuyXBDEGVHD2UmO1phYXDQAAAAo"
      }
    },
  • "ia::meta": {
    • "totalCount": 1,
    • "totalSuccess": 0,
    • "totalError": 1
    }
}