Frequently Asked Questions

This topic provides answers for frequently asked questions.

Web Services

Why am I getting an error about an invalid Web Services authorization?

If your Web Services call, AJAX gateway call, or SDK function fails with the following error, it means your Web Services sender ID is not authorized for the target company:

<response>
    <control>
        <status>success</status>
        <senderid>test_sender_id</senderid>
        <controlid>hello_world</controlid>
        <uniqueid>false</uniqueid>
        <dtdversion>3.0</dtdversion>
    </control>
    <operation>
        <authentication>
            <status>failure</status>
            <userid>test_user_id</userid>
            <companyid>test_company_id</companyid>
        </authentication>
        <errormessage>
            <error>
                <errorno>XL03000006</errorno>
                <description>Invalid Web Services Authorization</description>
                <description2>The sender ID &#039;test_sender_id&#039; is not authorized to make Web Services requests to company ID &#039;test_company_id&#039;.</description2>
                <correction>Contact the company administrator to grant Web Services authorization to this sender ID.</correction>
            </error>
        </errormessage>
    </operation>
</response>

Ask the company administrator to review the Web Services authorizations list on the Company Configuration Security tab, and add your sender ID if it’s not present. Note that the ajax sender ID must be included in the list when the Platform Services AJAX gateway is used.

Web Services authorization list

For more information, see Web Services authorizations in the Sage Intacct product help.

How do I get a Web Services developer license?

We use the term “Marketplace Partners” for companies that develop add-ons and applications that integrate with Sage Intacct. Please see Become a Partner on the Sage Intacct website for information on how to get started.

Can I change the password for my Web Services sender ID?

If you must change the password for a Web Services sender ID, open a case with Sage Intacct’s support team by logging in to the Sage Intacct Community.

How do I monitor and increase throughput for API calls, CSV imports, and offline reports?

In Sage Intacct, companies use offline processes for activities such as API transactions (asynchronous Web Services requests, Platform Services triggers, Customization Services smart events, or CSV imports) and offline reports. With the standard level of service (LOS), each company is allowed one API transaction job (online or offline) and one offline report job that can run concurrently. Offline processes from different companies share computing resources, so you might have to wait in line even if you have only one job.

If a company receives more than two requests at a time, the third one is held for 30 seconds. If a spot does not open up in that time, an error is thrown:

There are too many operations running for this company

You can use queue administration to view a list of all offline jobs queued to run in your company. If you have a premium level of service (LOS), you can also prioritize and cancel jobs. You can use APIs or the UI to use queue administration.

If you need greater throughput for offline jobs or if you need dedicated resources for your company, consider upgrading your LOS package. Contact your account manager for details.

Why are users getting connection errors about non-secure connections or other SSL issues?

Sage Intacct uses CloudFlare as the content delivery network (CND) that provides internet connections to Sage Intacct applications. When Sage Intacct and/or CloudFlare upgrade SSL certificates, Web Services integrations that use certificate authorities that stay up to date will not experience any issues.

However, Web Services integrations that save a certificate locally must upgrade that certificate or users will experience connection errors. While Sage Intacct makes every effort to communicate these changes in advance, it’s possible that some integrations may miss having their SSL certificates upgraded. In this case, users will experience connection errors that mention security certificates, SSL, or insecure/non-private connections. The solution to this problem is to upgrade old SSL certificates on the servers, or better yet, set up a certificate authority. This covers all of the Sage Intacct sub domains, such as:

Integrations should not hardcode certificate authority files in their code. If these hardcoded entries exist, they need to be changed as well (it is strongly recommended that a modern/standard approach be used instead).

XML API

How do I verify/troubleshoot my API calls?

Before doing any serious XML API work, it’s strongly recommended that you become familiar with the use of Postman and the Sage Intacct API collection for Postman. With this approach, you can easily learn to use the API, and test and verify your API calls before hard coding them. See Your First XML API Calls to get started.

Also, consider adding a flag to enable debug logging in your application/integration to help as you develop.

Even better, consider using one of the Sage Intacct SDKs, which nicely wrap the XML APIs for you:

Where can I find information about generic and/or object-specific functions?

Find the object of interest in the API documentation, then look for the functions on that page. For example, if you want to perform some action on a bill, look at the APBILL page, which includes the certified generic functions, the object-specific/legacy functions, and examples for both.

For custom objects, use the Platform Services Objects API documentation, which provides functions that let you get information about fields of custom objects. You can then use this information to compose your generic function calls.

Are legacy functions going away?

