sync-for-expenses

Sync for Expenses

Embedded accounting integrations for corporate card providers.

Summary

Expenses: The API for Codat's Expenses solution.

Expenses is an API and a set of supporting tools. It has been built to enable corporate card and expense management platforms to provide high-quality integrations with multiple accounting software through a standardized API.

Explore solution | See our OpenAPI spec

Not seeing the endpoints you're expecting? We've reorganized our solutions, and you may be using a different version of Expenses.

Endpoints

Endpoints	Description
Companies	Create and manage your SMB users' companies.
Connections	Create new and manage existing data connections for a company.
Configuration	View and manage mapping configuration and defaults for expense transactions.
Sync	Monitor the status of data syncs.
Expenses	Create and update transactions that represent your customers' spend.
Transfers	Create and update transactions that represent the movement of your customers' money.
Reimbursements	Create and update transactions that represent your customers' repayable spend.
Attachments	Attach receipts to a transaction for a complete audit trail.
Transaction status	Monitor the status of individual transactions in data syncs.
Manage data	Control and monitor the retrieval of data from an integration.
Push operations	View historic push operations.
Accounts	Create accounts and view account schemas.
Customers	Get, create, and update customers.
Suppliers	Get, create, and update suppliers.

SDK Installation

NuGet

To add the NuGet package to a .NET project:

dotnet add package Codat.Sync.Expenses

Locally

To add a reference to a local instance of the SDK in a .NET project:

dotnet add reference Codat/Sync/Expenses/Codat.Sync.Expenses.csproj

Example Usage

SDK Example Usage

Example

using Codat.Sync.Expenses;
using Codat.Sync.Expenses.Models.Components;
using Codat.Sync.Expenses.Models.Requests;

