API Documentation

The LinkGreen API (application programming interface) allows for integration with LinkGreen from your desktop, web or mobile application. Our API allows your application to do much of what a user would be able to do from our web interface such as adding a new inventory item, creating a looking good list or updating your inventory quantity.

Introduction

Protocols / Encoding

The LinkGreen API supports two common protocols and methods of data encoding.

REST/JSON: The first method uses simple HTTP POST and GET calls, with the request and response data encoded in JSON (JavaScript Object Notation). Although we don’t adhere strictly to the REST style architecture, you may think of this as a “REST-like” service, and for convenience we’ll refer to it in this documentation as our “REST” service. Each major entity in the system is represented by a root URL, followed by the operation you wish to perform, followed by a unique identifier for that entity. For example, to update the quantity of a product, the operation URL would be something like “/supplierinventory/updatequantity/SKU”. Again, while we don’t follow the REST architecture strictly, we typically follow the pattern of /entity/operation/uniqueidentifier

SOAP/XML: The second method we support is SOAP (Simple Object Access Protocol) with the request and response encoded in XML. This protocol is commonly used in conjuction with Microsoft technologies and languages, and using Visual Studio, it’s very easy to generate and use a WCF proxy client for each service. Like our REST service, each major entity in LinkGreen such as orders and inventory has it’s own root service, which contains operations for that entity such as retrieve, update or add.

Encryption

Whether you choose to use REST or SOAP, all calls to and from our API services are encrypted using HTTPS / SSL. If you’re using REST, you will not need to do anything special except ensure that you are prefixing your URLs with HTTPS. (If you forget to do this, don’t worry, we’ll automatically redirect your call to HTTPS anyway.) If you’re accessing our SOAP service through WCF, you’ll need to ensure that you turn on transport security in the HTTP binding. If you generate a client through Visual Studio or the svcutil.exe utility, it should automatically take care of this for you.

Authentication

