Obtain Developer Subscription Keys

Follow these steps to obtain your Sage 200 developer subscription keys. These keys are required when working with the Sage 200 API. The process involves creating a My Sage account, accessing the Developer Portal, subscribing to the desired API, and retrieving your unique subscription keys. Let's get started!

Sign in or Create a My Sage Account (if you don't have one)

Log in or Create a My Sage Account

• Click "Log in or Create Developer Portal Account" option above and if you don't have a My sage account select New User? Create account.
• If you do have a My Sage Account, sign in and move onto Access the Developer Portal

• You will then need to fill in your email address, first name, last name, and choose a password that meets the specified criteria (8 to 20 characters long, at least one uppercase letter, one lowercase letter, and one number).
• Click "Sign Up" to create your account.
• Check your email inbox (including spam or junk mail folders) for a verification email.
• Open the email and enter the verification code provided.
• Click "Verify email" to complete the verification process.

Access the Developer Portal

Log in or Create Developer Portal Account

• If you haven't already, sign in using your My Sage account credentials.
• If you don't have a Developer Portal Account yet, you will be prompted to create one. Simply fill out the form with your email address, first name, and last name.

• If you already have a Developer Portal Account, it will sign you into your profile. On your profile page, you will either see a blank page that requires a subscription to the Sage 200 API or a list of your subscribed products. For example, if you have not subscribed to Sage 200 before but have subscribed to the Sage Business Cloud Accounting v3 API, you may see that product listed here.

Subscribe to the Sage 200 API

Subscribe (Sage 200 API)

• At this point you should have and signed into your My Sage account and a Developer Portal Account.
• Click on the "Subscribe" button and follow the prompts to confirm your subscription.

• Once subscribed, and signed into your Developer Portal.
• Look for the section labeled "Your subscriptions".
• In this section, you will find your unique subscription ID 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. However, please keep the following points in mind:
  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.

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.

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:</strong>

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

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

Next Steps

Learn