Foundation Accounting APIs

Foundation Accounting API provides programmatic access to Foundation's Accounting Product. Built on modern REST principles, the API enables developers to integrate core accounting functions directly into their applications and workflows.

Products

Within the developer portal, APIs are bundled within a product. Products are grouped with a focus of like functionality. Depending the permissions granted by the Foundation team may only be granted limited access to the available products and the APIs within.

To access the FOUNDATION API, a subscription key is required. Subscription keys are scoped to limit access based on the need. The API Support team administrates these subscription keys by providing a primary and secondary key during onboarding. Separate keys will be needed to access sandboxes and production.

Your subscription key will be required as either a header or query parameter to each API request in addition to the Bearer token.

Open API Specifications (OAS v3.x)

During the Commercial Evaluation phase, someone from your organization will be given access to the Developer Portal where they can view our OpenAPI specifications. You may download the specifications from the API details page by (1) selecting the API definition dropdown and (2) selecting the Open API version you want to download.

The API document then downloads to your browser download folder. You can import this document into any tool that supports importing Open API Specification.

Versioning

The Foundation API version is based on Path Versioning.

Breaking changes to the APIs may occur. These changes will be communicated in close collaboration with our development team. Breaking changes will be released with the newest version of APIs and may become available at the path level.

For example, Foundation API Accounts Payable Vendors would be accessible at the following path:

"../foundation/ap/v1/vendors"

If the Foundation software team plans a breaking change, advanced communication will be provided, and the endpoint will be updated with the new version on a schedule.

Authentication

Foundation API uses OpenID Connect Core 1.0 through Azure Active Directory Business to Consumer (B2C) to provide secure logins for Foundation customers.

Authentication Basics

All authentication methods require the user to log in to authorize an integration before changing FOUNDATION data. This means integrators are required to use a web portal that redirects to your application.

Desktop Applications

If you have a desktop application integration, you need to use a web view or web application to retrieve a Foundation API access token for your integration.

In addition to your bearer token, Foundation API endpoints require a connection GUID. An endpoint called “List Cloud Clients” is located in the Foundation Core. This endpoint allows an authenticated user to provide their CRM client ID, which is provided by Foundation, provides a "casConnectionGuid". This connection guid is required as a header for subsequent requests.

TIP

Located in the List Cloud Clients endpoint API documentation are additional details describing how to obtain the connection GUID.

TIP

Connection GUIDS can be rotated periodically for security purposes. It is recommended that each time you create a new Foundation API session that you pull the most current connection GUID and not locally store this value.

Client Credentials Flow

Applications integrating through a background process use the Client Credentials grant flow. In this flow, an authorization request is made as a confidential application instead of under a specific user. To use this flow, your application must be confidential or have secured access to a confidential client.

Application Types

Public Clients	Confidential Clients
Desktop apps	Backend-driven web applications
Mobile apps	Web APIs
Wearable apps	Serverless Functions
Single-page web applications	Web daemons and services

If your application is one of the types listed above in the left-side column, it must implement a user flow such as the Code Grant Flow. However, if your public application already has a user flow, and authenticates that user with a confidential client, you could then use that confidential client to implement the Client Credentials flow. This would enable you to make requests that flow through the user interface of your public client to your confidential client and perform background processes using your confidential client. A common case of this would be a Web Application communicating with a Web API.

If you are not able to authenticate as a confidential client, please contact (800) 811-5926 and request the ability to use the Code Grant Flow as an alternative for public clients. Authentication security will be reviewed as part of the Integration Review step in the Onboarding Process.

Sample Request

curl --location --request GET \
'https://fslenterprisedr.b2clogin.com/fslenterprisedr.onmicrosoft.com/B2C_1A_CAS_SIGNIN/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=https://fslenterprisedr.onmicrosoft.com/foundation/.default' \
--data-urlencode 'client_id={{MyApplicationId}}' \
--data-urlencode 'client_secret={{MyClientSecret}}'

Authorization Code Grant Flow