When implementing new APIs, Sage Intacct provides generic or open functions that can operate on multiple types of objects. The older, object-specific functions are labeled as legacy in the documentation, which simply means they will not be enhanced. There are no plans to deprecate legacy functions, and in fact, there are cases in which they are the only functions available.

Can I use an undocumented function?

If an object or function is not included in the API documentation, it is likely not yet supported and subject to change. You can post an idea on the Sage Intacct Community or log a support case to inquire about the status of such objects and functions.

What return format should I use for best results when using readByQuery and readMore?

When you usereadByQuery with the XML returnFormat, which is the recommended format for all API calls, the returned data element has attributes about how many results are available:

 <data listtype="contract" count="2" totalcount="1588" numremaining="1586" resultId="7765623331WQdg3cCoA4MAAH4trhIAAAAD5">

If you use a different return format such as JSON, this information isn’t provided - particularly the resultId.

When using readByQuery, be aware that you cannot perform queries involving many-to-many or one-to-many relationships. Similarly, you cannot use readByQuery to return multiple owned objects.

If you need information about multiple related or owned objects, first use readByQuery to get the unique key (typically record number) for the record, then supply the key to the read function to get details about owned and related objects.

For example, a read on an APBILL record returns any owned bill lines:

<APBILL>
	<RECORDNO>259</RECORDNO>
	...
	<APBILLITEMS>
		<apbillitem>
			<RECORDNO>4354</RECORDNO>
			<RECORDKEY>259</RECORDKEY>
			<ACCOUNTKEY>131</ACCOUNTKEY>
			<ACCOUNTNO>7700</ACCOUNTNO>
			...
		</apbillitem>
		<apbillitem>
			<RECORDNO>4356</RECORDNO>
			<RECORDKEY>259</RECORDKEY>
			<ACCOUNTKEY>132</ACCOUNTKEY>
			<ACCOUNTNO>7710</ACCOUNTNO>
			...
		</apbillitem>
	</APBILLITEMS>
	...
</APBILL>

The same limitation is true for custom relationships. If you have a one-to-many relationship from a custom object to a Contract, for example, you cannot use readByQuery to list the custom object’s related contracts. Instead, you can use read on the custom object.

Note: You can use readByQuery for a many-to-one relationship if you start from the many side of the relationship.

How do I update an owned object?

Certain sub-components of Sage Intacct standard objects are referred to as owned objects. An owned object belongs to another object and typically cannot be manipulated directly. Instead, you work with owned objects by making API calls on the owner.

For example, in almost all cases, the line items of a transaction are objects owned by the header. Accordingly, you cannot perform an update operation directly on a transaction’s line item record. Instead you perform an update operation on the transaction header and pass in the line item information.

The following show two examples that update owned objects:

<update>
    <APBILL>
        <RECORDNO>65</RECORDNO>
        <APBILLITEMS>
            <APBILLITEM>
                <LINE_NO>1</LINE_NO>
                <ACCOUNTNO>6225</ACCOUNTNO>
                <TRX_AMOUNT>100.12</TRX_AMOUNT>
                <ENTRYDESCRIPTION>Additional service call</ENTRYDESCRIPTION>
                <DEPARTMENTID>D300</DEPARTMENTID>
            </APBILLITEM>
        </APBILLITEMS>
    </APBILL>
</update>

<update_sotransaction key="Sales Order-SO1234">
    <updatesotransitems>
        <updatesotransitem line_num="1">
            <memo>Testing1234</memo>
        </updatesotransitem>
    </updatesotransitems>
</update_sotransaction>

How do I query for an object based on a joined field (or how do I query for an employee by name)?

If you query for objects based on a field whose value is part of an associated object (a joined field), you will likely get an error processing the request. You can recognize a joined field by the period in the result element when you list objects, as shown:

<data listtype="employee" count="82" totalcount="82" numremaining="0" resultId="">
    <employee>
        <RECORDNO>38</RECORDNO>
        ...
        <PERSONALINFO.FIRSTNAME>Melissa</PERSONALINFO.FIRSTNAME>
        <PERSONALINFO.INITIAL>Q</PERSONALINFO.INITIAL>
        <PERSONALINFO.LASTNAME>Fandel</PERSONALINFO.LASTNAME>
        ...

For such fields, use the query function. For example, the following returns the employee record for the above first and last names:

<query>
    <object>EMPLOYEE</object>
    <filter>
        <and>
            <equalto>
                <field>personalinfo.firstname</field>
                <value>Melissa</value>
            </equalto>
            <equalto>
                <field>personalinfo.lastname</field>
                <value>Fandel</value>
            </equalto>
        </and>
    </filter>
</query>

How do you add a contact to the Contact List for a customer?

The generic functions for creating and updating customers do not support adding to the Contact List. You can use the legacy functions (create_customer / update_customer) for this purpose.

Can I update a statistical journal entry via the API?

Yes, but be aware that the update is treated as a complete replacement of any entries. Be careful you pass every entry you want to keep so you do not clear out the whole thing, for example:

<update>
    <GLBATCH>
        <RECORDNO>21</RECORDNO>
        <BATCH_DATE>03/31/2016</BATCH_DATE>
        <BATCH_TITLE>Headcount 03/31/2016</BATCH_TITLE>
        <ENTRIES>
            <GLENTRY>
                <ACCOUNTNO>HEADS</ACCOUNTNO>
                <DEPARTMENT>ADMIN</DEPARTMENT>
                <LOCATION>100</LOCATION>
                <TR_TYPE>1</TR_TYPE>
                <AMOUNT>2.00</AMOUNT>
                <DESCRIPTION>Headcount 03/31/2016</DESCRIPTION>
            </GLENTRY>
        </ENTRIES>
    </GLBATCH>
</update>

Note that GLBATCH is used for all of the types of journal entry objects, so make sure you are providing the correct RECORDNO.

Why aren’t my dates working correctly?

Dates in Sage Intacct do not have associated timezones. Third-party integrators are responsible for any adjustments to account for timezone differences. For example, if an integration stores everything in GMT and the client requires a different timezone, the integrator is responsible for translating the dates to the correct timezone for the client. In addition, ISO 8601 date formats are not supported in Sage Intacct. An integration that uses these formats must translate them into accepted date formats. See Dates for more information.

What field do I use for attachments?

In the Sage Intacct UI, the Attachments label indicates that you can provide supporting documents. However, in XML API calls, the corresponding field name is SUPDOCID.

How do I update a record at the entity level for a multi-entity shared company?

Add a location ID to your login. See login element for an example.

General Ledger

GL Outlier Detection

If GL Outlier Detection is enabled for a company, information about outliers is included in journal entries and allocation splits.

For example, the following shows part of a read response on a journal entry with outlier information (PREDICTIONS) for a SPLIT:

<GLBATCH>
    ...
    <ENTRIES>
        <glentry>
        ...
            <SPLIT>
                <RECORDNO>267</RECORDNO>
                ...
                <AMOUNT>50</AMOUNT>
                <TRX_AMOUNT>50</TRX_AMOUNT>
                <SPAMOUNT>50</SPAMOUNT>
                <SPBASEAMOUNT>50</SPBASEAMOUNT>
                <SPLOCATIONID>Central Region--Central Region</SPLOCATIONID>
                <SPDEPARTMENTID>1--Accounting</SPDEPARTMENTID>
                <PREDICTIONS>
                    <glentryprediction>
                        <RECORDNO>13</RECORDNO>
                        <GLENTRYKEY>267</GLENTRYKEY>
                        <GLBATCHKEY>84</GLBATCHKEY>
                        <FEATUREID>GLOD</FEATUREID>
                        <ISOUTLIER>!</ISOUTLIER>
                        <REASON>This Department with this Location is unusual</REASON>
                    </glentryprediction>
                </PREDICTIONS>
            </SPLIT>
        ...
        </glentry>
    </ENTRIES>
</GLBATCH>

More information about GL Outlier Detection is available in the Sage Intacct product help.

Customization Services

Are the injections in my Smart Event condition correct?

If you are having trouble setting up a condition, it’s useful to verify that your injections are correct. You can modify the Smart Event to send you an email that provides the injections in the email body. For example, if your condition uses {!APBILL.VENDORNAME!}, include this in your email:

The vendor name is: {!APBILL.VENDORNAME!}

Why aren’t integration codes working for picklist fields on a standard object?

Using name/value pairs for picklist fields is not supported for custom picklists on standard objects. This capability is only supported on custom picklists for custom objects (Platform Services).

Can I use a smart event to pull data from the first line of the line item section into a field in the header section?

You can create an API Smart Event on the detail line, and the event criteria can include LINE_NO = 0 (the underlying data is 0-based even though the UI starts at line 1). The API call in the API event can look something like this:

<update_potransaction key="{!PODOCUMENTENTRY.PODOCUMENT.DOCID!}">
<projectid>{!PODOCUMENTENTRY.PROJECTID!}</projectid>
</update_potransaction>