Each LinkGreen user has their own unique API key. You can view your API key by logging on to the LinkGreen application ( https://app.linkgreen.ca), clicking on your username in the top right of the screen (next to the words “Logged in as”) and then clicking on the “API Key” tab. If you do not see this tab, please contact the administrator of your account to give you access. You will provide this key with every API call that you make. It will be the first parameter of the service method (if you’re using SOAP) or it will be the first part of the URL after the service name (if you’re using REST)

If your API key is ever stolen or compromised, you can generate a new one on this same screen by clicking the “Generate New Key” button


Getting Started with REST / JSON

API URLs:

The URL for our live site is:

https://api.linkgreen.ca

The URL for our testing site is (note the protocol is HTTP, not HTTPS for the testing site only):

http://sandbox.linkgreen.ca

Requests:

The typical pattern for each operation is:

URL/{ServiceName}/{OperationName}/rest/{ApiKey}/{UniqueIdentifier}

(The unique identifer is omitted when not applicable, for example, when retrieving a list of items as opposed to a single item.) If the request requires additional data, such as when adding an inventory item, it will be passed along in the body of the request and encoded as JSON.

The HTTP verb you will use (GET vs. POST) will depend on the nature of the call. Typically, if you are requesting data and nothing will be changed as a result of the call, we will use the GET verb. If your call will result in data being added, updated or deleted, we will use the POST verb.

Finally, ensure that you add an “Accept” HTTP header with the value of “application/json”, otherwise the service will return XML rather than JSON.

Responses:

The response body (also encoded as JSON) will contain the following properties:

  • Error Will contain the error message if there is a problem, or will be null if the operation completed successfully.
  • Success True if the operation completed successfully, false if the operation had an error and did not complete.
  • Result This property will contain the result data, where applicable. If the operation does not return a result, this property will be omitted. The data type of the result object will depend on the nature of the operation – it might be an order, an inventory item, a list of categories etc.

If there is a problem or error, the HTTP response code will be 400 (Bad Request). If the operation completes successfully, the HTTP response code will be 200 (OK).

In the event of an authentication problem (invalid or missing API Key), the HTTP response code will be 403 (Forbidden). The result will contain a single property, “Reason”, which will contain an explanation of why the request could not be authenticated.


Working With Product Categories

Supplier inventory is organized into categories to make it easier for buyers to search for and find what they’re looking for. Suppliers must define at least one category, and each item must be assigned to a single category. Categories may be organized into a heirarchy, such that a category may have no parent (i.e. a root category) or one parent, and mat have zero to many children. Our API provides methods to fetch categories, add categories, rename categories and reassign categories to new parents.

Get All Categories

Get
https://api.linkgreen.ca/categoryservice/rest/getall/{APIKEY}

  • Request Body: Empty
  • Sample Response:
{
    "Error": null,
    "Success": true,
    "Result": [

        {
            "Depth": 0,
            "Id": 14643,
            "Name": "ABELIA",
            "ParentCategoryId": null
        }
    ]
}

Result Properties:

The result is an array of categories. Categories are arranged in a hierarchy so that a category can have zero to one parents, and zero to many children. The category object has the following properties:

  • Id: Unique identifier for this category. Use this value when you need to specify a category in other calls, such as when adding an item to inventory.
  • Depth: A zero-based index which indicates how many generations of parents this category has. If zero, it has no parent. If one, it has a parent of depth 0. If two, it has a parent, and it has a parent of depth 0….etc.
  • Name: The category name
  • ParentCategoryId: The Id of this category’s parent, if any (will be null when depth is zero.)

Add A Category

Post
https://api.linkgreen.ca/categoryservice/rest/add/{APIKEY}

  • Request Body: Contains an AddCategoryRequest object, with two properties: Name and ParentCategoryId. The name is required and cannot be blank. The ParentCategoryId may be blank, but if present, must contain a valid ID of one of your existing categories. If the ParentCategoryId is null, this new category will have no parents (it will be a root category). If present, the new category will be a child of the specified parent category.
{
    "Name": "New Category Name", 
    "ParentCategoryId": null 
}

Sample Response: A category object with the following properties:

  • Id: Unique identifier for this category. Use this value when you need to specify a category in other calls, such as when adding an item to inventory.
  • Depth: A zero-based index which indicates how many generations of parents this category has. If zero, it has no parent. If one, it has a parent of depth 0. If two, it has a parent, and it has a parent of depth 0….etc.
  • Name: The category name
  • ParentCategoryId: The Id of this category’s parent, if any (will be null when depth is zero.)
{
    "Error": null, 
    "Success": true, 
    "Result": 

    { 
        "Depth": 0, 
        "Id": 14643, 
        "Name": "New Category Name", 
        "ParentCategoryId": null 
    }
}

Rename A Category

Post
https://api.linkgreen.ca/categoryservice/rest/rename/{APIKEY}

  • Request Body: Contains a RenameCategoryRequest object, with two properties: NewName and Id. The “NewName” is required and cannot be blank. The Id is the Id of the category getting renamed, and must be a valid ID of one of your existing categories.
{
    "NewName": "New Category Name", 
    "Id": 17716 
}

Sample Response: A category object with the following properties:

  • Id: Unique identifier for this category. Use this value when you need to specify a category in other calls, such as when adding an item to inventory.
  • Depth: A zero-based index which indicates how many generations of parents this category has. If zero, it has no parent. If one, it has a parent of depth 0. If two, it has a parent, and it has a parent of depth 0….etc.
  • Name: The category name
  • ParentCategoryId: The Id of this category’s parent, if any (will be null when depth is zero.)
{
    "Error": null, 
    "Success": true, 
    "Result": 

    { 
        "Depth": 0, 
        "Id": 17716, 
        "Name": "New Category Name", 
        "ParentCategoryId": null 
    }
}

Assign A New Parent

Post
https://api.linkgreen.ca/categoryservice/rest/assignNewParent/{APIKEY}

  • Request Body: Contains an AssignNewCategoryParentRequest object, with two properties: NewParentId and Id. The “NewParentId” is not required but if supplied must be a valid ID for one of your existing categories. If null or not supplied, the category will essentially become a “root” category, with no parents. The Id is the Id of the category that is getting the new parent, and must be a valid ID of one of your existing categories.
{
    "NewParentId": 12, 
    "Id": 17716 
}

Sample Response: A category object with the following properties:

  • Id: Unique identifier for this category. Use this value when you need to specify a category in other calls, such as when adding an item to inventory.
  • Depth: A zero-based index which indicates how many generations of parents this category has. If zero, it has no parent. If one, it has a parent of depth 0. If two, it has a parent, and it has a parent of depth 0….etc.
  • Name: The category name
  • ParentCategoryId: The Id of this category’s parent, if any (will be null when depth is zero.)
{
    "Error": null, 
    "Success": true, 
    "Result": 

    { 
        "Depth": 1, 
        "Id": 17716, 
        "Name": "Category Name", 
        "ParentCategoryId": 12 
    }
}

Working With Product Locations

Supplier inventory can be assigned to a location (as broad as a warehouse or as specified as a shelf) in order to simplify the process of preparing an order for shipping from a pick-list. This is optional – items do not need to be assigned to a location. Our API provides operations for you to get all your locations, add a new location, and rename an existing location.

Get All Locations

Get
https://api.linkgreen.ca/locationservice/rest/getall/{APIKEY}

  • Request Body: Empty
  • Sample Response:
{
    "Error": null, 
    "Success": true, 
    "Result": [

        { 
            "Id": 14643, 
            "Name": "Orillia Warehouse" 
        },     

        { 
            "Id": 14644, 
            "Name": "Barrie Warehouse" 
        }
    ]
}

Result Properties:

The result is an array of locations. The location object has the following properties:

  • Id: Unique identifier for this location. Use this value when you need to specify a location in other calls, such as when adding an item to inventory.
  • Name: The location name.

Add A Product Location

Post
https://api.linkgreen.ca/locationservice/rest/add/{APIKEY}

  • Request Body: Contains an AddLocationRequest object, with a single property,”Name” which is required and cannot be blank.
{ 
    "Name": "New Location Name"
}

Sample Response: A location object with the following properties:

  • Id: Unique identifier for this location. Use this value when you need to specify a location in other calls, such as when adding an item to inventory.
  • Name: The location name
{
    "Error": null, 
    "Success": true, 
    "Result": 

    { 
        "Id": 14643, 
        "Name": "New Location Name" 
    }
}

Working With Supplier Inventory

Add an Item

Post
https://api.linkgreen.ca/SupplierInventoryService/rest/AddItem/{APIKEY}

This operation will allow you to add a new item to inventory. The request URL contains only your API Key. The request body contains an InventoryItemRequest object. The response returns the same object back to you, with the Id populated so that you can uniquely identify this item on subsquent calls.

The InventoryItemRequest has the following properties:

  • Id: (Integer). On your request, you may omit this value. In the response, this value will be populated with the new unique indentifier for this item.
  • CategoryId: (Integer). Required. This must be a valid identifier for one of your categories. If you do not know the ids of your categories, you can make a call into the “GetAll” operation of the “CategoryService”
  • Description: (String). Required. A short, one sentence description of this item.
  • PrivateSKU: (String). Required. Must be unique in your inventory.
  • LocationId: (Integer). Optional. If supplied, it must represent a valid identifier of one of your locations. If you do not know the ids of your locations, you can make a call into the “GetAll” operation of the “LocationService”
  • UPC: (String). Optional. Universal product code of this item, if applicable.
  • MinOrderSpring: (Integer). Optional. This is the minimum amount of this item that must be ordered in the spring.
  • MinOrderSummer: (Integer). Optional. This is the minimum amount of this item that must be ordered in the summer.
  • FreightFactor: (Decimal/Float). Optional.
  • QuantityAvailable: (Integer). Optional. This is the total number of this item in stock and available for sale.
  • Comments: (String). Optional. A longer description of the item, typically one to five sentences if required.
  • SuggestedRetailPrice: (Decimal/Float). Optional. The manufacturer’s suggested retail price (MSRP) if applicable.
  • OpenSizeDescription: (String). Optional. Short description of the size. e.g 12×12, 16 pound bag, 1.5 litres, etc.
  • DirectDeliveryMinQuantity: (Integer). Optional. The minimum required on a direct delivery order.
  • NetPrice: (Decimal/Float). Optional. Also known as the catalog price, this is the base price a buyer will pay for this item if they are not entitled to any special pricing or a buyer group discount.
  • SlaveQuantityPerMaster: (Integer) Optional. When an item is priced individually but sold in bulk, this value represents the number of smaller items which make up the larger quantity. For example, if you sell 100 per skid, this value would be “100”
  • SlaveQuantityDescription: (String). Optional. When an item is priced individually but sold in bulk, this value represents the description of smaller items which make up the larger quantity. For example, if you sell 100 plants per skid, this value might be “each” or “plant”
  • MasterQuantityDescription: (String). Optional. When an item is priced individually but sold in bulk, this value represents the description of the larger item. For example, if you sell 100 plants per skid, this value would be “skid”.
  • DirectDeliveryCode: (String). Optional
  • Inactive: (Boolean). Optional. When true, this item will not appear to buyers.
  • IsDirectDelivery: (Boolean) Optional. When true, this item can only be ordered with other direct-delivery items.

Sample Request Body: An InventoryItemRequest object, as described above. (other properties have been omitted for brevity)

{
    "PrivateSKU": "ABCDEF", 
    "Description": "This is my new product", 
    "CategoryId": 30, "NetPrice": 20.12 
}

Sample Response:

{
    "Error": null,  
    "Success": true,  
    "Result": 

    {  
        "CategoryId": 30,  
        "Comments": null,  
        "Description": "This is my new product",  
        "DirectDeliveryCode": null,  
        "DirectDeliveryMinQuantity": 0,  
        "FreightFactor": 0,  "Id": 14172,  
        "Inactive": false,  
        "IsDirectDelivery": false,  
        "LocationId": null,  
        "MasterQuantityDescription": null,  
        "MinOrderSpring": 0,  
        "MinOrderSummer": 0,  
        "NetPrice": 20.12,  
        "OpenSizeDescription": null,  
        "PrivateSKU": "ABCDEF",  
        "QuantityAvailable": 0,  
        "SlaveQuantityDescription": null,  
        "SlaveQuantityPerMaster": null,  
        "SuggestedRetailPrice": null,  
        "UPC": null  
    }     
}

Result Properties: Properties of the InventoryItemResponse object, same as the request above.

Update an Item

Post
https://api.linkgreen.ca/SupplierInventoryService/rest/UpdateItem/{APIKEY}

This operation will allow you to update an inventory item. The request URL contains only your API Key. The request body contains an InventoryItemRequest object.

Every property of the inventory item will be overwritten with the values you provide (even if you provide null or zero). Furthermore, if you omit an optional property in your request, you’ll be essentially setting that value to it’s default value (typically zero or null). Therefore, it’s highly recommended that you first fetch the item, change the properties you need to change and then send the entire item as the request body. This way, no properties of the item will be overwritten inadvertently with defaults. Please take note of the properties such as PrivateSKU, Category ID and description which cannot be null or blank

When determining which item is being updated, it is the “Id” property which is used to uniquely identify the item. Effectively, the Id property is read-only and can never be updated.

The response returns the same object back to you

The InventoryItemRequest has the following properties:

  • Id: (Integer). Required. This is used to identify the item being updated. Read-only – may not be updated.
  • CategoryId: (Integer). Required. This must be a valid identifier for one of your categories. If you do not know the ids of your categories, you can make a call into the “GetAll” operation of the “CategoryService”
  • Description: (String). Required. A short, one sentence description of this item.
  • PrivateSKU: (String). Required. Must be unique in your inventory. You may update the SKU, but you will get an error if another item alreadt has this SKU.
  • LocationId: (Integer). Optional. If supplied, it must represent a valid identifier of one of your locations. If you do not know the ids of your locations, you can make a call into the “GetAll” operation of the “LocationService”
  • UPC: (String). Optional. Universal product code of this item, if applicable.
  • MinOrderSpring: (Integer). Optional. This is the minimum amount of this item that must be ordered in the spring.
  • MinOrderSummer: (Integer). Optional. This is the minimum amount of this item that must be ordered in the summer.
  • FreightFactor: (Decimal/Float). Optional.
  • QuantityAvailable: (Integer). Optional. This is the total number of this item in stock and available for sale.
  • Comments: (String). Optional. A longer description of the item, typically one to five sentences if required.
  • SuggestedRetailPrice: (Decimal/Float). Optional. The manufacturer’s suggested retail price (MSRP) if applicable.
  • OpenSizeDescription: (String). Optional. Short description of the size. e.g 12×12, 16 pound bag, 1.5 litres, etc.
  • DirectDeliveryMinQuantity: (Integer). Optional. The minimum required on a direct delivery order.
  • NetPrice: (Decimal/Float). Optional. Also known as the catalog price, this is the base price a buyer will pay for this item if they are not entitled to any special pricing or a buyer group discount.
  • SlaveQuantityPerMaster: (Integer) Optional. When an item is priced individually but sold in bulk, this value represents the number of smaller items which make up the larger quantity. For example, if you sell 100 per skid, this value would be “100”
  • SlaveQuantityDescription: (String). Optional. When an item is priced individually but sold in bulk, this value represents the description of smaller items which make up the larger quantity. For example, if you sell 100 plants per skid, this value might be “each” or “plant”
  • MasterQuantityDescription: (String). Optional. When an item is priced individually but sold in bulk, this value represents the description of the larger item. For example, if you sell 100 plants per skid, this value would be “skid”.
  • DirectDeliveryCode: (String). Optional
  • Inactive: (Boolean). Optional. When true, this item will not appear to buyers.
  • IsDirectDelivery:. (Boolean) Optional. When true, this item can only be ordered with other direct-delivery items.

Sample Request Body: An InventoryItemRequest object, as described above. (Optional properties have been omitted for brevity)

 
{
    "Id": 14172, 
    "PrivateSKU": "ABCDEF", 
    "Description": "This is my new product", 
    "CategoryId": 30, 
    "NetPrice": 20.12    
}

Sample Response:

{
    "Error": null, 
    "Success": true, 
    "Result": 

    { 
        "CategoryId": 30, 
        "Comments": null, 
        "Description": "This is my new product", 
        "DirectDeliveryCode": null, 
        "DirectDeliveryMinQuantity": 0, 
        "FreightFactor": 0,  "Id": 14172, 
        "Inactive": false,  "IsDirectDelivery": false, 
        "LocationId": null,  "MasterQuantityDescription": null, 
        "MinOrderSpring": 0, 
        "MinOrderSummer": 0, 
        "NetPrice": 20.12, 
        "OpenSizeDescription": null, 
        "PrivateSKU": "ABCDEF", 
        "QuantityAvailable": 0, 
        "SlaveQuantityDescription": null, 
        "SlaveQuantityPerMaster": null, 
        "SuggestedRetailPrice": null, 
        "UPC": null 
    }     
}

Result Properties: Properties of the InventoryItemResponse object, same as the request above.

Get an Item By SKU

Get
https://api.linkgreen.ca/SupplierInventorySearchService/rest/GetItem/{APIKEY}/{SKU}

This operation will allow you to fetch a single item by it’s SKU. The request URL contains your API Key and the SKU of the item you want to retrieve. If the item is not found, it will result in an error.

The request body is empty.

The response is an InventoryItemResponse object.

Sample Response:

{
    "Error": null, 
    "Success": true, 
    "Result": 

    {
        "CategoryId": 30, 
        "Comments": null, 
        "Description": "This is my new product", 
        "DirectDeliveryCode": null, 
        "DirectDeliveryMinQuantity": 0, 
        "FreightFactor": 0,  "Id": 14172, 
        "Inactive": false, 
        "IsDirectDelivery": false, 
        "LocationId": null, 
        "MasterQuantityDescription": null, 
        "MinOrderSpring": 100, 
        "MinOrderSummer": 200, 
        "NetPrice": 20.12, 
        "OpenSizeDescription": null, 
        "PrivateSKU": "ABCDEF", 
        "QuantityAvailable": 0, 
        "SlaveQuantityDescription": null, 
        "SlaveQuantityPerMaster": null, 
        "SuggestedRetailPrice": null, 
        "UPC": null 
    } 
}

Update The Available Quantity of an Item

Post
https://api.linkgreen.ca/SupplierInventoryService/rest/UpdateProductQuantity/{APIKEY}/{SKU}/{NEWQTY}

This operation will allow you to update the available quantity on a single item in your inventory. In addition to your API Key, you must supply the item’s SKU and the new quantity. All of these parameters are part of the URL. The request body is emtpy. The response will contain the “Error” and “Success” properties, but no result.

  • Request Body: Empty
  • Sample Response:
{
    "Error": null, 
    "Success": true 
}

Result Properties: N/A

Update The Catalog Price of an Item

Post
https://api.linkgreen.ca/SupplierInventoryService/rest/UpdateProductPrice/{APIKEY}/{SKU}/{NEWPRICE}

This operation will allow you to update the catalog price (also known as the net price) on a single item in your inventory. This is the standard price a buyer will pay if they do not have access to special pricing, or if they are not eligible for a buyer group discount. In addition to your API Key, you must supply the item’s SKU and the new price. All of these parameters are part of the URL. The request body is emtpy. The response will contain the “Error” and “Success” properties, but no result.

  • Request Body: Empty
  • Sample Response:
{
    "Error": null, 
    "Success": true 
}

Result Properties: N/A


Working With Relationships

In LinkGreen, a “relationship” represents an instance of your company being connected to another company. If you are a buyer, then being in a relationship with a company means that you can see their catalog and pricing and place orders with them. If you are a supplier, then being in a relationship with a company means that they can see your pricing and catalog and place orders with you.

Relationships must be requested and approved. Until approved, neither side derives the benefits of the relationship (i.e. ability to see pricing).

Our API provides operations to see all approved and pending relationships, search for companies, request relationships and approve pending relationships.

Get All Companies In Relationship

This operation will list all the companies with whom you have an approved relationship (i.e the relationship is not pending or ignored on either side).

Every company in LinkGreen has public contact information such as their phone number and address. This is equivalent to what you can find in the phone book or on their website. However, when you are in a relationship with a company, you can also store private contact information such as the email address or cell phone number of your private, personal contact. This is information that only users in your company can see. Where possible, we will show you the private contact information you’ve stored and will fall back to the public information when private information is absent.

Get
https://api.linkgreen.ca/relationshipservice/rest/getall/{APIKEY}

  • Request Body: Empty
  • Sample Response:
{
    "Error": null, 
    "Success": true, 
    "Result": [

        {
            "Address1": "15 White Street", 
            "Address2": null,"City": "Apto", 
            "CompanyTypeId": 6, 
            "Contact1": "Jennifer Grayling", 
            "Contact1Desc": "President", 
            "Contact2": "Kyle Brown", 
            "Contact2Desc": "Vice President", 
            "Country": "Canada", 
            "Email1": "jgreen@apto.on.ca", 
            "Email1Desc": "President", 
            "Email2": "kgreen@apto.com", 
            "Email2Desc": "Vice President", 
            "FormattedPhone1": "705-555-2210", 
            "FormattedPhone2": "705-555-2214", 
            "FullEmail": "President: jgreen@bellissimo", 
            "FullPhone1": "Home: 705-555-2210", 
            "Id": 8,"Name": "Municipality of Bellissimo", 
            "Phone1Desc": "Home", 
            "Phone2Desc": "Business", 
            "PostalCode": null, 
            "ProvState": "Ontario", 
            "Web": "http://www.bellissimo.on.ca" 
        }
    ]
}

Result Properties:

The result is an array of PrivateCompanies (“Private” because it may contain non-public contact information as discussed above). The PrivateCompany object has the following properties:

  • Address1: Primary address, typically a street address
  • Address2: May be omitted, or may be a suite number, PO box number or other.
  • City: City where the company is located
  • CompanyTypeId: The unique identifier of the company’s “type” in LinkGreen such as retail or landscaper
  • Contact1: Name of the primary contact at this company
  • Contact1Desc: Description of the primary contact, often a title such as “President”
  • Contact2: Name of the secondary contact person at this company
  • Contact2Desc: Description of the of the second contact, often a title such as “Sales Manager”
  • Country: Country where the company is located
  • Email1: Primary email address for this company
  • Email1Desc: Description of where or to whom the primary email will go, such as “sales” or “order desk”
  • Email2: Secondary email address for the company
  • Email2Desc: Description of where or to whom the secondary email will go, such as “sales” or “order desk”
  • FormattedPhone1: Properly formatted, human-readable primary phone number
  • FormattedPhone2: Properly formatted, human-readable secondary phone number
  • FullEmail: Combines the primary email with it’s description into one readable property
  • FullPhone1: Combines the primary phone number with it’s description into one readable property
  • Id: Unique identifier for this company
  • Name: Name of the company
  • Phone1Desc: Description of the primary phone number such as “Sales” or perhaps “Cell”, if the number is for a private contact at the company
  • Phone2Desc: Description of the secondary phone number such as “Sales” or perhaps “Cell”, if the number is for a private contact at the company
  • PostalCode: Postal code (for Canadian companies) or Zip code (for U.S. companies)
  • ProvState: The province (Canada) or state (U.S.) where the company is located.
  • Web: This company’s web site address.

Get Relationship

This operation will retrieve a single relationship.

A relationship object contains private information you have stored about this company with whom you have an approved relationship. This can include a private cell number of your contact, or the company number you have stored for this company for your accounting package. To see this information, use this API call and specify the ID of the company (not the ID of the relationship, if you have it)

Get
https://api.linkgreen.ca/relationshipservice/rest/GetRelationship/{APIKEY}/{CompanyId}

  • Request Body: Empty
  • Sample Response:
{
    "Error": null,
    "Success": true,
    "Result": 

    {
        "ContactEmail": "jack@mycompany.co",
        "ContactName": "Jack Bauer",
        "ContactPhone": "4165551212",
        "Id": 10395,
        "OurBillToNumber": null,
        "OurCompanyNumber": "JF-553535",
        "SerializedTaxInfo": null
    }
}

Result Properties:

The result is a “Relationship”. The “Relationship” object has the following properties:

  • ContactEmail: Private email address you have saved for a contact at this company, if any
  • ContactName: Private contact name you have saved for a contact at this company, if any
  • ContactPhone: Private contact phone number address you have saved for a contact at this company, if any
  • Id: This is a unique identifier of the relationship (not of the company itself).
  • OurBillToNumber: This is YOUR bill-to company reference number, perhaps from another software package such as your accounting
    system.
  • OurCompanyNumber: This is YOUR company reference number, perhaps from another software package such as your accounting
    system.
  • SerializedTaxInfo: This field can hold serialized tax information you have provided which, when downloading orders,
    helps create an import file for your accouting package that correctly calculates taxes. Please contact us for more information
    on this feature.

Get Pending Relationships

This operation will list all the companies that have requested a relationship with you and are waiting for you to approve the request. Because you are not yet in a relationship with this company, you will only see their public address, phone number and email address, such as one could find on their website or in a phone book.

Get
https://api.linkgreen.ca/relationshipservice/rest/getpending/{APIKEY}

  • Request Body: Empty
  • Sample Response:
{
    "Error": null,
    "Success": true,
    "Result": [

        {
            "City": "Vancouver",
            "CompanyName": "Shovels By Doug",
            "CompanyType": "Retail",
            "CompanyTypeId": 1,
            "ContactName": "Doug Norman",
            "Email": "doug@shovels.bc.ca",
            "Id": 7883,
            "Phone": "604-555-3240",
            "ProvState": "BC",
            "RequestDate": "/Date(1441724842307-0400)/",
            "RequestingCompanyId": 64462
        }
    ]
}

Result Properties:

The result is an array of PendingRelationship.

The PendingRelationship object has the following properties:

  • City: City where the requesting company is located.
  • CompanyName: Name of the company requesting the connection.
  • CompanyType: Description of the requesting company type, such as “Retail” or “Municipality”.
  • CompanyTypeId: Identifier of the requesting company type.
  • ContactName: Contact at the requesting company.
  • Email: General email address of the requesting company.
  • Id: A unique identifier for this relationship request (not the ID of the requesting company). You will need this number if you wish to make an API call to approve the request.
  • Phone: Phone number of the requesting company.
  • ProvState: Province or state where the requesting company is located.
  • RequestDate: The date and time the request was made.
  • RequestingCompanyId: The unique identifier of the company making the request.

Approve A Relationship

This operation will allow you to approve a pending relationship. Invoking this operation will trigger a workflow which, among other things, will notify the requesting company by email that their request has been approved.

There is no request body, however as part of the request URL, you must specify the unique identifier of the relationship you wish to approve. You must add this to the URL after the API Key. You can find the Id of all your pending relationships by calling the “Get Pending Relationships” operation.

Post
https://api.linkgreen.ca/relationshipservice/rest/approve/{APIKEY}/{ID}

  • Request Body: Empty
  • Sample Response:
{
    "Error": null,
    "Success": true
}

Result Properties: N/A

Get All Company Types

In LinkGreen, companies are organized according to types such as “Greenhouse Grower, “Municipality” or “Retail”. When you’re inviting companies to join LinkGreen, you’ll need to know which company type to assign. This API call lists all company types so you will be able to view them all and assign the correct one.

There is no request body

Get
https://api.linkgreen.ca/relationshipservice/rest/GetCompanyTypes/{APIKEY}

  • Request Body: Empty
  • Sample Response (Not all values displayed for brevity):
{
    "Error": null, 
    "Success": true,
    "Result": [

        {
            "Description": "Retail",
            "Id": 1
        },
        {
            "Description": "Irrigation",
            "Id": 2
        },
        {
            "Description": "Landscaper",
            "Id": 3
        },
        {
            "Description": "Lawn Care",
            "Id": 4
        }
    ]
}

Result Properties: The result is an array of “CompanyType”. The “CompanyType” object has the properties “Id” and “Description”.

Invite Companies To Join

This API call will allow you to invite companies to join LinkGreen. You begin by sending a list of companies with all the important information such as name, address, phone number and email. First, we will validate the incoming data to make sure that no required information is missing. We then search our database to ensure that the company does not already exist as a member.

Every company that passes validation and is not already a member will be added. We will send them an invitation with a unique link that will allow them to join. When they click the link to join, you will be automatically connected with them.

Post
https://api.linkgreen.ca/relationshipservice/rest/Import/{APIKEY}

Request Body: An array of companies, with the following properties:

  • Name: Required. This is the name of the company
  • FormattedPhone1: Required. Main phone number of the company
  • CompanyType: Required. Must be the description of one of our built-in company types. For reference, make this API call.
  • Address1: Optional.
  • Address2: Optional.
  • City: Optional.
  • Country: Required. Must be exactly: “Canada “or “US”
  • ProvState: Required. Must be the two letter abbreviation such as ON or NY.
  • PostalCode: Optional. Postal Code (Canada) or Zip Code (U.S)
  • Web: Optional.
  • Contact1: Optional. Name of our main public contact at the company
  • Web: Optional.
  • PrivateContactName: Optional. Name of our private, personal contact at this company
  • PrivateContactEmail: Optional. Email address of the private contact, above.
  • PrivateContactPhone:Optional. Phone number of the private contact, above.
  • OurCompanyNumber:Optional. Our internal reference number for this company, perhaps from our accounting system or another software package.
  • OurBillToNumber: Optional. Our internal reference number for this company, perhaps from our accounting system or another software package.
[
    {
        "Address1":"123 Main Street",
        "Address2":"RR #1",
        "City":"Brighton",
        "CompanyType":"Retail",
        "Contact1":"Jennifer Young",
        "Country":"Canada",
        "Email1":"sales@theplace.on.ca",
        "FormattedPhone1":"6135551212",
        "Name":"The Place",
        "PostalCode":"K8V 3J8",
        "ProvState":"ON",
        "Web":"http://www.theplace.on.ca",
        "OurBillToNumber":"SPL-1214",
        "OurCompanyNumber":"SPL-1214",
        "PrivateContactEmail":"john@theplace.on.ca",
        "PrivateContactName":"Jonh Fash",
        "PrivateContactPhone":"6135553555"
    }
]

Request Body:

  • CompaniesAlreadyMembers This is the list of companies who were not invited because we identified that they are already LinkGreen members.
  • CompaniesInvited This is the list of companies who were added and invited.
  • Problems If there are problems with the data which is preventing us from validating the companies, this array will contain all of the errors you need to correct.
  • SuccessfulImport This will be true if validation passed and all companies who are not already members were invited. If false, there was a validation error and you should look at the “Problems” array to see what the problems are.
{
    "Error": null,
    "Success": true,
    "Result": 

    {
        "CompaniesAlreadyMembers": ["ABCD", "XYZ"],
        "CompaniesInvited": ["JFK"],
        "Problems": [],
        "SuccessfulImport": true
    }
}

Working With Orders

Get All Statuses

During the lifecycle of an order, it will go through many stages as it’s created, submitted, confirmed, shipped and eventually completed. An order might also be cancelled or put on hold. At each stage, an order will have a buyer status and a supplier status. It’s important to know what all the available statuses are so that you can understand what stage an order is currently in, it’s history and it’s possible next steps.

This operation lists all the order statuses in LinkGreen which are available to you as buyer (if you’re logged in a a buyer) or as a supplier (if you’re logged in as a supplier). It will be rare, but not impossible, that LinkGreen will introduce new order statuses in the future. Therefore, while it’s advisable to cache this data, you should also periodically check for updates.

Get
https://api.linkgreen.ca/orderservice/rest/status/{APIKEY}

  • Request Body: Empty
  • Sample Response:
{
    "Error": null,
    "Success": true,
    "Result": [

        {
            "Id": 4,
            "Status": "Rejected"
        },
        {
            "Id": 5,
            "Status": "Open"
        },
        {
            "Id": 6,
            "Status": "Open / Revised"
        },
        {
            "Id": 10,
            "Status": "Confirmed"
        },
        {
        "Id": 8,
            "Status": "Supplier Submitted"
        },
        {
            "Id": 15,
            "Status": "Shipped"
        },
        {
            "Id": 20,
            "Status": "Completed"
        },
        {
            "Id": 25,
            "Status": "Cancelled"
        },
        {
            "Id": 30,
            "Status": "On Hold"
        }
    ]
}

Result Properties:

The result is an array of OrderStatus.

The OrderStatus object has the following properties:

  • Id: Unique identifier for this order status. Use this value when you need to specify a status in other calls, or identify the current status in other calls.
  • Name: The status name.

Get Order Details

This operation will get a single order along with all the details such as the items ordered, quantity and price.

Get
https://api.linkgreen.ca/orderservice/rest/OrderDetails/{APIKEY}/{{OrderId}}

  • The OrderId is required in the request URL, and is the unique identifier for this order.
  • Request Body: Empty
  • Sample Response:
{
    "Error": null,
    "Success": true,
    "Result": {
    "AnticipatedShipDate": "/Date(1458792000000+0000)/",
    "BuyerComment": null,
    "BuyerCompany": {

        "Address1": "58 Red Drive.",
        "Address2": null,
        "City": "Barrie",
        "CompanyType": "",
        "CompanyTypeId": 1,
        "Contact1": "Michael Norman",
        "Contact1Desc": "Regional VP",
        "Contact2": null,
        "Contact2Desc": "Contact Name",
        "Country": "Canada",
        "DeliveryAreaFeesAndMethod": null,
        "Email1": "mike@here.com",
        "Email1Desc": "Email",
        "Email2": "mark@gmail.com",
        "Email2Desc": "Home.",
        "FormattedPhone1": "705-770-3240",
        "FormattedPhone2": "705-429-4250",
        "Id": 1,
        "Name": "Buyer Name",
        "Phone1Desc": "Business",
        "Phone2Desc": "Home",
        "PostalCode": null,
        "ProductsAndSpecialties": null,
        "ProvState": "ON",
        "Web": "http://www.us.com"
    },

    "BuyerCompanyId": 1,
    "BuyerPO": "",
    "BuyerStatus": "",
    "BuyerStatusId": 105,
    "ContactName": null,
    "CreatedDate": "/Date(1452807298790+0000)/",
    "Details": [

        {
            "AddedBySupplier": false,
            "AdditionalDiscount": 0,
            "CatalogPrice": 6.5,
            "ItemId": 20421,
            "ItemIsDirectDelivery": true,
            "ItemName": "ACER PALMATUM BENI MAIKO #3 Pot",

            "Price": 6.175,
            "PrivateSKU": "24111",
            "QuantityConfirmed": 2,
            "QuantityRequested": 2,
            "QuantitySent": null,
            "Size": null,

            "SubstitutedById": null,
            "SubstitutedForId": null
        }
    ],

    "Freight": null,
    "Id": 22306,
    "IsDirectDelivery": true,
    "OrderNumber": "00016-000385",
    "PaymentTerm": "",
    "PaymentTermId": 1019,
    "RequestedShippingDate": null,
    "ShippingDate": null,
    "Status": null,
    "SupplierComment": null,
    "SupplierCompany": {

        "Address1": "35 Jake Cres",
        "Address2": null,
        "City": "Barrie",
        "CompanyType": "",
        "CompanyTypeId": 1,
        "Contact1": "Sam Soily",
        "Contact1Desc": "President",
        "Contact2": "Dora Dirt",
        "Contact2Desc": "Vice President",
        "Country": "Canada",
        "DeliveryAreaFeesAndMethod": null,
        "Email1": "john@here.com",
        "Email1Desc": "Email",
        "Email2": null,
        "Email2Desc": "Email",
        "FormattedPhone1": "705-212-5039",
        "FormattedPhone2": "",
        "Id": 16,
        "Name": "Supplier Name",
        "Phone1Desc": "Phone #",
        "Phone2Desc": "Phone #",
        "PostalCode": "L4N QN6",
        "ProductsAndSpecialties": null,
        "ProvState": "ON",
        "Web": null
    },

    "SupplierCompanyId": 16,
    "SupplierPO": null,
    "SupplierStatusId": 10
    }
}

Result Properties:

The result is an “Order” object. In addition to having many of the properties of “OrderSummary” class below, the “Order” class has a “Details” property which is an array of “OrderDetails”. “OrderDetails” has the following properties:

  • AddedBySupplier: True if the item was added by the supplier after it was submitted by the buyer.
  • AdditionalDiscount: Any additonal discount amount, in dollars, added by the supplier.
  • CatalogPrice: The standard catalog price of this item. (May or may not be the price the buyer actually pays). Compare with the “Price” property below which is the price the buyer actually pays on this order.
  • AdditionalDiscount: Any additonal discount amount, in dollars, added by the supplier.
  • ItemId: The unique identifier of the item.
  • ItemIsDirectDelivery: True if the item is direct delivery
  • ItemName: The name of the item ordered.
  • Price: The actual price the buyer pays for this item on this order.
  • PrivateSKU: The SKU of the item being ordered.
  • QuantityConfirmed: The quantity confirmed by the supplier.
  • QuantityRequested: The quantity requested by the buyer.
  • QuantitySent: The quantity shipped by the supplier.
  • Size: The size of the item.
  • SubstitutedById: If not null, this is the Id of the item which was substituted in for this item.
  • SubstitutedForId: If not null, this is the Id of the item for which this item was substituted in.

Get Supplier Orders By Status

If you are logged in as a supplier, this operation will get all of your orders in LinkGreen which match one or more supplier statuses you specify. In the body of the request, you provide an array of integers which represents the ids of the statuses you want to match, for example 15 (shipped) and 20 (completed). This operation will return an array of all orders which are either shipped or completed. If you don’t know the ids which correspond the statuses you want, you can make a call to “Get All Statuses” to see all order statuses and their corresponding ids.

Get
https://api.linkgreen.ca/orderservice/rest/getforsupplier/{APIKEY}

Request Body: An array of one or more integers which represent the status id(s) you want to match

[5, 10]

Sample Response: An array of OrderSummary objects:

{
    "Error": null,
    "Success": true,
    "Result": [

        {
            "AnticipatedShipDate": null,
            "BuyerCompanyId": 16,
            "BuyerCompanyName": "Soils Demo Company",
            "BuyerPO": null,
            "BuyerStatus": "",
            "CreatedDate": "/Date(1390839015963+0000)/",
            "FormattedAnticipatedShipDate": "",
            "FormattedCreatedDate": "Jan 27 2014",
            "FormattedRequestedShippingDate": "Feb 12 2015",
            "IsDirectDelivery": false,
            "OrderNumber": "00001-000036",
            "PaymentTerm": "Net 30",
            "RequestedShippingDate": "/Date(1423717200000+0000)/",
            "ShippingDate": null,
            "SupplierCompanyId": 1,
            "SupplierCompanyName": "Link Green",
            "SupplierPO": null,
            "SupplierStatus": "Open",
            "SupplierStatusId": 5
        }
    ]
}

Result Properties:

The result is an array of OrderSummary. The OrderSummary object has the following properties:

  • AnticipatedShipDate: The date on which the supplier has indicated they expect to ship the order. May be null if not indicated by the supplier. See “FormattedAnticipatedShipDate” for a more human-readable representation.
  • BuyerCompanyId: Unique identifier of the buyer company on this order.
  • BuyerCompanyName: The name of the company which is the buyer on this order.
  • BuyerPO: The buyer’s purchase order, if any. May be null.
  • BuyerStatus: The buyer’s status of this order – typically “Submitted” but might also be “Cancelled” or “On Hold”.
  • CreatedDate: The date the order was created. See “FormattedCreatedDate” for a more human-readable representation.
  • IsDirectDelivery: “true” if this is a direct-delivery order, “false” otherwise.
  • OrderNumber: A unique order number for this order.
  • PaymentTerm: A description of the payment terms for this order.
  • RequestedShippingDate: The date the buyer has requested for shipping. See “FormattedRequestedShippingDate” for a more human-readable representation.
  • ShippingDate: The final, actual date the order shipped. May be null.
  • SupplierCompanyId: A unique identifier of the supplier company on this order.
  • SupplierCompanyName: The name of the company which is the supplier on this order.
  • SupplierPO: The supplier purchase order number, if any. May be null.
  • SupplierStatus: A description of the supplier’s order status, such as “Confirmed” or “Shipped”.
  • SupplierStatusId: Identifier of the supplier’s order status.