Adaco Budget API Guide & Reference

Introduction

The Adaco Budget API enables users to send budget records into Adaco, which are then used to populate and update the Adaco Budget and Budget Details tables. This allows third-party systems, such as accounting software, to be the primary source for budgeting records, avoiding double-entry issues as well as ensuring that Adaco users have the most up-to-date budget details to hand.

Important: Enabling this API for a Adaco customer does not stop users with the appropriate access rights from managing the budget data using the Adaco UI. This API can override any manual update to a budget record; and vice versa. Therefore, it is important that any users with access to editing budgets in Adaco are aware of how this API is implemented. 

Quick Facts

Integration type	SOAP with XML via HTTP or HTTPS
Authentication	Header authentication via a session ID
Availability	Fourth Inventory for Hotels customers
Testing	Test environment is available on request
More information	N/A

Updates

You can find any updates on the Release Notes page for the Budget API.

Overview of the tables

This API provides access to two tables:

• The Budget table holds the name of available budgets and which properties the budget is available in. A budget must exist in this table before it is available in the Budget Details table.
• The Budget Details table holds the details for each budget, such as the fiscal year and budget amount. Each field in the table maps to an element in the API request.

Note that these tables are not directly shown in the user interface. Instead, Adaco uses the data in the tables to populate relevant information windows in the user interface, for example:

Get Access

Before integrating, you’ll need to set up a new user account in Fourth with access rights to the API and resource. 

Requests to this API are not restricted by property. This enables you to create and update the budget tables regardless of which property the user account was created in.

Step 1: create a user group 

Create a user group for accessing the API within one of your Fourth properties — we recommend the central purchasing (CP) property where there is one. Then edit the Group Details for the group:

1. Under Edit Permissions, select Accounting.
2. Tick the Import Budgets option, then under Access Rights column select the 3 ellipsis to edit the access rights for the option.
3. On the modal window for the access rights, make sure to give the group the Create and Update access rights.

Step 2: create a user account

In the same property, create a user account. Assign it to the API user group.

Step 3: provide the API user the account details

The API user — normally a third-party system — will need to know the following:

• Username and password for the user account.
• Property number for the property in which the user account exists. They will need to include this number when making API requests.
• Property numbers for the properties that have budgets assigned to them. They will need to map these numbers to the property data in their own system.

Get the property number

Before you can make any Budget API requests, you will need the property numbers of the Adaco properties. One of our Fourth integration specialist can provide a list of these to you during your initial integration. You can also find a property's property number in the Fourth UI with the rest of the property's details. 

Get the outlet or division number

Similarly, you will also need the division and outlet numbers of the Adaco properties. One of our Fourth integration specialist can provide a list of these to you during your initial integration. You can also find outlet or division numbers in the Fourth UI within the Property Setup screen.

Screenshot showing Division Number

Screenshot showing Outlet Numbers

Available methods

This is a SOAP API. The following methods are available:

• Login — establishes a session

• InsertBudgets — adds one or more records into the Budget table

• UpdateBudgets — updates one or more records in the Budget table

• InsertBudgetDetails — adds one or more records into the Budget Details table

• UpdateBudgetDetails —  updates one or more records in the Budget Details table

Base path

The base path for all Budget API requests is:

<ROOT>/{CustomerName}Service/api/incomingbudget.svc

This is made of:

• The domain name of the Fourth cloud, referenced as <ROOT> above.
• A customer-specific CustomerName — this is the same name in the URL that is used when the customer logs into Fourth Inventory for Hotels. You must also add "Service" to the name; e.g. "acmeService".

The Fourth integration specialist involved in your integration will provide the specific URL you need. You can access a Web Service Definition Language file (WSDL) from this URL.

Header elements

You must include these elements in the SOAP header of InsertBudgets, UpdateBudgets, InsertBudgetDetails and UpdateBudgetDetails requests:

• ApplicationType — set this to Web.
• PropertyNumber — the property that the user account exists in.
• SessionID — the session ID retrieved via the login method.

Making Login method requests

The Login method establishes a session. This method accepts just two elements: username and password.

The response provides a Session ID that you will need to provide in the header for the other methods. The created session defaults to 90 minutes long.

Example request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.fourthhospitality.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:Login>
         <ws:userName>APIUser1234</ws:userName>
         <ws:password>Ex4mpl3P4ssw0rd</ws:password>
      </ws:Login>
   </soapenv:Body>
</soapenv:Envelope>

The response body returns a LoginResult element. This value is the session ID you need for further requests.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <LoginResponse xmlns="http://ws.fourthhospitality.com/">
         <LoginResult>ba99b4adb2dc44efb0cab40313d3d5c7</LoginResult>
      </LoginResponse>
   </s:Body>
</s:Envelope>

Making InsertBudgets method requests

The InsertBudgets method adds one or more records into the Budget table.

The Budget table holds the name of available budgets. A budget must exist in this table before it is available in the Budget Details table.

For each property that the budget relates to, you must create a record. For example, if the budget is required in the Central Property (CP) and two other properties, you must send a request with three records specifying the same budget number and name. See below for an example.

