Leads Posting Gateway

Developer Guide

Last Revised 03-17-2014

 

Introduction

 

Welcome to the GRANOT INC Leads Posting Gateway Developer Guide. This guide describes the Web development required to connect a web-site or other application to the GRANOT INC Leads Posting Gateway in order to submit moving leads for distribution and/or sell.

The Leads Posting Gateway is a customizable leads distribution solution that gives the leads provider control over all the steps in distributing a lead, including:

·      Capturing the lead information at the gateway level (HTTP or XML)

·      Generating leads distribution

·      Access to the Leads Provider System:

Secure storage of leads information

Creating leads distribution rules

Secured financial operation (debit, credit, balance operation, and credit cards processing)

Managing customers files

Access to large amount of moving companies

Operational and managerial reports

·      And more, depending on the leads provider's business requirements

The security of a lead posting transaction is assured through a 128-bit Secure Sockets Layer (SSL) connection between the provider Web server/Web site and the Leads Posting Gateway.

 

 

Developer Support

 

There are several resources available to help you successfully integrate a moving leads Web server / Web site to the Leads Posting Gateway.

·      The Integration Test Center at http://gmove.granot.com/TESTLEADPOSTING.lidgw provides a test page.

·      If you can’t find what you need in the Integration Test Center, our Integration Team is to answer your questions by email at info@granot.com.

 

Submitting Leads

 

The leads posting gateway application programming interface (API) consists of required information fields (introduced in the following tables) and additional optional fields that can be submitted to the leads posting gateway for real-time leads distribution processing.

 

General Requirements

The following table represents the fundamental fields required for submitting a leads to the leads posting gateway.

FIELD NAME

VALUE DESCRIPTION

STRUCTURE and TYPE

NOTES

servtypeid

101 - Local Move

102 - Long Distance Move

103 - Auto Transport

104 - International Move

HTTP - 3 Characters

XML - Integer

HTTP – Optional

XML - Mandatory

firstname

Client's First Name

30 Characters

Optional when the full name is in a single string

lastname

Client's First Name 

30 Characters

Mandatory

ocity

origin city - 'from city'

30 Characters

Optional if zip code is provided

ostate

origin state - 'from state'

20 Characters

Abbreviation or full name ('NY' or 'New York')

ozip

origin zip code- 'from zip'

6 Characters

Optional when city and state are provided

dcity

destination city - 'to city'

20 Characters

Optional if zip code is provided

dstate

destination state - 'to state'

20 Characters

Optional if zip code is provided. Abbreviation or full name ('NY' or 'New York')

dzip

destination zip code- 'to zip'

6 Characters

Optional when city and state are provided

notes

Any additional information

Max characters

Can gather several additional notes that will be merged to a single remark. i.e. best time to call, client remarks, additional contact method (skype), etc.

movedte

Expected Move Date

HTTP - 10 Characters MM/DD/YYYY

XML – Date time

HTTP – Optional if posting dates in three parts. See below*

XML - Mandatory

movemmonth*

Move month

2 Characters

HTTP – Optional

‘06’ for June

moveday*

Move day

2 Characters

HTTP – Optional

 ‘20’

moveyear*

Move year

4 Characters

HTTP – Optional

 ‘2012’

email

client contact email

50 Characters

Optional

phone1

20 Characters

Optional

phone2

20 Characters

Optional

cell

20 Characters

Optional

leadno

The lead ID on the provider's system

20 Characters

Optional

source

The provider's remark on the source of the lead (name of a Web site, affiliate name, etc.)

70 Characters

Optional

moverref

Posting single lead directly to the mover account regardless the balance and  distribution criteria. This unique parameter is provided by the mover.

12 Characters

Optional

redirurl

Redirect HTTP posted form to a ‘thank-u-page.htm’

70 Characters

HTTP - Optional

mincount

Determine the minimum amount of sales for a specific lead to be distributed/sold

0-9

Optional
[0] - void

maxcount

Determine how many times a specific lead can be distributed/sold

0-9

Optional
[0] - void


 

Moving Lead Types

This section describes the moving lead types supported by the leads posting gateway and their specific field requirements.

Lead Type

Service Type ID (servtypeid)

Local Move Lead

101

Long Distance Move Lead

102

Auto Transport Lead

103

International Move Lead

104

 

Local & Long Distance Lead (101, 102)

FIELD NAME

VALUE DESRIPTION

