Locations Endpoint

Endpoint Actions

Create Record

POST /v2/locations

{
    "location": {
        "parent_id":"22222222-2222-2222-2222-222222222222", // Required
        "name":"Brand Test", // Required
        "branding_domain_url":"test.domain.com", // Required
        ... // Optional Fields Here
    }
}
{
    "location": {
        "id": "54c11750-a6c9-af57-e77a-da021bf9c0b1",
        "account_number": null, 
        "location_api_id": null,
        "name": "Brand Test",
        "address1": null,
        "address2": null,
        "city": null,
        "state": null,
        "zip_code": null,
        "office_phone": null,
        "office_ext_phone": null,
        "fax": null,
        "aba": null,
        "dda": null,
        "ticket_hash_key": null,
        "tz": "America/New_York",
        "receipt_logo": null,
        "created_ts": 1421936806,
        "modified_ts": null,
        "location_api_key": null,
        "branding_domain_url": "test.domain.com",
        "parent_id": "22222222-2222-2222-2222-222222222222",
        "country": "USA",
        "_links": {
            "self": {
                "href": "{url}/v2/locations/54c11750-a6c9-af57-e77a-da021bf9c0b1"
            }
        }
    }
}

Update Record

PUT /v2/locations/{id}

{
    "location": {
        "office_phone": "2485551111",
        ... // Other fields and values for update
    }
}
 {
    "location": {
        "id": "54c1b053-f074-1795-1ba3-2feb99d91491",
        "account_number": null,
        "location_api_id": null,
        "name": "Test Retail (m9clq830w769lik9)123",
        "address1": null,
        "address2": null,
        "city": null,
        "state": null,
        "zip_code": null,
        "office_phone": "2485551111",
        "office_ext_phone": null,
        "fax": null,
        "aba": null,
        "dda": null,
        "ticket_hash_key": null, 
        "tz": "America/New_York",
        "receipt_logo": null,
        "created_ts": 1421937392,
        "modified_ts": 1421937514,
        "location_api_key": null,
        "branding_domain_url": "wo74cjoi4u8oajor.domain.com",
        "parent_id": "54c0bf68-e516-ebb1-ba80-ee5793e30557",
        "country": "USA",
        "_links": {
            "self": {
                "href": "{url}/index.php/v2/locations/54c1b053-f074-1795-1ba3-2feb99d91491"
            } 
        }
    }
}

View Single Record

GET /v2/locations/{id}

{
    // Empty Payload - Not Needed Here
}
{
    "location": { 
        "id": "54c1b053-f074-1795-1ba3-2feb99d91491",
        "account_number": null,
        "location_api_id": null,
        "name": "Test Retail (m9clq830w769lik9)123",
        "address1": null, 
        "address2": null,
        "city": null,
        "state": null,
        "zip_code": null,
        "office_phone": null,
        "office_ext_phone": null,
        "fax": null,
        "aba": null,
        "dda": null,
        "ticket_hash_key": null,
        "tz": "America/New_York",
        "receipt_logo": null,
        "created_ts": 1421937392, 
        "modified_ts": 1421937514,
        "location_api_key": null,
        "branding_domain_url": "wo74cjoi4u8oajor.domain.com",
        "parent_id": "54c0bf68-e516-ebb1-ba80-ee5793e30557",
        "country": "USA",
        "_links": {
            "self": {
                "href":"{url}/v2/locations/54c1b053-f074-1795-1ba3-2feb99d91491" 
            }
        }  
    }
}

View Record List

GET /v2/locations

Note: Filters can be used to search for Locations by including the columns you want to filter on as URL parameters. i.e. /v2/locations?field=value&field2=value2

