Skip to content
logo Knowledgebase

A Guide to Constructing an API Request for the Sage 200 API

Created on  | Last modified on 

Summary

This document is a step by step guide to building an application utilising the RESTful API for Sage 200 Standard and Sage 200 Professional.

Process

CAUTION: This authentication method has been deprecated, 19th Febuary 2021. For an updated version of this guide, please see the Authenticate with the Sage 200 API guide.

Overview

The API is a RESTful data service which provides programmatic access to read and write data, allowing developers to make HTTP requests and receive responses. The API uses the OAuth 2.0 standard for authentication. OAuth 2.0 is a widely recognised framework for authentication and is globally used in APIs. This is a process of exchanges that allow a user to grant access for an application to access their data set. You can read more about OAuth 2.0 here. These requests use HTTP verbs (GET, POST, PUT, DELETE) to determine the request functionality:

GET: The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect. i.e. Retrieve data /records.

POST: The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. i.e. Create data / records.

PUT: The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an existing resource, it is modified. i.e. Modify data/ records.

DELETE: The DELETE method deletes the specified resource. i.e. Deletes data / records.

NOTE: If you are developing or testing API requests using Postman, we have also produced the following guide which you may find helpful, see here. This guide will cover a lot of the content discussed below in the context of the Postman application.

OAuth flow

The client requests authorization from the resource owner. The authorization request can be made directly to the resource owner, or, preferably, indirectly via the authorization server, which acts as an intermediary.

The client receives an authorization grant, which are credentials representing the resource owner's authorization. These are expressed using one of four grant types and are defined in this specification or using an extension grant type. The authorization grant type depends on the method used by the client to request authorization and the types supported by the authorization server:

  • The client requests an access token by authenticating with the authorization server and presenting the authorization grant.
  • The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token.
  • The client requests the protected resource from the resource server and authenticates by presenting the access token.
  • The resource server validates the access token, and if valid, serves the request.
Confidential or Public Client

There are 2 ways to access the Sage 200 API, via a Confidential Client or a Public Client.

Public Client:

Mobile and Desktop applications are classed as a public client types as they would need to store the client and secret locally, and securely, which are then used as part of the Sage ID user authentication process. This is potentially less secure as the client and secret would need to be distributed with the compiled applications. To improve security, a temporary certificate is issued by Sage ID to secure any communication between the application and Sage ID

Confidential Client:

Web based applications that store the Client and Secret keys on a server are classed as Confidential Clients. They are more secure because only the server has access to these keys; they are not distributed to end users

Credentials

When you register your application for the Sage 200 API, you are provided with:

  • A Client_ID
  • A Scope

If you are using a confidential client, you will also be provided with:

  • A Secret Key

CAUTION: You must store these credentials securely and not share these with anyone. You must also not check this information into source control.

For confidential client, you will register one or more redirect URLs with Sage that will be used during the OAuth process to redirect the user back to your application. For testing and development purposes you do not need to register your application and can instead use our demonstration credentials. Please contact Sage Developer Services if you require these. To register your API application, for a production environment, and receive your API Credentials, please complete our request form.

Access and refresh tokens

Access tokens are used to authenticate API requests. Without a valid access token any request will be denied. Access tokens are set to expire after a specified amount of time, for a maximum of 60 minutes for the access token and 180 days for the refresh token. When a successful request is made to generate a new access token a refresh token is also generated. When an access token expires, your application can be configured to either have the user login to requests another access token, or the refresh token can be used to generate a new access token without user interaction up to the lifetime of the refresh token.

NOTE: Authentication for the Sage 200 API requires user interaction, either by requesting a new access token or a new refresh token. This cannot be circumnavigated, or automated.

Access tokens are specific to the Sage ID used to request the token and therefore share the same level of authorization and permission within the Sage 200, as the user who made the request.

Base URLs

The Base URL for your request will differ based on the Sage 200 application.

For Sage 200 Professional/Extra Online you need to ensure the following Base URL being used is:

https://api.columbus.sage.com/uk/sage200extra/accounts/

For Sage 200 Standard this would be: 