STRUCTURE and TYPE

NOTES

weight

Pounds

HTTP - 6 Characters

XML - Integer

volume

Cubic Feet

HTTP - 6 Characters

XML - Integer

movesize

move size description

20 Characters

Studio 1500 LBS,

One bedroom 2800 LBS,

Two Bedrooms 3200 LBS...

Auto Transport (103)

[Add url to AUTo LEADS]

The Leads Posting Gateway can capture up to three different cars in a post.

FIELD NAME

VALUE DESRIPTION

STRUCTURE and TYPE

NOTES

make0

First vehicle maker

20 Characters

Toyota

model0

First vehicle model

20 Characters

Corolla

year0

First vehicle year

20 Characters

2009

autotype0

First vehicle auto type

20 Characters

Sedan

running0

1 – Yes

0 - No

HTTP – 1 Character

XML - Integer

1

make1

 

 

 

model1

 

 

 

year1

 

 

 

autotype1

 

 

 

running1

 

 

 

make2

 

 

 

model2

 

 

 

year2

 

 

 

autotype2

 

 

 

running2

 

 

 

* All numeric indexes are zero relative (first make:make0, second make:make1, third make: make2)

 

International Move Lead (104)

FIELD NAME

VALUE DESRIPTION

STRUCTURE and TYPE

NOTES

ocountry

origin country- 'from country

20 Characters

Only for International leads

dcountry

destination country - 'to country'

20 Characters

Only for International leads

 

Post Locations (URI)

There are three leads posting gateway URLs:

·         Local, Long Distance, and International Moves

·         Auto Transport

·         Inventory for Local and Long Distance Moves (more information in the Posting Inventory Items topic)

Direct post of leads new

It is possible to post leads to specific movers by denoting their email (MOVERREF) on the URI string.

i.e. http://leads.granot.com/LEADSGWXML.lidgw?&API_ID=E432CD67C51E&MOVERREF=leads@company1.com,leads@mover2.com...

The email of the mover is provided by the mover itself (it is also have to match the setup in the moving software).

Moving Leads (Local, Long Distance, and International Moves) Post Location

 

The leads provider Web Server/Web site should submit leads’ information to the following leads posting gateway URL:

·         HTTP – http://leads.granot.com/LEADSGWHTTP.lidgw?&API_ID=E432CD67C51E[&MOVERREF=]*

·         XML - http://leads.granot.com/LEADSGWXML.lidgw?&API_ID=E432CD67C51E[&MOVERREF=]*

* [Optional]  -  MOVERREF is part of the URI string. Example: ...&API_ID=E432CD67C51E&MOVERREF=leads@company1.com,leads@mover2.com...

Auto Transport Post Location

The leads provider Web Server/Web site should submit auto transport leads to the following leads posting gateway URL:

·         HTTP --http://leads.granot.com/LEADSAUTOGWHTTP.lidgw?&API_ID=E432CD67C51E

·         XML- http://leads.granot.com/LEADSAUTOGWXML.lidgw?&API_ID=E432CD67C51E

 

Integration Test Center: http://test.granot.com/TESTLEADAUTOPOSTING.lidgw

 

 

Provider’s Login ID and protocols

 

The leads provider API Login ID (12 characters) is provided in the leads provider package and must be stored securely.

The API Login ID is an authentication key and it is required for accessing the leads posting gateway. The API_ID is part of the URL string (using the GET method).

The API_ID for the general test account is E432CD67C51E.

Protocols

The Leads Posting Gateway supports three protocols of data; HTTP, XML low level, and XML DTD.

·      HTTP - simple post of a form. Usually posted directly from the Web site's form using the post method.

·      XML (low level) - simple structure with xml elements and tags which contains the leads information (example)

·      XML DTD - Also known as XML High Level. It is a pre-defined document that contains both the data definition types and the leads information (example)

 

Transaction Response

 

The transaction response from the leads posting gateway provides the LEADID and the information about the status of a transaction; Error ID and Error Description.

 

There are two formats of the Leads Posting Gateway response string:

 

·         HTTP – returning a delimited string

·        XML – returning an XML low level string

Immediate Response

HTTP Response Example

XML Response Example

104360,13,missing client name,0,6


or

104360,0,OK,6,6

<?xml version="1.0"?>