The response will confirm whether a record was created and if not, provide an error message for each unsuccessful record you submitted.

Elements

You will need to include a unique identifier in your requests in the BudgetNumber field. This is used in all other requests to identify the budget. See Elements in InsertBudgets and UpdateBudgets requests below for a full description of the XML element accepted in requests.

Example

This example shows a budget being created in multiple properties.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.fourthhospitality.com/">
   <soapenv:Header>
      <ws:AuthenticationHeader>
         <ws:ApplicationType>Web</ws:ApplicationType>
         <ws:PropertyNumber>1</ws:PropertyNumber>
         <ws:SessionID>ba99b4adb2dc44efb0cab40313d3d5c7</ws:SessionID>
      </ws:AuthenticationHeader>
   </soapenv:Header>
   <soapenv:Body>
      <ws:InsertBudgets>
         <ws:budgets>
            <ws:Budget>
               <ws:PropertyNumber>1</ws:PropertyNumber>
               <ws:BudgetNumber>5</ws:BudgetNumber>
               <ws:BudgetName>MAINTENANCE</ws:BudgetName>
            </ws:Budget>
            <ws:Budget>
               <ws:PropertyNumber>14</ws:PropertyNumber>
               <ws:BudgetNumber>5</ws:BudgetNumber>
               <ws:BudgetName>MAINTENANCE</ws:BudgetName>
            </ws:Budget>
            <ws:Budget>
               <ws:PropertyNumber>15</ws:PropertyNumber>
               <ws:BudgetNumber>5</ws:BudgetNumber>
               <ws:BudgetName>MAINTENANCE</ws:BudgetName>
            </ws:Budget>
         </ws:budgets>
      </ws:InsertBudgets>
   </soapenv:Body>
</soapenv:Envelope>

Making UpdateBudgets method requests

The InsertBudgets method updates one or more records in the Budget table.

The response will confirm whether a record was updated and if not, provide an error message for each unsuccessful record you submitted.

Elements

The budget you are updating is identified by the BudgetNumber. See Elements in InsertBudgets and UpdateBudgets requests below for a description of the XML element accepted in requests.

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.fourthhospitality.com/">
   <soapenv:Header>
      <ws:AuthenticationHeader>
         <ws:ApplicationType>Web</ws:ApplicationType>
         <ws:PropertyNumber>1</ws:PropertyNumber>
         <ws:SessionID>ba99b4adb2dc44efb0cab40313d3d5c7</ws:SessionID>
      </ws:AuthenticationHeader>
   </soapenv:Header>
   <soapenv:Body>
      <ws:UpdateBudgets>
         <ws:budgets>
            <ws:Budget>
               <ws:PropertyNumber>1</ws:PropertyNumber>
               <ws:BudgetNumber>5</ws:BudgetNumber>
               <ws:BudgetName>REPAIRS AND MAINTENANCE</ws:BudgetName>
            </ws:Budget>
         </ws:budgets>
      </ws:UpdateBudgets>
   </soapenv:Body>
</soapenv:Envelope>

Elements in InsertBudgets and UpdateBudgets requests

Node/Element	Type	Description
Budgets		Required Parent of Budget.
Budget		Required Parent of all other elements.
PropertyNumber	Integer	Required The unique number for an Adaco property. You can find this in the Fourth UI as "Property Number". During integration, Fourth will provide the values for existing properties. For example, 12.
BudgetNumber	Integer	Required A unique number assigned to the budget group inside Adaco. InsertBudgets requests — You must use a unique number to create a new budget. The request will fail if a budget with the same number already exists. UpdateBudgets requests — The number identifies the budget you wish to update. For example, 1.
BudgetName	String(100)	Required A human-friendly description of the budget group. For example, REPAIRS & MAINTENANCE.

Making InsertBudgetDetails method requests

The InsertBudgetDetails method creates one or more records into the Budget Details table.

 You can only add details for budgets that are also in the Budget table.

For each property that the budget details relates to, you must create a new record. For example, if the budget details are required in the Central Property (CP) and two other properties, you must send a request with three records for the budget. See below for an example.

The response will confirm whether a record was created and if not, provide an error message for each unsuccessful record you submitted.

Elements

The BudgetNumber field identifies the budget for which you are creating a budget details record. See Elements in InsertBudgetDetails and UpdateBudgetDetails requests below for a full description of the XML element accepted in requests.

Example

