Overview

Welcome to the documentation for the Forest API web service. Currently the only the Forest Direct™ service is exposed via the api. If you have any questions, please contact customer support at support@forestincentives.com and they'll forward your questions to the right channel.

Authentication

The protool for authentication is Basic Auth. In order to be able to utilize the api, you must be assigned a username and password. Additionaly, your account must be associated with/granted access to one or more customer accounts to act upon/on behalf of.\n\nFor all endpoints requiring authentication, requests must contain the Authorization header, which contains the name of the authentication method (Basic), followed by a base64 encoded string of type username:password.

Example

For username='john' and password='apiaccess', Authoriztion: Basic am9objphcGlhY2Nlc3M=

Please note: All requests require authentication

Forest Direct Endpoints

The following endpoints relate to the Forest Direct service

Direct Order Details

GET https://api.forestincentives.com/v2/{station_id}/direct/orders/{order_number}
Path parameters
station_id The Station associated with the order being fetched.
order_number This can be either the Forest Order # (SO#####) or the order's Reference Id that was passed through api order creation.
Response
Status: 200 OK
Content type: application/json 
                {
                    "order_number": string,
                    "reference_id": string,
                    "po_number": string,
                    "callback_url": string,
                    "shipping_method": string,
                    "shipping_address": {
                            "addressee": string,
                            "attention": string,
                            "address1": string,
                            "address2": string,
                            "city": string,
                            "state": string,
                            "postal": string,
                            "country": string
                        }
                    "lines": [
                        {
                            "reference_id": string,
                            "sku": string,
                            "premium_code": string,
                            "quantity": integer,
                            "shipping_method": string,
                            "number": string,
                            "name": string,
                            "email": string,
                            "gift_date": datetime,
                            "custom_data1": string,
                            "custom_data2": string,
                            "custom_data3": string,	
                            "status": string,
                            "tracking_numbers": string
                        }
                    ]
                }

Direct Order Creation

Creates a Forest Direct order. This endpoint is not recommended for batch/bulk order creation.
POST https://api.forestincentives.com/v2/{station_id}/direct/orders
Path parameters
station_idThe station id
Request body parameters
po_number Required Type:String Title:Purchase Order Number
reference_id Type:String Title:Reference Id
callback_url Type:String Title:Callback Url When an item on an order is shipped, shipment information is posted to this URL
number Type:String Title:Member number
name Required Type:String Title:Member name Used for any email notifications.
email Required Type:String Title:Email address
shipping_method Required Type:String Title:Shipping Method Default order shipping method. For available methods, see here
shipping_address Required Type:Object Title: Address to ship items to
addressee Type:String Title:Addressee If left blank, member name will be used.
attention Type:String Title:Attention
address1 Required Type:String Title:Address Line 1 Address Line 1
address2 Type:String Title:Address Line 2 Address Line 2
city Required Type:String Title:City City
state Required Type:String Title:State Two letter state code
postal Required Type:String Title:Postal code Address zip code
country Required Type:String Title:Country Two letter country code
lines Required Type:Array Title:Order Lines The line items on the order
reference_id Type:String Title:Reference Id
sku Required Type:String Title:Forest SKU Forest SKU
premium_code Type: Title: Station's item premium - purely informational for exporting/reporting.
quantity Type:Integer Title:Quantity Defaults to 1 if not passed; maximum line quantity is 10.
gift_date Type:Date Title:Gift Date Informational for exporting/reporting purposes
custom_data1 Type:String Title:Custom Data Informational for exporting/reporting purposes
Allegiance: Pledge Id
Team Approach: Gift Sequence
SalesForce: SalesForce ID
MemSys: Pledge #
custom_data2 Type:String Title:Custom Data Informational for exporting/reporting purposes
Allegiance: Order Number
Team Approach: Adjustment Sequence
custom_data3 Type:String Title:Custom Data Informational for exporting/reporting purposes
Team Approach: Benefit Sequence
MemSys: Sequence #
Response
Status: 201 CREATED
Content type: application/json 
                The response object is the same as Order Details

Direct Order Line