<AAA>

   -  <BBB>

          <leadid>104360</leadid>

          <errid>13</errid>

          <msg>missing client name</msg>

          <sold>0</sold>

          <match>6</match>

      </BBB>

   </AAA>

 

Error Message Codes

ERRID

MSG

0

OK (no errors)

11

Missing provider's API_ID

12

Provider's reference does not exist in the system

13

Inactive provider

14

Missing client name

15

Missing contact information (phone and email)

16

Invalid move date

17

Missing 'from state'

18

Missing 'to state'

19

Invalid 'from state'

20

Invalid 'to state'

21

Missing country (international lead)

22

Inventory was not captured

23

Invalid lead ID when updating inventory

24

Empty post

25

No matches were found / Lead does not match minimum distribution

26

Duplicate Lead (verified by the Email)

27

Mover was not found (invalid MOVERREF)

 

 

Posting Inventory Items

 

Inventory items can be posted for local, long distance, and international moves (servtypeid 101, 102, 104). The inventory has to be posted after a successful posting of the basic lead information and receiving the LEADID number (view the transaction response in the above example). The LEADID number has to be added to the post URL for complete relation between the inventory items and leads information.

The leads posting gateway can capture up to 100 items per lead.

 

FIELD NAME

VALUE DESRIPTION

STRUCTURE and TYPE

NOTES

item0

Item description

VARCHAR(50)

Sofa

lbs0

Weight in pounds

HTTP – VARCHAR(6)

XML – Numeric 8,2

12.50

qty0

Quantity

HTTP – VARCHAR(3)

XML - Integer

1

roomname0 [new]

Room Name

VARCHAR(50)

John’s Room

.

 

 

 

.

 

 

 

.

.

 

 

 

item99

 

 

 

lbs99

 

 

 

qty99

 

 

 

roomname99

* All numeric indexes are zero relative (first item:item0, second item:item1, …, hundred  item: item99)

Inventory Post URL

HTTP:

https://gmove.granot.com/LEADSINVGWHTTP.lidgw?&API_ID=E432CD67C51E&LEADID=[LEADID]

or

https://gmove.granot.com/LEADSINVGWHTTP.lidgw?&API_ID=E432CD67C51E&&EMAIL=[EMAIL]

XML:

https://gmove.granot.com/LEADSINVGWXML.lidgw?&API_ID=E432CD67C51E&LEADID=[LEADID]

or

https://gmove.granot.com/LEADSINVGWXML.lidgw?&API_ID=E432CD67C51E&&EMAIL=[EMAIL]

Test and Demo Page: http://gmove.granot.com/TESTLEADINVPOSTING.lidgw?&LEADID=104484

 

 

Demo Account Information

 

The leads information can be posted directly from a web-page or from a script processor (web-server)

The API_ID for the general test account is E432CD67C51E.

 

Features of Leads Provider System

             

The Leads Provider System is a secured web-based application for operating and managing all tasks involved from capturing the lead, distribution, and processing the payments.  The following table lists the major features of the system.

 

Feature

Description

Operation view

Overture page for overall view on the business operation and profits.

Customer Information

View on the customer information as stored in the general pool of moving companies

Contact  persons

This feature allows providers to manage privately (create, edit, delete) contact persons for each customer

Make a Payment

·         Transact online credit card payment

·         Transact online eChecks payment

·         Record any other payments (checks, cash, wires)

Billing

Financial statement for each customer

Rules

Leads distribution rules for each customer

Credit Cards Info

Manage all credit cards for all customers

Credit Cards Process

Supporting the following gateways:

·         Skipjack

·         Authorize.net

Regions

Managing collection of states for leads distribution

Search Customers

 

New Customer

Adding new customer to the general pool of customers

Balance Report

 

Payments Report

 

Claims

Accepting or Declining claims for allegedly pseudo leads

Remarks

Advance module to record remarks on any object (customer, contact, lead, payment, credit card, etc.)

Leads In Report

Leads capturing report

Leads Out Report

Leads Distributing report

Pivot Reports

Diverse reports on business operation

Settings

·         Adding users to the system

·         Adjust services pricing

·         Adding merchant accounts for credit card processing

 

 

 

Accessing the Leads Provider System

 

The logon screen for the Leads Provider System is through GRANOT INC Web site; http://www.granot.com.

You will get two sets of username and password.

·         First set – Customer entry level

·         Second set – User entry level (one who uses the system).

After logging the system, the main user can open additional user accounts.

----