tools/sdk-net.md

---
title: Sage Intacct SDK for .NET | Sage Intacct Developer
url: https://developer.intacct.com/tools/sdk-net/
---

# Sage Intacct SDK for .NET | Sage Intacct Developer

Overview

Getting Started

List AR Invoices

List Vendors (Legacy)

CRUD Customer

Custom Object Function

Troubleshooting

* Overview
* System Requirements
* Quick Install
* Client model
* Client configuration
* Request configuration
* API functions
* Credentials
  + Hard-coded credentials
  + Environment variables
  + Credentials file and profiles
  + Session credentials
  + Client/entity slide-in credentials
* Error handling
* Logging
* What’s next?

---

## Overview

Get going quickly using Web Services with the Sage Intacct SDK for .NET.

The SDK allows you to work with pre-built objects instead of directly with the underlying XML API.

The Sage Intacct SDK for .NET is licensed under Apache v2.0. Please read and accept this before using the SDK.

This topic provides a high-level overview of the SDK. When you are ready to start coding, try the getting started example and keep the reference documentation handy for delving deeper.

If the SDK does not provide the functionality you need, you can write your own classes that implement functions. See Custom Object Function for an example.

---

## System Requirements

* An active Sage Intacct Web Services Developer license, which includes a Web Services sender ID and password. If you need a developer license, contact your account manager.
* Web Services authorization for that sender ID in the target company
* .NET Core >=2.0 or .NET Framework >=4.6.1. The SDK targets .NET Standard 2.0.
* An up-to-date NuGet client:
  + NuGet 5.7.0+
  + Visual Studio 2019 version 16.0
  + dotnet.exe (.NET SDK 2.1.0+)
  + JetBrains Rider 2020.2+

---

## Quick Install

Install the SDK using NuGet:

```xml
PM> Install-Package Intacct.SDK
```

You can also visit the NuGet package page.

---

## Client model

The SDK uses a *client* model for sending requests to the gateway. You construct a client, optionally configure it, then use it to execute your requests.

There are two kinds of clients:

* `OnlineClient` can perform multiple create, update, and delete operations. 99% of all developers will use this client.
* `OfflineClient` just like the OnlineClient except it uses a predefined Policy ID with Sage Intacct to make Offline Web Services requests.

Both clients provide an `execute` call that sends a single API function, and an `executeBatch` function for sending multiple functions. For usage information, see the getting started example.

---

## Client configuration

When you construct a client, you can optionally provide configuration information in a client configuration object. This object can provide Web Services credentials, company credentials (including an optional entity ID), a session ID, logger choices, the gateway endpoint, and so forth.

```xml
ClientConfig clientConfig = new ClientConfig() // Create the config and set a session ID
{
    SessionId = "SomeSessionFromTheInternet..",
};
OnlineClient client = new OnlineClient(clientConfig); // Construct the client with the config
```

During client instantiation, the default endpoint (`https://api.intacct.com/ia/xml/xmlgw.phtml`) is used.

---

## Request configuration

To configure the request that is sent to the gateway by the SDK, create a request configuration instance and pass it in when you call `Execute` or `ExecuteBatch`.

You can use a request configuration to set a control ID for the request, specify a transport policy ID (for an offline client), set a time-out value, and so forth.

```xml
RequestConfig requestConfig = new RequestConfig() // Create the request config and set a control ID
{
    ControlId = "testing123",
};
Task<OnlineResponse> task = client.Execute(query, requestConfig); // Execute the request
task.Wait(); // Wait for the async task
OnlineResponse response = task.Result;
```

If you do not supply a request configuration, the following defaults are used.

```xml
ControlId = (DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1))).TotalSeconds.ToString();
Encoding = Encoding.GetEncoding("UTF-8");
MaxRetries = 5;
MaxTimeout = TimeSpan.FromSeconds(300);
NoRetryServerErrorCodes = new int[] { 524 }; // CDN cut the connection, but the system is still processing the request
PolicyId = "";
Transaction = false;
UniqueId = false;
```

For a high-level understanding of how you can configure requests, see XML Requests.

---

## API functions