https://api.columbus.sage.com/uk/sage200/accounts/

The following demonstrations will assume you are using a confidential client.

Authorization Request

You will need to start by authenticating your application. This is achieved by sending a request to the Sage 200 Authorization Server with the following information:

Request URL:
https://eu-oauth.sso.services.sage.com/SSO/OAuthService/WebStartAuthorisationAttempt

response_type: code

client_id: This will have to be generated by Live Services, however, for demonstration credentials, please contact Developer Services.

redirect URI: The URI which will receive the result of the authentication. This is case sensitive, and must match a URI that is registered against the Client ID.

state: A string used to protect against Cross-site request forgery (C SRF) attacks. Although state is optional, we recommend including this. This should be a string that cannot be guessed.

scope: See Client ID.

NOTE: If the value of the state parameter returned in the response does not match the state that was provided in the original request, it does not originate from the original request and you must not continue.

OAuth requires all parameters to be URL encoded and concatenated with an ‘&’.

Example Request:
https://eu-oauth.sso.services.sage.com/SSO/OAuthService/WebStartAuthorisationAttempt?response_type=code&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&redirect_uri=http%3a%2f%2flocalhost%3a56953%2fAccount%2fAuthorise&state=Th15IsAT35t5tat3T0Demo5trat3AnAP1Auth3nt1cat1onR3qu35t&scope=XXXXXXXX()%3b
Response:

When this endpoint is queried, the user is prompted to sign into with their Sage ID and asked if they want to authorise the application. If the user allows access to your application, they are redirected to the redirect URL along specified in the request with an authorization code which can be read from the response.

Example Response:
http://localhost:56953/Account/Authorise?code=DZjSeplzqsdfXam%2bisdf3z%2bVbyxI%2bS19%2bpu0vOAs%3d&state=Th15IsAT35t5tat3T0Demo5trat3AnAP1Auth3nt1cat1onR3qu35t

NOTE: The state value matches that passed in our request.

Access token

Once your application has been authenticated you will then need to request an access token in exchange for the authorization code.

To do this, you will need to send a POST request to the following URL:

https://eu-oauth.sso.services.sage.com/SSO/OAuthService/WebGetAccessToken
Required parameters:
Header parameters:

Authorization: “Basic “ + <secretkey>

NOTE: The <secretkey consists of your client_id and _secret base 64 encoded and concatenated with a ‘:’

ContentType: application/x-www-form-urlencoded;charset=UTF-8

Request body parameters:

grant_type: authorization_code

code: The authorization code returned in the previous step (see Authorization Request.)

redirect_uri: The URI which will receive the result of the authentication. This is case sensitive, and must match a URI that is registered against the Client ID (see Credentials).
All parameters need to be URL encoded and concatenated with an ‘&’.

