Setup and Configuration

The setup and configuration must be complete prior to using the API. This page aims to help you get up and running quickly by including all relevant resources for setting up and configuring the Sage 200 API across both Sage 200 Standard and Professional.

For support with the API setup, we would recommend contacting the customers Sage 200 Business Partner as covered in our API setup responsibilities guide.

We would recommend starting with our Microsoft 365 Compatibility guide as this details which versions of Microsoft 365 are required to set up the Sage 200 API. After reviewing this, we would recommend reviewing the relevant setup guides found below.

Sage 200 Standard

• Sage 200 Standard - How to setup the API

Sage 200 Professional

• Setup of the Sage 200 Native API - using Microsoft AAD Tunneling
• API setup responsibilities
• API Access via Windows Authentication for Developers
• Disabling and Enabling the Native API

Knowledgebase Index

• Sage 200 - API Knowledgebase Index

Tools

• Sage 200 - API Test Tool
• "No Sites Returned" when running get sites via the API Test Tool

Obtain Developer Subscription Keys

To begin working with the Sage 200 API, follow these essential steps to obtain your developer subscription keys:

1. Access the Developer Portal: Sign into the Developer Portal or sign up for an account if you don't already have one.
2. Subscribe to Sage 200 API: Inside the Products section, select Sage 200 Unlimited to subscribe.
3. Retrieve your unique subscription keys: After subscribing, you will be able to access your unique subscription keys inside your Profile

1. Access the Developer Portal

To obtain a subscription key, you need a My Sage Account and then sign up to the Developer Portal.

1. If you have already signed up on the Developer Portal, select Sign in and enter your My Sage email address and password.
2. If you have not signed up but do have a My Sage Account, then press Sign up and enter your My Sage email address and password. Your Developer Portal Account will be set up using your My Sage Account details.

Visit the Developer Portal and choose the sign-in or sign-up option, then follow the remaining steps below.

Sign into Developer Portal

Don't have a My Sage Account?

If you don't have a My Sage Account, you will need to create one before you can sign up.

1. When selecting sign up, you have the option "New User? Create account."
2. You will then need to fill in your email address, first name, last name, and choose a password that meets the criteria.
3. Click "Sign Up" to create your account.
4. Check your email inbox (including spam or junk mail folders) for a verification email.
5. Open the email and enter the verification code provided.
6. Click "Verify email" to complete the verification process.

2. Subscribe to Sage 200 API

Now that you have signed in, you need to subscribe to the Sage 200 API.

In the menu at the top, you will find the Products section, here you will have a list of all Sage APIs that can be subscribed to.

1. Select Products from the top menu.
2. Select Sage 200 Unlimited which will give you access to the Sage 200 API for Sage 200 Professional and Sage 200 Standard.
3. Enter a Name for your subscription.
4. Agree to the Terms of Use, which can be seen by pressing Show.
5. Press Subscribe.
6. This will redirect you to your profile to obtain your subscription key.

3. Obtain Subscription Key

Now that you have signed in and subscribed to the Sage 200 API, you can access your subscription keys from your profile.

In your Profile you can see and do the following:

Account Details

In this section, you will see your profile details, which are taken from your My Sage Account. You also have the option to close your account here.

If you no longer require the account, you can close it. If you need another subscription after closing it, you will need to sign up and subscribe again to generate a new subscription key.

Subscriptions

In this section, you will find your unique subscription keys.

• To view your subscription keys, click on "Show" next to the hashed-out Primary key.
• Click on "Show" next to the hashed-out Secondary key.

• Make a note of your subscription keys and store them securely. Remember not to share these keys, as they grant access to make API calls on your behalf.
• When necessary, you have the option to regenerate your Primary and Secondary keys by selecting the "Regenerate" option.

Regenerating Keys

After regenerating your keys, it is crucial to update all your integrations, applications, or services that rely on the API with the newly generated keys. Failure to do so can potentially lead to service interruptions or authentication failures. Ensure seamless functionality by promptly replacing the old keys with the new ones across your systems.

Cancelling Subscription

