NAV Navbar
shell ruby
  • Introduction
  • Authentication
  • Website
  • Leads
  • Webhooks
  • Errors
  • Introduction

    Welcome to the Maptrack Beta API! You can use our API to access MapTrack API endpoints, which can get you information regarding websites added by you and leads generated by these websites.

    You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Authentication

    Every endpoint is protected using your account's secret key. An example authenticated request looks like this:

    curl -X GET -G 'https://app.maptrackpro.com/api/v1/resource' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx"
    
    require 'httparty'
    
    response = HTTParty.get("https://app.maptrackpro.com/api/v1/resources", headers: { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" })
    

    Make sure to replace sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx with your secret key which will be provided to you.

    MapTrack uses secret keys to allow access to the API and expects this key to be included in all API requests to the server in a header that looks like the following:

    Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx

    Website

    Create a Website

    An example request to create a new website looks like this:

    require 'httparty'
    
    headers = { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" }
    data = { 
      name: "MapTrack",
      url: "https://demo.maptrackpro.com",
      description: "Demo MapTrack Website"
    }
    
    response = HTTParty.post("https://app.maptrackpro.com/api/v1/websites", body: data, headers: headers)
    
    curl -X POST -G 'https://app.maptrackpro.com/api/v1/websites' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d name="MapTrack" \
    -d url="https://demo.maptrackpro.com" \
    -d description="Demo"
    

    The above command returns JSON structured like this:

    {
        "message": "Website created successfully",
        "data": {
            "id": 18,
            "name": "MapTrack",
            "url": "https://demo.maptrackpro.com",
            "status": "active",
            "tracking_code": "MT-000000-CD",
            "created_at": "2017-10-18T05:46:24.298Z"
        }
    }
    

    This endpoint creates a new website.

    HTTP Request

    POST https://app.maptrackpro.com/api/v1/websites

    BODY Parameters

    Parameter Description Required
    name The name of the website to be created True
    url The HTTPS url of the website to be created True
    description The description of the website to be created True

    Retrieve all Websites

    An example request to fetch all websites looks like this:

    require 'httparty'
    
    response = HTTParty.get("https://app.maptrackpro.com/api/v1/websites", headers: { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" })
    
    curl -X GET -G 'https://app.maptrackpro.com/api/v1/websites' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx"
    

    The above command returns JSON structured like this:

    {
        "message": "Websites retrieved successfully",
        "data": [
            {
                "id": 18,
                "name": "MapTrack",
                "url": "https://demo.maptrackpro.com",
                "status": "active",
                "tracking_code~": "MT-000000-CD",
                "created_at": "2017-10-18T05:46:24.298Z"
            },
            {
                "id": 19,
                "name": "MapTrack 2",
                "url": "https://demo.maptrackpro.com",
                "status": "active",
                "tracking_code~": "MT-111111-CD",
                "created_at": "2017-10-18T05:46:24.298Z"
            },
            {
                "id": 20,
                "name": "MapTrack 3",
                "url": "https://demo.maptrackpro.com",
                "status": "active",
                "tracking_code~": "MT-222222-CD",
                "created_at": "2017-10-18T05:46:24.298Z"
            }
        ],
        "meta": {
            "total": 3,
            "per_page": 10,
            "page": 1,
            "page_count": 1
        }
    }
    

    An example request to fetch all websites using query parameters looks like this:

    require 'httparty'
    
    headers = { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" }
    query = { 
      from: "2017-10-17",
      to: "2017-10-19",
      page: 1
    }
    
    response = HTTParty.get("https://app.maptrackpro.com/api/v1/websites", query: query, headers: headers)
    
    curl -X GET -G \
    'https://app.maptrackpro.com/api/v1/websites' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" \
    -d from="2017-10-17" \
    -d to="2017-10-19" \
    -d page=1
    

    The above command returns JSON structured like this:

    {
        "message": "Websites retrieved successfully",
        "data": [
            {
                "id": 18,
                "name": "MapTrack",
                "url": "https://demo.maptrackpro.com",
                "status": "active",
                "tracking_code~": "MT-000000-CD",
                "created_at": "2017-10-18T05:46:24.298Z"
            },
            {
                "id": 19,
                "name": "MapTrack 2",
                "url": "https://demo.maptrackpro.com",
                "status": "active",
                "tracking_code~": "MT-111111-CD",
                "created_at": "2017-10-18T05:46:24.298Z"
            },
            {
                "id": 20,
                "name": "MapTrack 3",
                "url": "https://demo.maptrackpro.com",
                "status": "active",
                "tracking_code~": "MT-222222-CD",
                "created_at": "2017-10-18T05:46:24.298Z"
            }
        ],
        "meta": {
            "total": 3,
            "per_page": 10,
            "page": 1,
            "page_count": 1
        }
    }
    

    This endpoint retrieves all websites.

    HTTP Request

    GET https://app.maptrackpro.com/api/v1/websites

    Query Parameters

    Parameter Default Description Format
    from all time filters by a set datetime Date: 2018-03-19 Date/Time: 2018-03-19T18:39:51
    to current date filters by a set datetime Date: 2018-03-19 Date/Time: 2018-03-19T18:39:51
    status active filters by active or inactive

    Pagination Parameters (Meta)

    Parameter Default Description
    page 1 The default retrieves the first page.
    per_page 10 The number of websites to retrieve per page with a max of 500.

    Retrieve a Website

    An example request to fetch a specific website looks like this:

    require 'httparty'
    
    response = HTTParty.get("https://app.maptrackpro.com/api/v1/websites/18", headers: { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" })
    
    curl -X GET -G 'https://app.maptrackpro.com/api/v1/websites/18' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx"
    

    The above command returns JSON structured like this:

    {
        "message": "Website retrieved",
        "data": {
            "id": 18,
            "name": "MapTrack",
            "url": "https://demo.maptrackpro.com",
            "status": "active",
            "tracking_code~": "MT-000000-CD",
            "created_at": "2017-10-18T05:46:24.298Z"
        }
    }
    

    This endpoint retrieves a specific website.

    HTTP Request

    GET https://app.maptrackpro.com/api/v1/websites/<ID>

    URL Parameters

    Parameter Description Required
    ID The ID of the website to retrieve True

    Deactivate a Website

    An example request to deactivate a website looks like this:

    require 'httparty'
    
    response = HTTParty.post("https://app.maptrackpro.com/api/v1/websites/18/deactivate", headers: { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" })
    
    curl -X POST -G 'https://app.maptrackpro.com/api/v1/websites/18/deactivate' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx"
    

    The above command returns JSON structured like this:

    {
        "message": "Website successfully deactivated",
        "data": {
            "id": 18,
            "name": "MapTrack",
            "url": "https://demo.maptrackpro.com",
            "status": "inactive",
            "tracking_code~": "MT-000000-CD",
            "created_at": "2017-10-18T05:46:24.298Z"
        }
    }
    

    This endpoint deactivates a website.

    HTTP Request

    POST https://app.maptrackpro.com/api/v1/websites/<ID>/deactivate

    URL Parameters

    Parameter Description Required
    ID The ID of the website to deactivate True

    Activate a Website

    An example request to activate a website looks like this:

    require 'httparty'
    
    response = HTTParty.post("https://app.maptrackpro.com/api/v1/websites/18/activate", headers: { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" })
    
    curl -X POST -G 'https://app.maptrackpro.com/api/v1/websites/18/activate' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx"
    

    The above command returns JSON structured like this:

    {
        "message": "Website successfully activated",
        "data": {
            "id": 18,
            "name": "MapTrack",
            "url": "https://demo.maptrackpro.com",
            "status": "active",
            "tracking_code~": "MT-000000-CD",
            "created_at": "2017-10-18T05:46:24.298Z"
        }
    }
    

    This endpoint activates a deactivated website.

    HTTP Request

    POST https://app.maptrackpro.com/api/v1/websites/<ID>/activate

    URL Parameters

    Parameter Description Required
    ID The ID of the website to activate True

    Delete a Website

    An example request to delete a website looks like this:

    require 'httparty'
    
    response = HTTParty.delete("https://app.maptrackpro.com/api/v1/websites/18", headers: { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" })
    
    curl -X DELETE -G 'https://app.maptrackpro.com/api/v1/websites/18' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx"
    

    The above command returns JSON structured like this:

    {
        "message": "Website along with it's collected data have been queued for deletion"
    }
    

    This endpoint queues a website for deletion.

    HTTP Request

    DELETE https://app.maptrackpro.com/api/v1/websites/<ID>

    URL Parameters

    Parameter Description Required
    ID The ID of the website to delete True

    Leads

    Retrieve all Leads

    An example request to fetch all leads looks like this:

    require 'httparty'
    
    response = HTTParty.get("https://app.maptrackpro.com/api/v1/leads", headers: { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" })
    
    curl -X GET -G 'https://app.maptrackpro.com/api/v1/leads' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx"
    

    The above command returns JSON structured like this:

    {
        "message": "Leads retrieved successfully",
        "data": [
            {
                "website_name": "MapTrack",
                "website_id": 18,
                "first_name": null,
                "last_name": null,
                "email": null,
                "phone_number": null,
                "city": "Flagstaff",
                "state": "AZ",
                "address": "2059 Paleo Pl",
                "zipcode": "86005",
                "full_address": "2059 Paleo Pl, Flagstaff, AZ 86005",
                "category": "residential",
                "created_at": "2018-04-27T13:55:49.908Z",
                "pageview_history": [  
                    {  
                        "page_url": "https://www.maptrackpro.com",
                        "visited_at": "2018-10-14T15:21:31.426Z"
                    },
                    {  
                        "page_url": "https://www.maptrackpro.com/contact",
                        "visited_at": "2018-10-14T15:32:31.426Z"
                    },
                    {  
                        "page_url": "https://www.maptrackpro.com/demo",
                        "visited_at": "2018-10-14T15:43:31.426Z"
                    }
                ]
            },
            {
                "website_name": "MapTrack",
                "website_id": 18,
                "first_name": null,
                "last_name": null,
                "email": null,
                "phone_number": null,
                "city": "Houston",
                "state": "TX",
                "address": "1200 Clay St",
                "zipcode": "77002",
                "full_address": "1200 Clay St, Houston, TX 77002",
                "category": "commercial",
                "created_at": "2018-04-26T16:26:15.926Z",
                "pageview_history": [  
                    {  
                        "page_url": "https://www.maptrackpro.com/features",
                        "visited_at": "2018-10-14T15:39:31.426Z"
                    },
                    {  
                        "page_url": "https://www.maptrackpro.com/support",
                        "visited_at": "2018-10-14T15:43:31.426Z"
                    }
                ]
            }
        ],
        "meta": {
            "total": 23,
            "per_page": 2,
            "page": 1,
            "page_count": 12
        }
    }
    

    An example request to fetch all leads using query parameters looks like this:

    require 'httparty'
    
    headers = { Authorization: "Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" }
    query = { 
      from: "2018-04-25",
      to: "2018-04-27",
      city: "Houston"
    }
    
    response = HTTParty.get("https://app.maptrackpro.com/api/v1/leads", query: query, headers: headers)
    
    curl -X GET -G 'https://app.maptrackpro.com/api/v1/leads' \
    -H "Authorization: Bearer sk_auth_xxxxxxxxxxxxxxxxxxxxxxxx" \
    -d from="2018-04-25" \
    -d to="2018-04-27" \
    -d city="Houston"
    

    The above command returns JSON structured like this:

    {
        "message": "Leads retrieved successfully",
        "data": [
            {
                "website_name": "MapTrack",
                "website_id": 18,
                "first_name": null,
                "last_name": null,
                "email": null,
                "phone_number": null,
                "city": "Houston",
                "state": "TX",
                "address": "1200 Clay St",
                "zipcode": "77002",
                "full_address": "1200 Clay St, Houston, TX 77002",
                "category": "commercial",
                "created_at": "2018-04-26T16:26:15.926Z",
                "pageview_history": [  
                    {  
                        "page_url": "https://www.maptrackpro.com",
                        "visited_at": "2018-10-14T15:21:31.426Z"
                    },
                    {  
                        "page_url": "https://www.maptrackpro.com/contact",
                        "visited_at": "2018-10-14T15:32:31.426Z"
                    },
                    {  
                        "page_url": "https://www.maptrackpro.com/demo",
                        "visited_at": "2018-10-14T15:43:31.426Z"
                    }
                ]
            }
        ],
        "meta": {
            "total": 1,
            "per_page": 100,
            "page": 1,
            "page_count": 1
        }
    }
    

    This endpoint retrieves all leads.

    HTTP Request

    GET https://app.maptrackpro.com/api/v1/leads

    Query Parameters

    Parameter Default Description Format
    from all time filters by a set datetime Date: 2018-03-19 Date/Time: 2018-03-19T18:39:51
    to current date filters by a set datetime Date: 2018-03-19 Date/Time: 2018-03-19T18:39:51
    website_name all filters by a like match on the name of website
    website_id none filters by an exact match on a website id
    city none filters by a like match on the city
    state none filters by a like match on the state
    address none filters by a like match on the address
    zipcode none filters by a like match on the zipcode

    Pagination Parameters (Meta)

    Parameter Default Description
    page 1 The default retrieves the first page.
    per_page 10 The number of leads to retrieve per page with a max of 500.

    Webhooks

    MapTrack allows you send webhook events that notify your application any time an event happens on your account.

    You can register webhook URLs that we will notify any time an event occurs. When an event occurs e.g — a mailing address is successfully generated from your website, an Event is created and the data is sent to the URL provided.

    We send this data via an HTTP POST request, to any endpoint URLs that you have defined in your account’s Webhooks settings.

    Supported Events

    Event Trigger
    lead.generated Triggers when a new mailing address is generated.
    email.appended Triggers when an email address is appended to a generated mailing address.
    phone.appended Triggers when a phone number is appended to a generated mailing address.

    Configuring your Webhook settings

    Webhooks are configured in the Dashboard's Developer's settings section. Click Create Webhook and proceed to add a new URL for receiving webhooks.

    You can enter any URL as the destination for events. However, this should be a dedicated page on your server that is set up to receive webhook notifications. You can choose to be notified of all event types, or only specific ones.

    Receiving and responding to a Webhook notification

    Webhook data is sent to you as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an object, you can proceed to use whatever information is important to you.

    To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to us that you did not receive the webhook. This means that a URL redirection or a "Not Modified" response will be treated as a failure. Any form of information returned in the request headers or request body will be ignored by us.

    For non-test urls, we will attempt to deliver your webhooks for up to 25 times over 3 days with an exponential back off.

    To send a test event, simply add a test url on the Webhook settings page and proceed to select a test event. The event data will then be sent to the test url you provided.

    Errors

    The MapTrack API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your secret key is wrong.
    403 Forbidden -- You are not allowed to view the resource.
    404 Not Found -- The specified resource could not be found.
    406 Not Acceptable -- You requested a format that isn't json.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.