Example request body:
grant_type=authorization_code&code=DZjSeplzqsdfXam%2bisdf3z%2bVbyxI%2bS19%2bpu0vOAs%3dredirect_uri=http%3a%2f%2flocalhost%3a56953%2fAccount%2fAuthorise
Example Response:
"{\"access_token\":\"fkFjvLZ\\/hKSueaLh7pRQDQ8cXzxbWp7QvXldoa+IszfZXAqSagAxW5eFS1Hqa2TjTi7C5qTgIJlf60qhd4gs7\\/nxoRyJPx6LXZHG7COfeQxQmmhzVvevZXq8WhEIkTIR8aDa3OtDKITWC6Lhyk5cFBeUviGPdu\\/yutux0TEKzRc4RVZRET6Fshl3zCN65U\\/HlGCrelVe8odz\\/GXiEFDziIN4KgmN7TCMIIqIA4qDifgaBiD4sFsLKo77vI14yoOFUXA9RmE0+Fa0V2eGN3vZyFCeZH0\\/+x4b60MCvydIaDKWK6eCwynCNtJJqkxSH1Aa7fIvmUFNnt6JZi7BMGSujjhXMrto1F3ObdCDZ+H0qUn0TwHwwmccuKlTKoSqdqF4NKd38qxYbkOruOIrTrWPE959tntz\\/SawM+jp5F4zgoswvxREI9xtBq2ZMWPsFC+0H001FLcf+t3E+cR\\/PvxzweIlqaBeUwbZj1IIEYxrwZCUe2pPuaVJFlNR82PAANKBko1B47+zy7fLkJGQZYhMcLI82Eq6KBzzCBF\\/NKn5XfyCUJhiveWWFEiHuMMsrqTCYkGwy7mA+ohzE6BE4j+jWom5RI04cUcisPBMQTeXAvesFtWvkEiI7eFqE3jHRusdUyMd4STFuMf3TY\\/hAk6Z4LHPbHLGQu6b6rioSUgfEQ8v1M2tHRKQ9chOwWM3YHhZgZHq9A8x8EEmzG3gj46rGyTCLmCG0qt1j67zYzOXVYnOKc28aDLhSFV0qHLeQG5xfK\\/u7Yq\\/WgKuRb8w11umLV7yx0oR+TRVUjQBZJqwWxABfoqP6cV6WbUQNPalUa2NQuvZ+o0gdfa034Jq3PjmFwp690IE6FUCPsT0+\",\"expires_in\":1200,\"refresh_token\":\"6Z3IFJE80HAG9R633ICV8EC64B401P28B6ER2D1E2O754QAA312D476ABR1W5Z4L5K0EEZ767BAXEV6D344SA5CB4F4N39E6ATCTEF983J4KBL9U9N45CQ4KCJ0K1K5Z\",\"scope\":null,\"token_type\":\"bearer\"}"
Using the refresh token

During the authorization exchange, you are issued with an access token and a refresh token. You must include the access token in each API call.

NOTE: The access token has a short expiry. The maximum lifetime of an access token is 60 minutes.

You can use a valid refresh token to obtain a new access token without requiring the user to sign in again, up to the expiry of the refresh token. To do this, you will need to send a POST request to the following URL:

https://eu-oauth.sso.services.sage.com/SSO/OAuthService/WebGetAccessToken
Required parameters:
Header parameters:

Authorization: “Basic “ + <secretkey>

NOTE: The <secretkey consists of your client_id and _secret base 64 encoded and concatenated with a ‘:’

ContentType: application/x-www-form-urlencoded;charset=UTF-8

Request body parameters:

grant_type: refresh_token

refresh_token: The refresh token generated by your previous request (see Access Token).

TIP: All parameters need to be URL encoded and concatenated with an ‘&’.

Example request body:
grant_type=refresh_token&refresh_token= 6Z3IFJE80HAG9R633ICV8EC64B401P28B6ER2D1E2O754QAA312D476ABR1W5Z4L5K0EEZ767BAXEV6D344SA5CB4F4N39E6ATCTEF983J4KBL9U9N45CQ4KCJ0K1K5Z
Example Response:
"{\"access_token\":\"fkFjvLZ\\/hKSueaLh7pRQDQ8cXzxbWp7QvXldoa+IszfZXAqSagAxW5eFS1Hqa2TjqloTl\\/FtxOp9NvqUN2YNsULkCS0CE5aDssKzpARvSQN7LhGnIU2DlJTWmwGAVc4q5D6WBwAbrOM2jiaiQUP4KQagEKOXLCjbJkX6TSQy+\\/DGQ0gobe0Ybg\\/2WIxt45+XZ8ngQht6QYDaCTEFt76hUHfd+pzG5U8NX4kjyzLzvXkNPs63qgoqbmlaeFSbSSwRfi4qa+GTP+\\/yQVxuj55gRsO++F4mCysc18+E1bG7\\/MREKVf\\/4iarkI+ydc1Uq7lwLFbpWTll7nk9GuFLBA52cAFo+AjPj1zJzb+NF5\\/TmIPBvInFsFTE9Ckr2xHq5DyrCpU7XgAyi+AD7q\\/MnK+kT5cb0nVzRqFxBXdvfYkPlDMupTEMKfLKqYWqWPZUseAPuVGdTup4k87JJNwHuunzIXmTmC7avVlbHGdDyU4+5jzUUWZjT\\/iDZ3DWFhBmSM5uUp8dpRdXxV8kUg4H8izfYsBuDOVH1KZtxiVYWPLpIcBFTlufdWIA0da4k2bIwH40Zo\\/yHqzkfRXGUKquJoGaXAksRkdZ+ffJJz3PsSUrF\",\"expires_in\":1200,\"refresh_token\":\"673NFZES0RAJ9Z6L3VCI8UCU4W4B1A2UBBEJ2U1F257D4UAS3B2K4I6RBH1N5X4D4GAP3P3W4HD48A1XDA42AJEN444FEY7MBO4JFR1W2L10EK3HBE8A1S3M3I1B6X2N\",\"scope\":\"6bektnhq();\",\"token_type\":\"bearer\"}"
Making a Request