You can cancel the subscription if required. Once cancelled, this process cannot be reversed; you would need to subscribe again if you require access in the future.

Congratulations! You have successfully created a My Sage account, subscribed to the Sage 200 API, and obtained your subscription keys. Keep your keys secure and use them for authentication when making API requests.

Request Client ID and Client Secret

To access the Sage 200 API, you need a client ID and a client secret. These credentials allow your application to authenticate and interact with the Sage 200 system. Follow these steps to request them.

Request Account Number (If Applicable)

If you already have an account number, skip this step. If you don't have an account number, please complete the Sage ISV Developer Account form to request an account to be setup. The account number is an 8-digit number that Sage assigns to your business. On the form, provide your:

• First name
• Surname
• Telephone number
• Email address
• Company name
• Registered address

Please provide a full business address for account registration.

Sage ISV Developer Account Request Form

Once you have completed the form, we shall email you with your account number. It may take up to 72 hours for the requested information to be processed and returned to you.

Request API Credentials

You need to complete the Sage 200 Credentials request form with the following information:

Personal/Business information

• Account number: The 8-digit number for your Sage account.
• Company name: The name for your Sage account.
• Contact name: The primary contact's name for this request.
• Contact email address: The email address where the API credentials will be sent. Use an email address accessible by more than one person for continuity.

Choose Development or Production Credentials

You can request either development or production credentials. It is recommended to request development credentials first. Once your application is ready for production, you can request production credentials.

Provide Application Details

On the same form, enter:

• Name of application: A name (3-120 characters) to distinguish your application from the Sage 200 application.
• Description: A summary (up to 140 characters) of your application's functionality.
• Refresh token expiry time in days: The number of days (0-90) after which the refresh token will expire.
• Desktop or web application: The type of your application.

Enter Redirect URLs (Web Applications Only)

If you selected a web application in the previous step, enter your redirect URLs on the same page. Redirect URLs are used for callback purposes after the user completes authentication. You may need to amend them if your application's infrastructure, domain, or callback URLs change. All redirect URLs must use the "https" prefix. Include port numbers if required for your redirect URLs.

Sage 200 Client ID and Client Secret Request Form

It may take up to 72 hours for the requested information to be processed and returned to you.

Security Considerations

Store and handle your client ID and client secret securely. They are sensitive information that grant access to your application. Use proper access controls and encryption mechanisms to prevent unauthorized access.

Amendments to Information

If you need to change any information, such as redirect URLs or other details, email [email protected] to request the amendments. Follow proper authentication and verification procedures when requesting amendments to prevent unauthorized changes to your application's settings.

Authentication

All requests made the Sage 200 API must contain a valid access token as part of the authentication header. This section will provide basic information on client credentials as well break down the different methods available to generate an access token. For a more detailed explanation of the Sage 200 API authentication process, see our Authenticate with the Sage 200 API guide, available here.

Client Credentials

The Sage 200 API supports 2 client types for authentication, Confidential Clients (Web) and Public Clients (Desktop). The type of credentials which you use will vary based on your applications construction and will be used, in combination with your Sage ID, to request a valid access/refresh token.

If you require development/production credentials, please return to Obtaining client ID and client secret credentials.

Access & Refresh Tokens

Access tokens are used to authenticate your API request and without one your requests will be denied. Access tokens are set to expire after a specified amount of time, 480 minutes, however, a refresh token can be used to remove the need for the user to sign in each time their access token expires.

Refresh tokens have a much longer expiry time than Access Tokens, with a maximum of 90 days, and can be used to generate a valid Access Token, if the Refresh Token has not expired.

If the Refresh Token has also expired than a user must login with a valid Sage ID to request a new Access Token and Refresh Token.

Please note that the Sage ID, which is used to authenticate the request, authenticating user, determines the operations, including methods and endpoints, available to you. Further information on user roles and features can be found in the relevant application documentation.

• Sage 200 Standard Online
• Sage 200 Professional

Generating an Access Token

There are various methods of generating an Access Token based on your Development needs:

Programmatically