The underlying API functions are made available through classes in the `Intacct.SDK.Functions` namespace. The classes that provide object-specific functionality are under feature namespaces, and the classes that provide generic functionality are in a single namespace. For example, object-specific classes such as `CustomerCreate`, `JournalEntryCreate`, and `ContactUpdate` are under their respective categories, and generic classes such as `Read` and `ReadByQuery` are under a single `Common` namespace.

All these classes implement the `IFunction` interface and extend `AbstractFunction`, which gives them access to an XML writer that translates the objects into XML.

The clients can execute any class implementations of the `IFunction`. If the `Intacct.SDK.Functions` classes do not meet your needs, you are welcome to write your own classes that implement this interface. Check out Custom Object Function for more on this.

The following example constructs a `ReadByQuery` instance that queries for vendors:

```xml
ReadByQuery query = new ReadByQuery()
{
    ObjectName = "VENDOR",
    PageSize = 1, // Keep the count to just 1 for the example
    Fields =
    {
        "RECORDNO",
        "VENDORID",
        "NAME"
    }
};
```

---

## Credentials

There are several ways you can supply Web Services and company credentials (including an optional entity ID) to the SDK.

* Pass in a client configuration with hard-coded credentials when you construct your client.
* Use environment variables to store your credentials.
* Use a credentials INI file to store various *profiles*, which are groupings of your credentials.
* Validate and use a session ID received from a Smart Event or trigger.

You can mix and match how credentials are loaded. For example, you might set Web Services credentials in your environment, then load company login credentials from a credentials file. You can also pass company credentials directly to the `ClientConfig` from a different source.

### Hard-coded credentials

The following shows how to provide hard-coded Web Services and company credentials using `ClientConfig`:

```xml
ClientConfig config = new ClientConfig()
{
    SenderId = "testsenderid",
    SenderPassword = "pass123!",
    CompanyId = "testcompany",
    // EntityId = "testentity",
    UserId = "testuser",
    UserPassword = "testpass",
};
```

**Note:** You should make every effort to securely store your credentials and not hard code them.

### Environment variables

You can use environment variables to specify credentials directly or via named profiles in a credentials file. You can also override the default gateway endpoint using an environment variable.

| Variable | Description |
| --- | --- |
| `INTACCT_SENDER_ID`, `INTACCT_SENDER_PASSWORD` | Web Services credentials. |
| `INTACCT_COMPANY_ID`, `INTACCT_ENTITY_ID`, `INTACCT_USER_ID`, `INTACCT_USER_PASSWORD` | Company login credentials. |
| `INTACCT_SENDER_PROFILE`, `INTACCT_COMPANY_PROFILE`,`INTACCT_PROFILE` | Names of profiles in a credentials file. Using these variables causes the client to load credentials from the given profile in the credentials file in use. |
| `INTACCT_ENDPOINT_URL` | Overrides the default endpoint URL. |

### Credentials file and profiles

If not otherwise supplied, the SDK will look for credentials in the `default` profile in a credentials file in the default location:

*home\_dir*`/.intacct/credentials.ini`

The following shows the format for the file. Each profile starts with a name in brackets followed by key/value pairs.

```xml
[default]
sender_id = mysenderid
sender_password = mysenderpassword
company_id = mycompanyid
user_id = myuserid
user_password = myuserpassword

[demo987654321]
company_id = demo987654321
user_id = myuserid
user_password = myuserpassword

[demo987654321_entityA]
company_id = demo987654321
user_id = myuserid
user_password = myuserpassword
entity_id = entityA

[dev123]
sender_id = mysenderid
sender_password = mysenderpassword
endpoint_url = https://api.intacct.com/ia/xml/xmlgw.phtml
```

You can provide values for the following in any profile:

* `sender_id`
* `sender_password`
* `endpoint_url`
* `company_id`
* `entity_id`
* `user_id`
* `user_password`

#### Override the location for the credentials file

You can override the default location of the credentials file with the `ClientConfig.ProfileFile` string property:

```xml
ClientConfig config = new ClientConfig()
{
    ProfileFile = Path.Combine(Directory.GetCurrentDirectory(), "SomeFileNotInSourceControl.ini"),
    ProfileName = "demo987654321",
};

OnlineClient client = new OnlineClient(config);
```

#### Use a non-default profile name