var sdk = new CodatSyncExpenses(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Available Resources and Operations

Available methods

Accounts

Create - Create account
GetCreateModel - Get create account model

Adjustments

Create - Create adjustment transaction

Attachments

Upload - Upload attachment

BankAccounts

Create - Create bank account
GetCreateModel - Get create bank account model

Companies

List - List companies
Create - Create company
Replace - Replace company
Update - Update company
Delete - Delete a company
Get - Get company

CompanyInfo

Get - Get company info

Configuration

Get - Get company configuration
Set - Set company configuration

Connections

List - List connections
Create - Create connection
Get - Get connection
Delete - Delete connection
Unlink - Unlink connection
CreatePartnerExpenseConnection - Create partner expense connection

Customers

List - List customers
Get - Get customer
Create - Create customer
Update - Update customer

Expenses

Create - Create expense transaction
Update - Update expense transactions

ManageData

RefreshAllDataTypes - Refresh all data
Get - Get data status
RefreshDataType - Refresh data type
ListPullOperations - List pull operations
GetPullOperation - Get pull operation

MappingOptions

GetMappingOptions - Mapping options

PushOperations

List - List push operations
Get - Get push operation

Reimbursements

Create - Create reimbursable expense transaction
Update - Update reimbursable expense transaction

Suppliers

List - List suppliers
Get - Get supplier
Create - Create supplier
Update - Update supplier

Sync

GetLastSuccessfulSync - Last successful sync
GetLatestSync - Latest sync status
List - List sync statuses
Get - Get sync status

TransactionStatus

List - List sync transactions
Get - Get sync transaction

Transfers

Create - Create transfer transaction

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverUrl: string optional parameter when initializing the SDK client instance. For example:

using Codat.Sync.Expenses;
using Codat.Sync.Expenses.Models.Components;
using Codat.Sync.Expenses.Models.Requests;

var sdk = new CodatSyncExpenses(
    serverUrl: "https://api.codat.io",
    authHeader: "Basic BASE_64_ENCODED(API_KEY)"
);

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name	Type	Scheme
`AuthHeader`	apiKey	API key

To authenticate with the API the AuthHeader parameter must be set when initializing the SDK client instance. For example:

using Codat.Sync.Expenses;
using Codat.Sync.Expenses.Models.Components;
using Codat.Sync.Expenses.Models.Requests;

var sdk = new CodatSyncExpenses(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply pass a RetryConfig to the call:

using Codat.Sync.Expenses;
using Codat.Sync.Expenses.Models.Components;
using Codat.Sync.Expenses.Models.Requests;

var sdk = new CodatSyncExpenses(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(
    retryConfig: new RetryConfig(
        strategy: RetryConfig.RetryStrategy.BACKOFF,
        backoff: new BackoffStrategy(
            initialIntervalMs: 1L,
            maxIntervalMs: 50L,
            maxElapsedTimeMs: 100L,
            exponent: 1.1
        ),
        retryConnectionErrors: false
    ),
    request: req
);

// handle response

If you'd like to override the default retry strategy for all operations that support retries, you can use the RetryConfig optional parameter when intitializing the SDK:

using Codat.Sync.Expenses;
using Codat.Sync.Expenses.Models.Components;
using Codat.Sync.Expenses.Models.Requests;

var sdk = new CodatSyncExpenses(
    retryConfig: new RetryConfig(
        strategy: RetryConfig.RetryStrategy.BACKOFF,
        backoff: new BackoffStrategy(
            initialIntervalMs: 1L,
            maxIntervalMs: 50L,
            maxElapsedTimeMs: 100L,
            exponent: 1.1
        ),
        retryConnectionErrors: false
    ),
    authHeader: "Basic BASE_64_ENCODED(API_KEY)"
);

ListCompaniesRequest req = new ListCompaniesRequest() {
    Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
    OrderBy = "-modifiedDate",
    Tags = "region=uk && team=invoice-finance",
};

var res = await sdk.Companies.ListAsync(req);

// handle response

Error Handling

CodatSyncExpensesException is the base exception class for all HTTP error responses. It has the following properties:

Property	Type	Description
`Message`	string	Error message
`StatusCode`	int	HTTP status code
`Headers`	HttpResponseHeaders	HTTP headers
`ContentType`	string?	HTTP content type
`RawResponse`	HttpResponseMessage	HTTP response object
`Body`	string	HTTP response body

Some exceptions in this SDK include an additional Payload field, which will contain deserialized custom error data when present. Possible exceptions are listed in the Error Classes section.

Example

using Codat.Sync.Expenses;
using Codat.Sync.Expenses.Models.Components;
using Codat.Sync.Expenses.Models.Errors;
using Codat.Sync.Expenses.Models.Requests;

var sdk = new CodatSyncExpenses(authHeader: "Basic BASE_64_ENCODED(API_KEY)");

try
{
    ListCompaniesRequest req = new ListCompaniesRequest() {
        Query = "id=e3334455-1aed-4e71-ab43-6bccf12092ee",
        OrderBy = "-modifiedDate",
        Tags = "region=uk && team=invoice-finance",
    };

    var res = await sdk.Companies.ListAsync(req);

    // handle response
}
catch (CodatSyncExpensesException ex)  // all SDK exceptions inherit from CodatSyncExpensesException
{
    // ex.ToString() provides a detailed error message
    System.Console.WriteLine(ex);

    // Base exception fields
    HttpResponseMessage rawResponse = ex.RawResponse;
    HttpResponseHeaders headers = ex.Headers;
    int statusCode = ex.StatusCode;
    string? contentType = ex.ContentType;
    var responseBody = ex.Body;

    if (ex is ErrorMessage) // different exceptions may be thrown depending on the method
    {
        // Check error data fields
        ErrorMessagePayload payload = ex.Payload;
        long StatusCode = payload.StatusCode;
        string Service = payload.Service;
        // ...
    }

    // An underlying cause may be provided
    if (ex.InnerException != null)
    {
        Exception cause = ex.InnerException;
    }
}
catch (System.Net.Http.HttpRequestException ex)
{
    // Check ex.InnerException for Network connectivity errors
}

Error Classes

Primary exceptions:

CodatSyncExpensesException: The base class for HTTP error responses.
- ErrorMessage: Your query parameter was not correctly formed.

Less common exceptions (2)

System.Net.Http.HttpRequestException: Network connectivity error. For more details about the underlying cause, inspect the ex.InnerException.
Inheriting from CodatSyncExpensesException:
- ResponseValidationError: Thrown when the response data could not be deserialized into the expected type.

Custom HTTP Client

The C# SDK makes API calls using an ISpeakeasyHttpClient that wraps the native HttpClient. This client provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The ISpeakeasyHttpClient interface allows you to either use the default SpeakeasyHttpClient that comes with the SDK, or provide your own custom implementation with customized configuration such as custom message handlers, timeouts, connection pooling, and other HTTP client settings.

The following example shows how to create a custom HTTP client with request modification and error handling:

using Codat.Sync.Expenses;
using Codat.Sync.Expenses.Utils;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

// Create a custom HTTP client
public class CustomHttpClient : ISpeakeasyHttpClient
{
    private readonly ISpeakeasyHttpClient _defaultClient;

    public CustomHttpClient()
    {
        _defaultClient = new SpeakeasyHttpClient();
    }

    public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken? cancellationToken = null)
    {
        // Add custom header and timeout
        request.Headers.Add("x-custom-header", "custom value");
        request.Headers.Add("x-request-timeout", "30");
        
        try
        {
            var response = await _defaultClient.SendAsync(request, cancellationToken);
            // Log successful response
            Console.WriteLine($"Request successful: {response.StatusCode}");
            return response;
        }
        catch (Exception error)
        {
            // Log error
            Console.WriteLine($"Request failed: {error.Message}");
            throw;
        }
    }

    public void Dispose()
    {
        _httpClient?.Dispose();
        _defaultClient?.Dispose();
    }
}

// Use the custom HTTP client with the SDK
var customHttpClient = new CustomHttpClient();
var sdk = new CodatSyncExpenses(client: customHttpClient);

You can also provide a completely custom HTTP client with your own configuration:

using Codat.Sync.Expenses.Utils;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

// Custom HTTP client with custom configuration
public class AdvancedHttpClient : ISpeakeasyHttpClient
{
    private readonly HttpClient _httpClient;

    public AdvancedHttpClient()
    {
        var handler = new HttpClientHandler()
        {
            MaxConnectionsPerServer = 10,
            // ServerCertificateCustomValidationCallback = customCertValidation, // Custom SSL validation if needed
        };

        _httpClient = new HttpClient(handler)
        {
            Timeout = TimeSpan.FromSeconds(30)
        };
    }

    public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken? cancellationToken = null)
    {
        return await _httpClient.SendAsync(request, cancellationToken ?? CancellationToken.None);
    }

    public void Dispose()
    {
        _httpClient?.Dispose();
    }
}

var sdk = CodatSyncExpenses.Builder()
    .WithClient(new AdvancedHttpClient())
    .Build();

For simple debugging, you can enable request/response logging by implementing a custom client:

public class LoggingHttpClient : ISpeakeasyHttpClient
{
    private readonly ISpeakeasyHttpClient _innerClient;

    public LoggingHttpClient(ISpeakeasyHttpClient innerClient = null)
    {
        _innerClient = innerClient ?? new SpeakeasyHttpClient();
    }

    public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken? cancellationToken = null)
    {
        // Log request
        Console.WriteLine($"Sending {request.Method} request to {request.RequestUri}");
        
        var response = await _innerClient.SendAsync(request, cancellationToken);
        
        // Log response
        Console.WriteLine($"Received {response.StatusCode} response");
        
        return response;
    }

    public void Dispose() => _innerClient?.Dispose();
}