{
    // Empty Payload - Nothing Needed Here
}
{
    "locations": [
        {
            "id": "54c1b053-f074-1795-1ba3-2feb99d91491",
            "account_number": null,
            "location_api_id": null, 
            "name": "OLUTest Retail (m9clq830w769lik9)123",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip_code": null,
            "office_phone": null,
            "office_ext_phone": null,
            "fax": null,
            "aba": null,
            "dda": null,
            "ticket_hash_key": null,
            "tz": "America/New_York",
            "receipt_logo": null,
            "created_ts": 1421937392,
            "modified_ts": 1421937514,
            "location_api_key": null, 
            "branding_domain_url": "wo74cjoi4u8oajor.zeamster.com",
            "parent_id": "54c0bf68-e516-ebb1-ba80-ee5793e30557",
            "country": "USA",
            "_links": {
                "self": {
                    "href": "{url}/v2/locations/54c1b053-f074-1795-1ba3-2feb99d91491"
                } 
            }
        },
        ... // Other Locations Here
    ],
    "meta": { 
        "pagination": {
            "links": {
                "self": {
                    "href": "{url}/v2/locations?page_size=3&page=1"
                },
                "next": {
                    "href": "{url}/v2/locations?page_size=3&page=2"
                },
                "last": {
                    "href": "{url}/v2/locations?page_size=3&page=157"
                }
            },
            "totalCount": 469,
            "pageCount": 157,
            "currentPage": 0,
            "perPage": 3
        },
        "sort": {
            "attributes": {
                "id": "desc"
            } 
        }
    }
}

 

Fields

Name Format Min Max Required on Post (Create) Required on Put (Update) System Generated Comments
id string 24 36     Unique id of location
aba string 9 9       Aba / Routing
account_number string 0 32       Account number
address1 string 0 32       Address 1
address2 string 0 32       Address 2
branding_domain_id string 24 36       GUID for Branding Domain. Required if is_new_domain is false
branding_domain_title string   64       Branding domain title. Required if is_new_domain is true
branding_domain_url string   64       Branding domain url. Required if is_new_domain is true
city string 0 100       City name
contact_email_trx_receipt_default boolean         If true, will email contact receipt for any transaction
country string 0 20       the country of the location, current possible values are : USA, CAN
created_ts integer 10 10     created timestamp
dda string 3 32       Dda
default_ach string 24 36       GUID for Location's default ACH Product Transaction
default_cc string 24 36       GUID for Location's default CC Product Transaction
developer_company_id string 24 36       GUID for Developer Company
email_reply_to string   60       Used as from email address when sending various notifications
fax string 10 10       Fax number
is_new_domain boolean           Indicates that a new branding domain is associated with location. Must pass branding_domain_url and branding_domain_title if true
location_api_id string 24 36       Location api ID
location_api_key string 36 36     Location api key
location_c1 string   128       Can be used to store custom information for location.
location_c2 string   128       Can be used to store custom information for location.
location_c3 string   128       Can be used to store custom information for location.
modified_ts integer 10 10       Timestamp for last modification
name string 1 64     Name of the company
office_phone string 10 10       Office phone number
office_ext_phone string 0 10       Office phone extension number
parent_id string 24 36     Location GUID of the parent location
recurring_notification_days_default integer           # of days prior to a Recurring running that a notification should be sent
receipt_logo string 0 256       Receipt logo
show_contact_files boolean           If set to true will show "Files" tab on Contact
show_contact_notes boolean           If set to true will show "Notes" tab on Contact
state string   100       State name
ticket_hash_key string 36 36     Ticket hash key
tz string 0 24     Time zone
zip_code string 5 10       Zip code of the city

 

Expands (Related Records)

For detail on how to use Expands on an Endpoint, please visit the Expands (Related Records) page.

Related Record Expand ID
Branding Domain branding_domain
Created User created_user
Developer Company developer_company
Product Transaction product_transactions
Product Recurring product_recurring
Product File product_file
Parent parent
Terminals terminal

 

Expand Examples

Below are some examples of “expanding” this endpoint to one of the above related records.

Parent Location

GET /v2/locations/{id}?expand=parent