The Authorization Code Flow for Foundation API enables a secure, two-step access to Foundation resources with the resource owner's permission.

We recommend Microsoft's documentation for successfully obtaining an access code, exchanging it for an access token, and refreshing the access token.

Required Parameters

You need the following information to follow the authorization code flow guide:

{tenantId} = fslenterprisedr
{policy} = B2C_1A_CAS_SIGNIN
client_id = {Your clientId provided in your Welcome Package}
redirect_uri = {your URL Encoded redirectURI you provided to the Foundation API Support Team}
scope = openid%20https%3A%2F%2Ffslenterprisedr.onmicrosoft.com%2FFoundation%2Ffoundation.access

Note:

Replace the sample values above with your actual tenant, policy, client ID, and redirect URI before implementing in production.

Redirect URL

Redirect URL Configuration

If the redirect URL is new or different from the one(s) you provided during onboarding, you need to contact Foundation API Support at (800) 811-5926 to have an additional redirect URL added.

For sandbox testing, we provide the redirect URL "https://jwt.ms" to enable you to test before you have the redirect working properly.

Authentication Libraries

There are numerous front-end libraries available for implementing OAuth 2.0 and OpenID Connect.

Microsoft's libraries provide an API for several popular programming languages including:

• Java
• Go
• Native mobile application languages
• JavaScript/TypeScript

If you do not see your language listed in the libraries Microsoft provides, we recommend searching for a set of authentication libraries in your own programming language before writing custom code.

Additional Libraries

There are numerous front-end libraries available for implementing OAuth 2.0 and OpenID Connect. We recommend searching for an open-source set of authentication libraries in your own programming language before writing custom code.

JavaScript Example

If you are using a JavaScript application, Microsoft provides some open-source examples for the Code Grant Flow.

Your First API Call

After you have authorized your first test user and received an authentication token, you can test our APIs by visiting the documentation on the Foundation API site.

Example: Get Cost Codes

Let's get some cost codes belonging to your sample customer:

curl -v -X GET
"https://apifs-sdbx.foundationsoft.com/foundation/v1/costcodes/pages?page=1&pageSize=50"
-H "Cache-Control: no-cache"
-H "Authorization: Bearer {yourToken}"
-H "Foundation-Subscription-Key: {yourKey}"
-H "CasConnectionGuid: {yourGuid}"

You should receive the response payload with a 200 status code:

[
  {
    "costCodeGroup": {
      "costCodeGroupId": null,
      "description": null
    },
    "wcClass": {
      "wcClassId": null,
      "description": null
    },
    "isActive": true,
    "costCodeId": "1",
    "description": "GENERAL COSTS",
    "costCodeGroupId": null,
    "wcClassId": null
  }
]

Rate Limiting

The Foundation Partner API uses rate limiting to optimize performance and security for integrations.

Current Rate Limit

500 requests, per minute, per customer

Customer-Based Limits

The rate limit is applied to the customer, not the integration. For example, if MyIntegration has 10 mutual customers with Foundation Software, and the 10 customers all use the app at the same time, they each have an individual rate limit of 500 per minute.

Prevent Excessive Failures

Once a customer reaches the rate limit, the API will return a 429 response.

Security Alert

Too many calls returning a 429 may be identified as a security threat, resulting in the integration being blocked and an investigation being conducted.

To prevent this, design the integration so that once the rate limit is reached, future calls are postponed until the rate limit resets. Consider using a circuit breaker pattern with a cached time to resume requests.

Rate Limit Headers

The following headers are returned on any API call:

Header Name	Value	Description
X-RateLimit-Limit	500	The total number of allowed requests
X-RateLimit-Remaining	0-499	The number of calls remaining until the rate limit will be reached

After the rate limit is reached, the following header is returned:

Header Name	Value	Description
X-RateLimit-Reset		The time in milliseconds at which the rate limit will reset

Need Help?

For questions during development, please call (800) 811-5926 for support.

---

Site v6.0