This example shows a budget detail record being created in multiple properties.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.fourthhospitality.com/">
   <soapenv:Header>
      <ws:AuthenticationHeader>
         <ws:ApplicationType>Web</ws:ApplicationType>
         <ws:PropertyNumber>1</ws:PropertyNumber>
         <ws:SessionID>ba99b4adb2dc44efb0cab40313d3d5c7</ws:SessionID>
      </ws:AuthenticationHeader>
   </soapenv:Header>
   <soapenv:Body>
      <ws:InsertBudgetDetails>
         <ws:BudgetDetails>
            <ws:BudgetDetail>
               <ws:PropertyNumber>1</ws:PropertyNumber>
               <ws:OutletDivisionNumber>5</ws:OutletDivisionNumber>
               <ws:OutletDivisionType>D</ws:OutletDivisionType>
               <ws:BudgetNumber>5</ws:BudgetNumber>
               <ws:AccountNumber>12345</ws:AccountNumber>
               <ws:PeriodNumber>12</ws:PeriodNumber>
               <ws:FiscalYear>2016</ws:FiscalYear>
               <ws:BudgetAmount>12000.50</ws:BudgetAmount>
            </ws:BudgetDetail>
            <ws:BudgetDetail>
               <ws:PropertyNumber>14</ws:PropertyNumber>
               <ws:OutletDivisionNumber>5</ws:OutletDivisionNumber>
               <ws:OutletDivisionType>D</ws:OutletDivisionType>
               <ws:BudgetNumber>5</ws:BudgetNumber>
               <ws:AccountNumber>12345</ws:AccountNumber>
               <ws:PeriodNumber>12</ws:PeriodNumber>
               <ws:FiscalYear>2016</ws:FiscalYear>
               <ws:BudgetAmount>12000.50</ws:BudgetAmount>
            </ws:BudgetDetail>
         </BudgetDetails>
      </ws:InsertBudgetDetails>
   </soapenv:Body> 
</soapenv:Envelope>

Making UpdateBudgetDetails method requests

The UpdateBudgetDetails method updates one or more records in the Budget Details table.

The response will confirm whether a record was updated and if not, provide an error message for each unsuccessful record you submitted.

Elements

The BudgetNumber field identifies the budget for which you are updating the budget detail record.See Elements in InsertBudgetDetails and UpdateBudgetDetails requests below for a full description of the XML element accepted in requests.

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.fourthhospitality.com/">
   <soapenv:Header>
      <ws:AuthenticationHeader>
         <ws:ApplicationType>Web</ws:ApplicationType>
         <ws:PropertyNumber>1</ws:PropertyNumber>
         <ws:SessionID>ba99b4adb2dc44efb0cab40313d3d5c7</ws:SessionID>
      </ws:AuthenticationHeader>
   </soapenv:Header>
   <soapenv:Body>
      <ws:UpdateBudgetDetails>
         <ws:BudgetDetails>
            <ws:BudgetDetail>
               <ws:PropertyNumber>1</ws:PropertyNumber>
               <ws:OutletDivisionNumber>5</ws:OutletDivisionNumber>
               <ws:OutletDivisionType>D</ws:OutletDivisionType>
               <ws:BudgetNumber>5</ws:BudgetNumber>
               <ws:AccountNumber>12345</ws:AccountNumber>
               <ws:PeriodNumber>12</ws:PeriodNumber>
               <ws:FiscalYear>2016</ws:FiscalYear>
               <ws:BudgetAmount>12000.50</ws:BudgetAmount>
            </ws:BudgetDetail>
         </BudgetDetails>
      </ws:UpdateBudgetDetails>
   </soapenv:Body> 
</soapenv:Envelope>

Elements in InsertBudgetDetails and UpdateBudgetDetails requests

Node/Element	Type	Description
BudgetDetails		Required Parent of BudgetDetails.
BudgetDetail		Required Parent of all other elements.
PropertyNumber	Integer	Required The unique number for an Adaco property. You can find this in the Fourth UI as "Property Number". During integration, Fourth will provide the values for existing properties. For example, 12.
OutletDivisionNumber	Integer	Required The ID of the outlet or division against which the budget detail should be applied. For example, 4.
OutletDivisionType	String(1)	Required Whether the budget applies to an outlet or a division: O — for an Outlet D — for a Division For example, D.
BudgetNumber	Integer	Required A unique number assigned to the budget group inside Adaco. InsertBudgetDetails requests — The number identifies a budget for which you wish to create new budget details for. UpdateBudgetDetails requests — The number identifies a budget for which you wish to update the budget details. For example, 5.
AccountNumber	Integer	Required The account number for the General Ledger Account. For example, 1.
PeriodNumber	Integer	Required The period within the fiscal year that the budgetAmount applies to. PeriodNumber can be an integer between 1 to 12. Customers can determine whether they use calendar months or another period rhythm, such as quarterly. For example, 3.
FiscalYear	Integer	Required The fiscal year that the budget applies to. This must be four digits. For example, 2023.
BudgetAmount	Decimal(18,3)	Required The budgeted value for this period for the outlet or division. This is by account, for the fiscal year. For example, 1299.99.

Additional data updated in Fourth

Adaco updates these fields after a successful request related to the BudgetDetail table.

Adaco database field	Value
BudgetDetail.CreatedByUserID	The ID of the user who authenticated with the service. Adaco adds this to each new record when created by the InsertBudgetDetails method.
BudgetDetail.ModifiedDateTime	The date and time when the budget detail record was last modified in Fourth. Adaco adds this to each record when created by the InsertBudgetDetails method or updated y the UpdateBudgetDetails method.