GINBOX.io

Implementation Steps

Step 1: Signup with https://www.ginbox.io/accounts/ with your official email account. Once account created please visit account section and fill all details pertaining to your business, server IP Address (IPV4) etc. Save the values. All editable values can be edited later also but need to be completed to enable usage of API.

Step 2: Completion of All fields in My account section will automatically issue a token on Access key page and will remain active for period of 180 days and completion of all fields in my account section.

Step 3: Token keys are restricted to IP Address (IPV4).

Step 4: There is one API which need to be integrated and on successful validation it will return the parameter values as detailed below. Note : if you use CMS like Shopify, WooCommerce, Magento etc please first search plugin/APP in respective marketplaces by name of "GINBOX" and download from there and follow steps 1-3 only.

Note :- This Integration of API will be on Server Side not Client Side and the IP mentioned in the profile should be of the Server (For Testing Purposes you can mention your system's IPv4)

API Integration Details

API Usage

This api enable user/client to get full addresses using generated token. The address can be get based on the following parameters.

API Endpoint:
https://www.ginbox.io/utils/api/v1/third-party-full-address
Parameters Description
token Generated token using the above API.
ginbox_number Ginbox number of the client.
Example Python request 
                                    
import requests

url = "https://www.ginbox.io/utils/api/v1/third-party-full-address"

payload={
    'token': 'generated_token',
    'ginbox_number': 'ginbox_number'
}

files=[

]

headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

Success Response

The api can only fetch address on successful validation of the token. The following responses based on multiple criteria can be observed.

Parameters Description
first_name First Name.
last_name Last Name.
state State.
mobile_number 10 digit Mobile Number.
is_primary Flag if the address is a primary address.
country_code_alpha_two Country Code.
telephone_code Telephone Code for Country.
country_flag Country flag image.
profile_image Profile picture of the customer.
customer_ginbox_number Ginbox number of the customer.
country_name Customer's Country Name.
email Customer's email address.
address_line_1 Customer's Street Address.
city Customer's City.
pincode Pincode number.
is_private Boolean flag if information is private.
latitude Geographic Latitude.
longitude Geographic Longitude.
Example Response 
                                    
{
    "ginbox_number": {
        "first_name": "Chip",
        "last_name": "The",
        "state": "New York",
        "mobile_number": "+12152686931",
        "is_primary": true,
        "country_code_alpha_two": "US",
        "telephone_code": 1,
        "country_flag": "https://www.ginbox.io/media/country_flag/us.png",
        "profile_image": "https://www.ginbox.io/media/profile_pictures/84862e61-7e75-43d7-b377-622c2e1a2429.jpg",
        "customer_ginbox_number": "THECHIP911",
        "country_name": "United States",
        "email": "thechip911@gmail.com",
        "address_line_1": "line 1",
        "city": "New York",
        "pincode": "10001",
        "is_private": true,
        "latitude": 40.7128,
        "longitude": 74.0060,
        "state_code": "NY",
        "country_code": "US"
    }
}

API Error Responses

Primary Address Unavailable

This error originates when a customer has not added any primary address associated with the passed GINBOX Number.

Status Description
404 Not Found.
Example Response 
                                    
{
    "status": "No Primary Address is associated with this Ginbox Number",
    "data": {}
}

Privacy is turned ON

This is response is generated when the customer has marked his primary address as private.
If the privacy is not set the address can be fetched without appending the phone number of the customer
NOTE: In this case GINBOX number should be appended with last 4-digits of customer's phone number.

Response Status
Status Code Description
403 Forbidden client.
Examples
GINBOX No. Description
THECHIP9113210 The GINBOX Number is an alphanumeric code corresponding to the customer while the last 4 digits of this alphanumeric code are the from the phone number of the customer.
[GINBOX No.][Last 4-digits of the phone number]
Example Response 
                                    
{
    "status": "User preferred Privacy for his address. Kindly enter last 4 digits of his mobile number after his GINBOX number and search again. Ex:  JAMESROGH1234",
    "data": {}
}
If Phone Number Entered is incorrect.
                                    
{
    "status": "Last 4 character should be numeric",
    "data": {}
}

No User Found

This error is originated when a alphanumeric code (Ginbox No.) is passed but it does not corresponds to a valid user account.

Status Description
404 Not Found.
Example Response 
                                    
{
    "status": "No Primary Address is associated with this Ginbox Number",
    "data": {}
}

Token Expired

This error originates when a token used is expired of its lifetime.

Status Code Description
403 Forbidden client.
Example Response 
                                    
{
    "status": "This Ginbox Number is not associated with any user.",
    "data": {}
}

Key Disabled

This error originates the admin has disabled your keys.

Status Code Description
403 Forbidden client.
Example Response 
                                    
{
    "status": "Please ask admin to activate key"
}

Key Invalid

This error originates when key used for the validation is invalid.

Status Code Description
401 Unauthorized client.
Example Response 
                                    
{
    "status": "Please ask admin to provide keys."
}