We have created a C# sample application and client library to demonstrate how to programmatically request an access token for a Windows Form Application (Public Client) and a Website (Confidential). These are available for download here. This page also details the changes required to update the Web and Desktop sample solution to use your Sage 200 API client credentials.

NOTE: Please be aware though that Sage Developer Services only support the API endpoints and not the implementation, troubleshooting or debugging of applications that make use of the Sage 200 API. This is further explained in our support boundaries which can be found here.

Postman

When testing and developing your API application you may wish to use Postman, an open-source API development environment, which allows you to authenticate and run API queries without needing to program an application, or website.

The Get New Access Token option within Postman’s Authorization tab allows you to request an access token for your API request by entering your Confidential client credentials.

Developer Services have also produced a utility which allows you to generate an access token using your Public client credentials, which can be copied into the Postman Authorisation header and used to query the Sage 200 API.

These methods are further explained in our guide to Using Postman with the Sage 200 RESTful API, see here.

NOTE: Postman does not support the use of a refresh token as part of the authentication process and will therefore require a new access token be requested upon expiry of the existing access token.

Site and Company Information

In order to make database specific requests via the Sage 200 API, you need to specify the Site ID (X-Site) and Company ID (X-Company) within your request header. To acquire these, a GET request can be ran to sites endpoint to show information for all sites the authenticating user has access to.

Please see below an example request and response to the sites endpoint for Sage 200 Standard Online:

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/sites
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/sites

Response:

    {
        "company_id": 123,
        "company_name": "APITestCompany",
        "tenant_id": 1234,
        "site_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "site_name": "Demodata",
        "site_short_name": "xxxxxxxxxx"
    }

Querying the Sage 200 API

Supported Methods

The Sage 200 API supports 4 methods, POST, GET, PUT, and DELETE, which correspond to the create, read, update, and delete (CRUD) operations respectively.

Prior to querying a Sage 200 API endpoint, you must first ensure that the method, or verb, you are going to use is supported on this endpoint. This information can be found in the supported verbs section for the endpoint in the relevant Sage 200 API documentation.

For example, the customers endpoint currently supports the GET and POST methods when a record ID is not specified as part of the endpoint URL, and the GET, PUT, and DELETE methods when it is included.

The following sections detail how to use each of these methods, in combination with query parameters and JSON request bodies, where applicable, to query the customers endpoint for Sage 200 Standard Online.

GET Request

A GET request allows you to read information from a specific endpoint, e.g., customers, and return this in the response body of the request.

Example 1

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers

Response:

This request will return information for all customer records in the response body. For performance purposes, this is limited to the first 500 records; we will discuss how to extend this later in this section.

Should you know the ID of the customer record you wish to query, you can append this to the end of your customers endpoint URL and return information for that specific record.

Example 2

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers/123
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers/123

NOTE: The customer ID relates to the unique reference number applied to the record in the Sage 200 database and is therefore not surfaced within the application. We, therefore, suggest that the $filter query parameter is used for a known unique field value, such as the customer reference, see below.

POST Requests

A POST request allows you to create a record using the Sage 200 API.

As you are creating a new instance of a record, POST requests do not support the inclusion of an existing ID or query parameters in the request URL.

The following example will demonstrate how to create a customer record in Sage 200 Standard Online, with the inclusion of some optional fields. Required fields for a POST request to an endpoint can be found in the Body Fields section of that endpoint's API documentation. For the customers endpoint, the required fields for a POST request are the reference and name fields.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	POST	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers
Sage 200 Professional	POST	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers

JSON Request Body:

{
    "reference": "APITEST",
    "name": "API Test 02",
    "short_name": "APITEST2",
    "on_hold": false,
    "account_status_type": "AccountStatusActive",
    "currency_id": 2103,
    "telephone_country_code": "00",
    "telephone_area_code": "1234",
    "telephone_subscriber_number": "567 8899",
    "website": "www.apitest01.co.uk",
    "credit_limit": 2500.00,
    "country_code_id": 13,
    "default_tax_code_id": 1729,
    "contacts": [
        {
            "salutation_id": 0,
            "name": "John Smith",
            "first_name": "John",
            "last_name": "Smith",
            "is_default": true
        }
    ]
}

