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?

See Requirements for details.


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.

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.

The readByQuery function lets you get unique keys (typically record numbers) for one or more main records based on a query. You can then supply such a key to the read function to get more information for the main record, including details about its owned and related objects.

For example, the following results returned by getting an APBILL show its 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>

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 that is part of an associated object (a joined field), you will likely get a 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 get_list function to query. For example, the following returns the employee record for the above first and last names:

<get_list object="employee">
    <filter>
        <expression>
            <field>personalinfo.firstname</field>
            <operator>=</operator>
            <value>Melissa</value>
        </expression>
        <expression>
            <field>personalinfo.lastname</field>
            <operator>=</operator>
            <value>Fandel</value>
        </expression>
    </filter>
</get_list>

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.


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 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 examples.


Platform Services

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

NEW!

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?

NEW!

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>

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