This enpoint ingests and stores a single line, to be grouped together into an order(s) during by a scheduled process. Lines are grouped by Purchase Order Number, so please assure lines you wish to be grouped together share PO numbers. Currently the order creation process runs hourly.
POST https://api.forestincentives.com/v2/{station_id}/direct/line
Path parameters
station_idThe station id
Request body parameters
po_number Required Type:String Title:Purchase Order Number
callback_url Type:String Title:Callback Url When this item is shipped, shipment information is posted to this URL
reference_id Type:String Title:Line Reference Id
sku Required Type:String Title:Forest SKU Forest SKU
premium_code Type: Title: Station's item premium - purely informational for exporting/reporting.
quantity Type:Integer Title:Quantity Defaults to 1 if not passed; maximum line quantity is 10.
shipping_method Required Type: String Title:Line Shipping Method Overrides the default shipping method on a line level. For available methods, see here
number Type:String Title:Member number
name Required Type:String Title:Member name Used as the address for shipping, as well as any email notifications.
email Type:String Title:Member email If present, is used for shipment notifications and backorder emails (if station is opted into backorder notifications).
shipping_address Required Type:Object Title: Address to ship items to
attention Type:String Title:Attention
address1 Required Type:String Title:Address Line 1 Address Line 1
address2 Type:String Title:Address Line 2 Address Line 2
city Required Type:String Title:City City
state Required Type:String Title:State Two letter state code
postal Required Type:String Title:Postal code Address zip code
country Required Type:String Title:Country Two letter country code
gift_date Type:Date Title:Gift Date Informational for exporting/reporting purposes
custom_data1 Type:String Title:Custom Data Informational for exporting/reporting purposes
Allegiance: Pledge Id
Team Approach: Gift Sequence
SalesForce: SalesForce ID
MemSys: Pledge #
custom_data2 Type:String Title:Custom Data Informational for exporting/reporting purposes
Allegiance: Order Number
Team Approach: Adjustment Sequence
custom_data3 Type:String Title:Custom Data Informational for exporting/reporting purposes
Team Approach: Benefit Sequence
MemSys: Sequence #
Response
Status: 200 OK
Content type: application/json Content: Any warning messages

Direct Shipments

GET https://api.forestincentives.com/v2/{station_id}/direct/orders/shipments
Path parameters
station_idThe station id
Query string parameters
format Type:String TitleFormat Indicates the desired export format which determines the fields returned. Currently supported formats are: default, allegiance, memsys, salesforce, teamapproach
startDate Type:Date TitleStart Date Starting date range of shipments to fetch, inclusive. In any standard date format, recommend M/d/yyyy.
endDate Type:Date TitleEnd Date Ending date range of shipments to fetch, inclusive. In any standard date format, recommend M/d/yyyy.
Response
Status: 200 OK
Content type: application/json

Default
                        [
                            {
                                "reference_id": string,
                                "line_reference_id": string,
                                "member_number": string,
                                "ship_dt": string,
                                "tracking_no": string,
                                "ship_method": string,
                                "gift_date": string,
                                "custom_data1": string,
                                "custom_data2": string,
                                "custom_data3": string
                            }
                        ]
Allegiance
                        [
                            {
                                "reference_id": string,
                                "line_reference_id": string,
                                "ship_dt": string,
                                "tracking_no": string,
                                "ship_method": string,
                                "pledge_id": string,
                                "order_no": string
                            }
                        ]
MemSys
                        [
                            {
                                "reference_id": string,
                                "line_reference_id": string,
                                "account": string,
                                "ship_dt": string,
                                "tracking_no": string,
                                "ship_method": string,
                                "pledge_number": string,
                                "sequence_number": string
                            }
                        ]
SalesForce
                        [
                            {
                                "reference_id": string,
                                "line_reference_id": string,
                                "ship_dt": string,
                                "tracking_no": string,
                                "ship_method": string,
                                "gift_date": string,
                                "sales_force_id": string
                            }
                        ]
Team Approach
                        [
                            {
                                "reference_id": string,
                                "line_reference_id": string,
                                "account_id": string,
                                "ship_dt": string,
                                "tracking_no": string,
                                "ship_method": string,
                                "gift_date": string,
                                "gift_sequence": string,
                                "adjustment_sequence": string,
                                "benefit_sequence": string
                            }
                        ]

Shipping Methods

Available shipping methods.

US Shipping Methods

Code Name
BWMED Best Way - Moderate Delivery & Cost
Delivery Expectation: 1-7 Business Days
BWFAST Best Way - Fastest and Most Expensive
Delivery Expectation: 1-3 Business Days
UPR UPS Ground
UP2 UPS 2nd Day Air
UP3 UPS 3 Day Select
UPA UPS Next Day Air
UPN UPS Next Day Air Saver
USPS USPS First Class/Priority
USPM USPS Medial Mail
Includes Books, CDs, VHS, DVDs, Blu-ray, and Audiobooks

Canada Shipping Methods

Code Name
CANBW Best Way - Moderate Delivery & Cost
UPC UPS Standard Canada