{
    "locations": [
        {
            "id": "{location_id}",
            "name": "Sample Company Location",
            ... // Other Location properties
            "parent": {
                "id": "{parent_location_id}",
                "location_api_id": "{integrator's location uuid}",
                "name": "Sample Company Headquarters",
                "address1": "123 Main Street",
                "address2": "",
                "city": "Novi",
                "state": "MI",
                "zip_code": "48375",
                "office_phone": "2481234567",
                "office_ext_phone": "",
                "fax": "",
                "account_number": "",
                "ticket_hash_key": "{system generated value}",
                "tz": "America/New_York",
                "created_ts": 1392066931,
                "modified_ts": 1549634496,
                "location_api_key": "{system generated value}",
                "email_reply_to": "reply@some.email",
                "branding_domain_id": "{UUID for location's branding domain}",
                "parent_id": "{location_id for parent of this location parent}",
                "location_c1": null,
                "location_c2": null,
                "location_c3": null,
                "contact_email_trx_receipt_default": false,
                "default_cc": "{location's default CC Product Service UUID}",
                "default_ach": "{location's default ACH Product Service UUID}",
                "show_contact_notes": 1,
                "show_contact_files": 1,
                "recurring_notification_days_default": 0,
                "_links": {
                  "self": {
                    "href": "{domain}/v2admin/locations/{parent_location_id}"
                    }
                }
            }
        }
    ]
}

Developer Company

GET /v2/locations/{id}?expand=developer_company

{
    "locations": [
        {
            "id": "{location_id}",
            "name": "Sample Company Location",
            ... // Other Location properties
            "developer_company": {
                "id": "{developer company uuid}",
                "title": "ACME Developers Group",
                "description": null,
                "created_ts": 1529005121,
                "modified_ts": 1529005121,
                "created_user_id": "{user UUID that created record}",
                "modified_user_id": "{user UUID that last modified record}",
                "_links": {
                    "self": {
                        "href": "{domain}/v2/developercompanies/{developer company uuid}"
                    }
                }
            }
        }
    ]
}

Branding Domain

GET /v2/locations/{id}?expand=branding_domain

{
    "locations": [
        {
            "id": "{location_id}",
            "name": "Sample Company Location",
            ... // Other Location properties
            "branding_domain": {
                "allow_contact_signup": false,
                "allow_contact_registration": true,
                "allow_contact_login": true,
                "registration_fields": [
                  "city",
                  "account_number"
                ],
                "id": "{Branding Domain UUID}",
                "url": "{domain}",
                "title": "Sample Branding Domain",
                "logo": null,
                "company_name": null,
                "support_email": null,
                "created_user_id": "11e7a8452518e768b2661a9a",
                "created": "2017-11-02 19:11:17",
                "modified_user_id": "11e7a8452518e768b2661a9a",
                "modified": "2018-11-12 18:42:40",
                "nav_color": null,
                "nav_logo": "{images.domain.com}/.../logo.png",
                "fav_icon": null,
                "button_primary_color": null,
                "logo_background_color": null,
                "icon_background_color": null,
                "menu_text_background_color": null,
                "menu_text_color": "",
                "right_menu_background_color": null,
                "right_menu_text_color": null,
                "button_primary_text_color": null,
                "aes_key": null,
                "help_text": "{... help message html ...}",
                "email_reply_to": null,
                "custom_javascript": null,
                "custom_theme": "default",
                "custom_css": "xzxzx",
                "created_ts": 1509649877
            }
        }
    ]
}

Using Multiple Expands

You can use multiple expands on an endpoint. Simply include them separated by a comma(s) like so:

GET /v2/locations/{id}?expand=branding_domain,developer_company,parent

{
    "locations": [
        {
            "id": "{location_id}",
            "name": "Sample Company Location",
            ... // Other Location properties
            "branding_domain": {
                ... // Branding domain properties
            },
            "parent": {
                ... // Parent properties
            },
            "developer_company": {
                ... // Developer Company properties
            }
        }
    ]
}

Location Credentials

This is a special endpoint that allows updating of these fields:

location_api_id, location_api_key, ticket_hash_key

PUT /v2/locations/{id}/credentials

 

{
    "location":{
        "location_api_id":"APIIDDD12345"
    }
}
Field Name Min Max Description
location_api_id 1 36 Location API ID
location_api_key 1 36 Location API Key
ticket_hash_key 1 36 Ticket Hash Key