For more info, check out some of the Customization Services Smart Event examples and Smart Rule examples.

If you only need this information in the printed PDF, you can get creative with Microsoft Word merge field codes. A SET field nested in an IF statement looking for the first line does the trick. See the Microsoft documentation on merge fields for more information.

How can I restrict a record to only be created privately in an entity, instead of at the root/top level?

Check out the Prevent creating records at the top level section in the Customization Services Smart Rule examples.

Platform Services

How do I get the targets of to-one relationships when working with dimension restrictions?

The getDimensionRestrictedData function lists the IDs of related dimensions that are the target(s) of to-many relationships from the source dimension, but does not list the related dimensions that are the targets of to-one relationships. Consider the following example, which shows the relationships for three UDDs.

relationships between UDDs

The following call on the PARTNER_TYPE dimension with the value of Full Service returns the IDs for all the PARTNERS that are the targets of to-many relationships:

<getDimensionRestrictedData>
    <DimensionValue>
        <dimension>PARTNER_TYPE</dimension>
        <value>Full Service</value>
    </DimensionValue>
</getDimensionRestrictedData>

Three PARTNER dimension values are returned (by ID), but no LINE_OF_BUSINESS values are:

<RestrictedData>
    <dimension>PARTNER</dimension>
    <value>10008</value> <!--  Almanido LLP PARTNER --> 
    <value>10122</value> <!-- BigBoy LLP PARTNER -->
    <value>10009</value> <!-- Sarderra PARTNER-->
</RestrictedData>

To get to-one relationships, list the dimensions using readByQuery and look for related fields (Rfields) in the output that were not listed by getDimensionRestrictedData. For example, to list all PARTNER_TYPE dimensions:

    <readByQuery>
      <object>PARTNER_TYPE</object>
      <fields>*</fields>
      <query/>
      <pagesize>100</pagesize>
    </readByQuery>

The results for the Full Service dimension show that the Rline_of_business to-one relationship has the Channel dimension value. The Rpartner field lists the three names of the PARTNER dimension values whose IDs were previously returned by getDimensionRestrictedData:

<partner_type>
    <name>Full Service</name>
    <comment></comment>
    ...
    <Rline_of_business>Channel</Rline_of_business>
    <Rpartner>Almanido LLP, Sarderra, BigBoy LLP</Rpartner>
    ...
</partner_type>

How do I set relationship values for dimensions, custom objects, or standard objects?

Continuing with our example (from above):

relationships between UDDs

You might set a to-one relationship from the given PARTNER_TYPE to the target LINE_OF_BUSINESS as follows:

 <update>
    <PARTNER_TYPE>
          <id>10120</id>
          <Rline_of_business>10002</Rline_of_business>
    </PARTNER_TYPE>
 </update>

You can also set the values of a to-many relationship from the given LINE_OF_BUSINESS to the target PARTNER_TYPE records:

<update>
  <LINE_OF_BUSINESS>
      <id>10002</id>
      <Rpartner_type>10005,10006,10007</Rpartner_type>
  </LINE_OF_BUSINESS>
</update>

If you read the LINE_OF_BUSINESS record, you can see the values you just set:

<LINE_OF_BUSINESS>
    <name>Direct</name>
    <comment></comment>
    ...
    <Rpartner_type>Services, Software, Full Service</Rpartner_type>
    ...

You can typically use these approaches when setting relationships between custom and standard objects. For example, the following sets multiple target TEST_OBJECT records on the given APBILL:

<update>
  <APBILL>
      <recordno>259</recordno>
      <RTEST_OBJECT>10027,10032</RTEST_OBJECT>
  </APBILL>
</update>

Construction Application

How do I interpret fields for Purchasing or Order Entry transactions that accept change orders? (Construction subscription)

When you read a source Purchasing or Order Entry transaction in the API, new output parameters help identify the changes that led to the current state:

Transaction (header) fields:

Transaction line fields:

Accounting terminology for non-US countries

How do I map accounting terms from my country to US accounting terms?

Refer to the mapping table in the Sage Intacct product help (AU, GB only).

Miscellaneous

How can I search across the Sage Intacct Developer Community group?

  1. Click the search icon (magnifying glass) in the upper right of the Sage Intacct Developers group page.

  2. On the resulting page, click Search Feeds on the left, provide the search term, then click Search Feeds, which is now on the right side:

    Web Services authorization list

Provide feedback