As shown above, you can specify a non-default profile to use with `ClientConfig.ProfileName`. You can also use the `INTACCT_SENDER_PROFILE`, `INTACCT_COMPANY_PROFILE`, or `INTACCT_PROFILE` environment variables for this purpose.

### Session credentials

Some integrations are triggered by Smart Event HTTP notifications. Such notifications typically include a session ID and endpoint URL.

**Warning:** Do not blindly trust session IDs that your server receives over the internet. Always validate these parameters before using them.

You can use the static `SessionProvider.Factory` function to validate that a session ID is valid and that the endpoint URL is a `*.intacct.com` domain.

```xml
try
{
    ClientConfig config = new ClientConfig();
    // Web Services credentials are loaded from the environment
    // Assume the following endpoint and session ID came from an HTTP POST (after using sanitize filters)
    config.EndpointUrl = "https://api.intacct.com/ia/xml/xmlgw.phtml";
    config.SessionId = "SomeSessionFromTheInternet..";

    // Validate that the session ID is valid and the endpoint URL is a *.intacct.com domain
    Task<ClientConfig> validateTask = SessionProvider.Factory(config);
    validateTask.Wait(); // Wait for the async task
    ClientConfig sessionConfig = validateTask.Result;

    // Create a client with the validated session credentials in a new ClientConfig
    OnlineClient client = new OnlineClient(sessionConfig);

    // Execute some other API functions
}
catch (Exception e)
{
    Console.WriteLine(e);
    throw;
}
```

### Client/entity slide-in credentials

The following table shows another way to provide entity slide-in credentials using the pipe character (`|`) to separate the IDs.

| Description | Company ID |
| --- | --- |
| Client linked from your console | `myConsoleId|clientCompanyId` |
| Entity level of a company | `companyId|entityId` |
| Entity level of a company for a client linked from your console | `myConsoleId|clientCompanyId|entityId` |

---

## Error handling

There are several categories of errors that can occur when sending requests to the gateway. Your code should handle these.

| Exception | Description |
| --- | --- |
| `IntacctException` | An IntacctException extends the `System.Exception` and is likely an issue with Sage Intacct itself. |
| `ResponseException` | A ResponseException extends the `System.Exception` and is likely a problem with the client or request configuration. For example, you might have invalid Web Services credentials or invalid company credentials. |
| `ResultException` | A ResultException extends the `Intacct.SDK.Exceptions.ResponseException` and is likely a problem with an API function being executed. |

The `Execute` and `ExecuteBatch` functions have some built-in error handling for the results (`Result` instances) coming back:

* `Execute` allows you to execute one function to the Sage Intacct API. This will also grab the `Result` and call `EnsureStatusSuccess` to check for any API errors executing the single API function.
* `ExecuteBatch` allows you to execute multiple functions to the Sage Intacct API in the same request.
  + If the passed `RequestConfig.Transaction` property evaluates to `true`, it will loop through each `Result` and call `EnsureStatusNotFailure` in an attempt to check for any API errors that are status `failed` and not `aborted`.
  + If the passed `RequestConfig.Transaction` property evaluates to `false` (default), you will need to do your own `Result` looping and error checking.

---

## Logging

As of v3.0.0, the SDK uses Microsoft Extensions Logging.

A logger can be set using the `ClientConfig.Logger` function. If set, the SDK will add entries for all HTTP request and responses with the Sage Intacct API endpoint. By default, the SDK writes log entries using the `debug` log level. To change the level, use `ClientConfig.LogLevel`. If you change the level, consider changing the format to omit the XML request and response as these can get quite large.

To format the entries differently, construct a new `Intacct.SDK.Logging.MessageFormatter` object and add it to the config with `ClientConfig.LogMessageFormatter`.

The logger will attempt to redact sensitive info, like passwords, from the debug entries. Regardless, access to logs should always be restricted.

The examples implement Microsoft Extensions Logging through NLog to utilize writing logs to a file. For example, getting started writes log messages to `Intacct.Examples/bin/Debug/netcoreappX.X/intacct.log`. The log file name and path are configured via `Intacct.Examples/nlog.config` in the project directory.

---

## What’s next?

* Try the getting started example.

Provide feedback