var sdk = new CodatSyncExpenses(client: new LoggingHttpClient());

The SDK also provides built-in hook support through the SDKConfiguration.Hooks system, which automatically handles BeforeRequestAsync, AfterSuccessAsync, and AfterErrorAsync hooks for advanced request lifecycle management.

Support

If you encounter any challenges while utilizing our SDKs, please don't hesitate to reach out for assistance. You can raise any issues by contacting your dedicated Codat representative or reaching out to our support team. We're here to help ensure a smooth experience for you.

Name		Name	Last commit message	Last commit date
parent directory ..
.speakeasy		.speakeasy
Codat/Sync/Expenses		Codat/Sync/Expenses
docs		docs
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Codat.Sync.Expenses.sln		Codat.Sync.Expenses.sln
NUGET.md		NUGET.md
README.md		README.md
RELEASES.md		RELEASES.md
USAGE.md		USAGE.md
files.gen		files.gen
global.json		global.json

FilesExpand file tree

sync-for-expenses

Directory actions

More options

Directory actions

More options

Latest commit

History

sync-for-expenses

Folders and files

parent directory

Sync for Expenses

Summary

Endpoints

Table of Contents

SDK Installation

NuGet

Locally

Example Usage

SDK Example Usage

Example

Available Resources and Operations

Server Selection

Override Server URL Per-Client

Authentication

Per-Client Security Schemes

Retries

Error Handling

Example

Error Classes

Custom HTTP Client

Support

Library generated by Speakeasy