Skip to content
Developerhome

Let's get started

This guide will provide you with everything you will require to get start you started with the Sage 200 API. Complete each step in order to setup a test environment of Sage 200 Standard, obtain all require development credentials and make your first request:

  • Intro
  • Obtain Developer Subscription Keys
  • Request Client Id & ClientSecret
  • Authentication
  • Site & Company Information
  • Supported Methods
  • Query Parameters
  • Next Steps
  • Sage 200 getting started image

    Welcome

    To get started with the UK Sage 200 API, you will need to do the following steps:

    • Obtain developer subscription keys: You will need to register as a developer on the Sage Developer Portal and request access to the UK Sage 200 API. You will then receive two subscription keys: a primary key and a secondary key. You will need to use one of these keys in every API request you make.

    • Obtain client ID and client secret: You will also need to request a client ID and a client secret for your application by filling out an online form. These are used to authenticate your application with the UK Sage 200 API and obtain an access token.

    • Authentication: Learn how to securely access the UK Sage 200 API by following the authentication process, which involves obtaining valid credentials and implementing the necessary authentication method in your code.

    • Site & Company Information: To access database-specific requests via the Sage 200 API, retrieve the Site ID (X-Site) and Company ID (X-Company) by making a GET request to the sites endpoint, providing access to the necessary information for your API requests.

    • Sage 200 API Support Methods: Review the Sage 200 API CRUD operations with the POST, GET, PUT, and DELETE methods, ensuring you can query the API and interact with the endpoints.

    • Query Parameters: Learn to incorporate query parameters into your requests to influence your API response.

    • Begin Development: Dive into Sage 200 Development by exploring our guides and available endpoints

    These steps are important because they ensure that you have the necessary credentials and permissions to use the UK Sage 200 API securely and effectively. They also help you familiarize yourself with the basic structure and functionality of the API.

    We are here to help you on your journey with the UK Sage 200 API, we hope you enjoy using the UK Sage 200 API and creating amazing applications with it!

    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.
    Open Sage 200


    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.
    Open Sage 200


    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.
    Open Sage 200
    • 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.

    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