With a valid access token, you are now authorized to make API requests. A request consists of various attributes which must be built up prior to sending the request.The API has several endpoints and operations available. These are essentially URLs available to make requests to.

For example, a GET request to the customer’s endpoint will return all customers, whereas, a POST request to the same endpoint will create a new customer.

All the available endpoints and operation can be found here, for Sage 200 Professional/Extra Online, and here, for Sage 200 Standard. The documentation for each operation provides information on available/required fields and OData query parameters.

Once you have determined which HTTP method (operation) and endpoint you wish to use you will need to construct the request header and body.

Header parameters:

Headers include information about the HTTP request and about the data that is sent with the request body.

As part of your header you will need to supply the following values for each HTTP request:

ocp-apim-subscription-key: Your Developer Subscription Key.

TIP: Your developer subscription key is a unique ID which is used when making API calls against your account. It is therefore important that these keys are not shared. For further information on acquiring your developer subscription key please see here.

Content-Type: application/json

TIP: This informs the server/client the type of content that is being sent/recieved. For the Sage 200 API this would be JSON, therefore, this value will always be set to: application/json.

Authorization: A valid access token (if authenticating using Cloud ID)

TIP: This is the access token that you have generated, prefixed with the string "Bearer "(note the space affixed to the end of Bearer).

CAUTION: If you omit to add to a space you will the following error in your response body when you attempt to make an API request: "Message": "Authorization has been denied for this request."

X-Site: The site_id value of the Site.

X-Company: The company_id of the Company.

TIP: These values are the ID of the site, and the company, you would like to send your request to. These values must be passed on every request, with the exception of a GET request to the sites endpoint, which is used to obtain these values. For information on the sites endpoint here, for Sage 200 Professional/Extra Online, and here, for Sage 200 Standard.

Example:
Bearer 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
Request Body Example:

This is an example of a JSON request body for a POST request to the customers endpoint.

 {
    "reference": "APITEST",
    "name": "API Test",
    "short_name": "APITEST",
    "on_hold": false,
    "account_status_type": "AccountStatusActive",
    //Currencies endpoint
    "currency_id": 63956,
    "exchange_rate_type": "ExchangeRateSingle",
    "telephone_country_code": "00",
    "telephone_area_code": "1234",
    "telephone_subscriber_number": "567 8899",
    "fax_country_code": "00",
    "fax_area_code": "1234",
    "fax_subscriber_number": "567 9988",
    "website": "www.apitest01.co.uk",
    "credit_limit": 2500.00,
    //Country_codes endpoint
    "country_code_id": 63946,
    //Tax_codes endpoint
    "default_tax_code_id": 1287,
    "duns_code": "000000001",
    "contacts": [
        {
            "salutation_id": 0,
            "name": "Api Test",
            "first_name": "Api",
            "middle_name": "",
            "last_name": "Test",
            "is_default": true
        }
    ]
}
Further Information:
Setup and Configuration:

Information on setup and configuration of the Native API, using Microsoft Azure Active Directory tunnelling, can be found here.

API Setup and Responsibilities:

Information on who responsible for each area of a Sage API deployment can be found here.

FAQ:

For a list of frequently asked question regarding the Sage 200 API, please see here.

Getting Started with Postman:

This guide provides steps to making API request to the Sage 200 RESTful API via Postman, and can be found here.