Response:

A successful POST request will return a 200 (OK) HTTP status, and the response body will show the record information for your created record, including fields that were not populated by your initial POST request.

NOTE: The Sage 200 API follows the same rules for record creation as the Sage 200 application. Therefore, if you attempt to re-run your POST request, you will receive a 400 (Bad Request) HTTP status, with the response body advising that "The account reference already exists. You cannot have two accounts with the same account reference."

PUT Requests

A PUT request can be used to update information on an existing record. As such, you must specify your record ID as part of your request URL. Only the information that you intend to update needs to be passed as part of the request body.

TIP: Further information on using the $filter query parameter to find a record's ID can be found in the GET Requests section of this article.

The following example demonstrates how to update the short name of the customer record used in our GET Requests $select example.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	PUT	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers/27825
Sage 200 Professional	PUT	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers/27825

JSON Request Body:

{
    "short_name": "APIDemo"
}

Response:

A successful PUT request will return a 200 (OK) HTTP status, and the response body will show all record information, including the updated field, for the ID specified in the PUT request URL.

DELETE Requests

The DELETE method can be used to delete a record from Sage 200. You must, therefore, specify the record ID as part of your request URL.

As the Sage 200 API follows the same rules for deletion as the Sage 200 application, you will only be able to delete records that meet the criteria set by your user roles within the application.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	DELETE	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers/27825
Sage 200 Professional	DELETE	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers/27825

Response:

A successful DELETE request will return a 200 (OK) HTTP status. If your user roles do not permit the deletion of the record, you will receive a 403 (Forbidden) HTTP status, and the response body will advise that "The requested operation is forbidden for this account."

Query Parameters

You can add query parameters to your request URL to influence your API response. The following section will demonstrate how to use, and combine, some of the more common parameters. Please review the full list of the supported query parameters.

• $filter

  The $filter parameter allows you to return records that match your specified criteria. You can use more than one $filter as part of your request by including the and/or operators.

  TIP: This parameter is commonly used to return information for a specific record when the ID is not known.

  Example 1

  Request:

  Product	Request Type	URL
  Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'
  Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'

  Response:

  This will return record information for the customer record which has a reference of A1D001.

  Example 2

  Request:

  Product	Request Type	URL
  Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001' or name eq 'APITest'
  Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$filter=reference eq 'A1D001' or name eq 'APITest'

  Response:

  This will return record information for the customer record which has a reference of A1D001 or a name of APITest.




• $select

  The $select parameter allows you to limit the fields that are returned in the response of your request. In the following example, we combine this parameter with the $filter parameter to return the ID of one of our customer records.

  Example

  Request:

  Product	Request Type	URL
  Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'&$select=id
  Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$filter=reference eq 'A1D001'&$select=id

  Response:

  {
    "id": 27825
  }




• $top

  The $top parameter allows you to limit the number of records returned in your response body. As previously advised, when this value is not specified, the Sage 200 API will limit requests to 500 records. However, for versions of Sage 200 released after February 2019, you can return up to 5000 records, as demonstrated below.

  Example

  Request:

  Product	Request Type	URL
  Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$top=5000
  Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$top=5000

  NOTE: If an $orderby parameter is not specified, the endpoint's default will be used.




• $orderby

  The $orderby parameter allows you to order the results in your API response body, in both ascending and descending order. In this example, we are going to use the $top query parameter to increase the number of records returned to the maximum of 5000 and order the results in descending order by the customer's balance.

  Example

  Request:

  Product	Request Type	URL
  Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$top=5000&$orderby=balance desc
  Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$top=5000&$orderby=balance desc




• $expand

  The $expand parameter allows you to include the content of the record's sub-records in your response body.

  Example

  Request:

  Product	Request Type	URL
  Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'&$expand=contacts
  Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$filter=reference eq 'A1D001'&$expand=contacts

Next Steps

Learn