Introduction to ParkWhiz API v4.0

The API is available at https://api.parkwhiz.com/v4, and a sandbox API available at http://api.sandbox.parkwhiz.com/v4.

Please contact dev@parkwhiz.com with any questions or concerns.

API Usage Basics

Authentication

Many resources on the Parkwhiz API are only accessible if the requester has proper authorization. The way to access endpoints that require authentication is to use an OAuth2 access token as an authorization header (e.g. Authorization Bearer OAUTH_TOKEN). The POST /oauth/token endpoint can be used to issue a token as documented below



Token Generation Grant Flows

There are four "grant flows" that can be followed when requesting a token via POST /oauth/token. Each one has a different use case and target user, so care should be taken to ensure the right grant flow method is used for the right situation. These four methods are:

Grant Flow Name grant_type parameter value Use Case
The client credential flow grant_type=client_credentials Used by an app or trusted partner when user specific information doesn't need to be retrieved. This is most approriate for requests not associated with user data like GET /quotes. To access or modify user data (e.g. GET /bookings, GET /accounts/me) you must use a password grant or authorization code grant.
The password grant type grant_type=password Used when user information is known and the client credentials need to be concealed, such as in a client side web application, and specific user information needs to be accessed or modified.
The authorization code grant_type=authorization_code Used by an app or a trusted partner when they need to access or modify user specific information on behalf of a user but do not have access to the user's information to use a password grant.
The refresh token grant_type=refresh_token Used to refresh a token to prevent expiry. Cannot be used to regenerate a token generated from the client credentials flow.

Further information about each of these grant flows are listed in their respective sections:



Generating A Token With Client Credentials

A Parkwhiz authorized client application can request a token for a user by posting to /oauth/token with the query or body parameter grant_type=client_credentials. The ParkWhiz issued client_id and client_secret must be specified as query parameters, body parameters, or in an Authorization: HTTP Basic Auth header.

For example:

POST /oauth/token?grant_type=client_credentials&client_id=ASSIGNED_CLIENT_ID_1234&client_secret=ASSIGNED_CLIENT_SECRET_1234&scope=public

which will yield a response like:

{
  "access_token": "new_token_12345",
  "token_type": "bearer",
  "expires_in": 31557600,
  "scope": "public",
  "created_at": 1486143527
}
  • expires_in gives the number of seconds until the token expires (tokens expire a year after they are granted).
  • scope the authorization scope given to this token. See the scope section.
  • created_at when the token was created as a UNIX timestamp.

Use of this token via Authorization: Bearer OAUTH_TOKEN will uniquely and securely identify the client account. Note that the client credentials token is inherently limited in what it can do with respect to user accounts. The token is not associated with a user so GET /accounts/me will not retrieve any user information. Likewise user information in general cannot be modified or retrieved by this token. Requests not associated with user information like GET /quotes are appropriate for this token.

Generating A Token With Password Grant Type

Generating a token via client credentials is not recommended for all circumstances. For example, in a client side web application where requests are exposed to the user, using grant_type=client_credentials would be insecure. Additionally as stated in the client credentials section the token generated from that flow cannot access or modify user data.

Another way to generate a token is through using grant_type=password which uses parameters based on the attributes of the user who's being authenticated. This grant flow allows the holder of the token to access and modify the user information associated with the customer_email and customer_password used in the request.

An example request:

POST oauth/token?grant_type=password&scope=public&customer_email=you@yourdomain.com&customer_password=yourSecurePassword

with response:

{
  "access_token": "YOUR_ACCESS_TOKEN_1234",
  "token_type": "bearer",
  "expires_in": 31557600,
  "refresh_token": "YOUR_REFRESH_TOKEN_1234",
  "scope": "public",
  "created_at": 1486157828
}

Generating A User Authorization Token With Authorization Code Grant Type

A user authorization token is required for endpoints that access user information (e.g. GET /bookings). The password grant flow can generate a token with this level of clearance, however, in some cases an app or a trusted partner may need to access or modify information on behalf of a user when the information needed to use the password grant flow is not available. For this use case, the authorization code grant flow is recommended, that is, acquiring a token with the grant_type parameter set to authorization_code.

In order to use the authorization_code grant flow, the requester first must obtain a code from the oauth/authorize endpoint. The requests query or body parameters must contain a ParkWhiz issued client_id and client_secret, response_type=code, the client's redirect_uri, a scope (e.g. scope=partner) and either a customer_email or customer_id to identify the customer for whom authorization is being requested. The client_id and client_secret values can also be provided via an Authorization: HTTP Basic Auth header.

For example:

POST /oauth/authorize?response_type=code&customer_email=dev@parkwhiz.com&redirect_uri=http://yoursite.com/oauth/auth_code&client_id=ASSIGNED_CLIENT_ID&client_secret=ASSIGNED_CLIENT_SECRET&scope=partner

On successful acquisition of the authorization code, the client will be redirected to the specified redirect_uri, with the authorization code specified by the code query parameter. This authorization code is valid for 30 minutes.

The user authorization token can then be acquired by posting to /oauth/token with the query or body parameters grant_type=authorization_code, the client redirect as redirect_uri, and the previously acquired authorization code as code. The ParkWhiz issued client_id and client_secret must be specified as query parameters, body parameters, or in an Authorization: HTTP Basic Auth header.

An example token request using the authorization code:

POST /oauth/token?grant_type=authorization_code&client_id=ASSIGNED_CLIENT_ID&client_secret=ASSIGNED_CLIENT_SECRET&code=AN_AUTHORIZATION_CODE_1234&redirect_uri=https://api.parkwhiz.com/v3/oauth/auth_code&scope=internal

which will yield the response:

{
  "access_token": "YOUR_ACCESS_TOKEN_1234",
  "token_type": "bearer",
  "expires_in": 31557600,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "internal",
  "created_at": 1486404380
}

On successful token generation, you will be supplied with your new access_token, the token_type (bearer), scope of the token's permissions for the requested user, token creation time (created_at) as UNIX timestamp, and number of seconds until token expiration (expires_in). The default expiration time is 1 year.

Use of this token via Authorization: Bearer OAUTH_TOKEN will uniquely and securely identify the user account that was specified in the customer_email or customer_id field in the /oauth/authorize request. So, for example, a request GET /accounts/me will yield a response object of the user specified with customer_email or customer_id.

Refresh Token Grant Flow

The refresh token grant flow can be used to renew tokens before they expire without having to redo the flow used to originally acquire the token. For example, the authorization code grant flow yields a refresh_token as part of it's response upon success. To regenerate a new token with the same permissions using the refresh token:

POST /oauth/token?grant_type=refresh_token&client_id=ASSIGNED_CLIENT_ID&client_secret=ASSIGNED_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN

The request will return a new access_token and a new refresh_token which can be used to regenerate another token using the refresh token grant flow.

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 31557600,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "internal",
  "created_at": 1486409329
}

Note that the refresh token grant flow cannot be used to refresh a token generated from the client credentials grant flow.

None

Many of the endpoints in the ParkWhiz API may be used without authenticating. In general, resources are public if they are not related to a specific account and do not require a scope. Using the API without a token is useful if you are simply poking around or experimenting. Your rate limit will be significantly lower, and endpoints requiring authorization will return a 401.

If you are giving the API more than a cursory glance, consider using Client Credentials OAuth Token instead.

Scopes

The scope parameter defines what resources the returned authorization token will have access to. Currently the following scopes are supported: internal, mobile, partner, data and public where public is the default scope if no value is provided. data requires a data license. Scopes will have different api resources they can or cannot access. To determine whether a scope has access to a particular endpoint check the endpoints section.

To declare a scope, add as a parameter to the POST /oauth/authorize or the POST /oauth/token request. Example:

POST /oauth/token?grant_type=client_credentials&client_id=1234abcde&client_secret=abcd1234&scope=internal

will return:

{
  "access_token": "new_token_12345",
  "token_type": "bearer",
  "expires_in": 31557600,
  "scope": "internal",
  "created_at": 1486143527
}

Sorting

Available sortable params are documented per endpoint. You can sort by a parameter by specifying the parameter and including which way you would like to sort,asc or desc. For example, you can sort venues by distance, closest first, with this parameter:

?sort=distance:asc

We try to supply sane defaults so you don't have to include asc or desc everywhere. For example, sorting by just name will sort from a-z by default. Sorting by distance will return the closest results first. It would look like this:

?sort=name

Multiple sorting parameters can be supplied and separated with with spaces. It will look similar to:

?sort=name:desc distance

which will sort by name in descending order, followed by distance in ascending order.

Stats

As a utility, the API provides a stats parameter that can perform simple calculations on the results returned by the endpoint calls. For now, the only stat available is count.

To get the count of the number of objects returned from an api call, use result_format=stats&fields=stats:count. For example, to get the number of venues near Chicago, perform:

POST /venues?&q=coordinates:41.881943,-87.630976&result_format=stats&fields=count

which would return a response like:

{
  "count": 5903
}

The count should return the total number of objects returned by the database and pagination will not affect the results.

Searching

A common pattern used on several endpoints allows you to search by one of several types. These types are typically mutually exclusive. When retrieving price quotes for example, you can specify your destination with a variety of search types such as a geographic coordinate, a venue ID, an event ID or a set of geographic bounds.

These searches take a query string parameter q, which is formatted as a space separated list of query types and values. It will look similar to:

?q=coordinates:41.878,-87.626 distance:5

In the above example, you are querying within 5 miles of downtown Chicago. Keep in mind that the query string is space separated.

Pagination

By default, you will receive up to 100 results from endpoints that return lists. You may request fewer or step through pages of results using the per_page and page parameters. For example, per_page=10&page=3 indicates you would like records 21-30.

You may only request up to 100 results and requests for more will be capped.

As described in RFC 5988, a Link header field will help in paging through results. It will look similar to this:

Link: <https://api.parkwhiz.com/v4/bookings?page=3&per_page=10>; rel="next", <https://api.parkwhiz.com/v4/bookings?page=2&per_page=10>; rel="prev" <https://api.parkwhiz.com/v4/bookings?page=7&per_page=10>; rel="last"

The "_links" field of response bodies may also have "next" and "prev" links.

The following headers will be returned when paging is occurring:

Header Description
X-Pagination-Per-Page The maximum number of records being returned per page
X-Pagination-Total The total number of records
X-Pagination-Returned The number of records returned for this request
X-Pagination-Current-Page The current page
X-Pagination-Total-Pages The number of pages in the result set when using the given per page limit

Including or Limiting Fields

To keep the response payload to a minimum you can supply a fields parameter specifying only those fields that you wish to receive. The fields should be specified as a comma-separated list.

For example, to retrieve only the ID and geographic coordinates of a parking location, you might use something like this:

GET /v4/locations/2504?fields=id,entrances

You can also retrieve all of the default fields with :default, in addition to any others you specify. This is useful if you need a response field that is rarely used and not returned by default.

GET /v4/locations/2504?fields=:default,rating_summary

Namespacing fields

Fields can be namespaced to the object that they are referencing. The syntax for this is fields=object_name:field_name or fields=object_name::field_group_name for grouped fields. For example, getting the default fields and the rating summary on the location model can be done via namespacing the desired fields:

GET /v4/locations/2504?fields=location::default,location:rating_summary

It is recommended to use namespacing whenever possible, particularly because namespacing is required when requesting fields on linked resources

Grouped vs singular fields

The fields parameter may accept fields that return just one attribute on a resource. For example, fields=event:site_url will cause only the site_url attribute on the event model to be shown. Other fields may cause multiple attributes on a group to be returned. For example, fields=location::address will show the attributes: address1, address2, city, state, and postal_code on the location object. By convention fields that yeild a singular attribute use a single colon fields=object_name:field_name while grouped attributes use a double colon between the resource and the field group name fields=object_name::field_group_name.

Zooms

Zooms provide an easy way for a single request to return multiple related resources. Normally when requesting a resource additional API calls would be needed to fetch related resources as they are exposed in the _links field. For example when searching for parking for an event API calls would be needed to retrieve both the event information and the associated venue information. By using zooms, all of this data can be retrieved in a single request and will immediately be available to the API consumer.

As described in JSON Hypertext Application Language (Draft 7), related resources are linked in the "_links" field.

{
    "id": 2504,
    "name": "120 N LaSalle Garage",
    "reviews": { "href": "/locations/2504/reviews" },
    ...
    "_links": {
        "curies": [{ "name": "pw", "href": "https://api.parkwhiz.com/v4/doc/{rel}", "templated": true }],
        "self": { "href": "/locations/2504" },
        "pw:reviews": { "href": "/locations/2504/reviews" }
    }
}

Related resources may be retrieved by using the zoom parameter to cut down on the number of API calls needed. You may use a comma-separated list to request multiple resources.

For example, GET /events/31727?zoom=pw:venue will retrieve the details for event with id: 31727. The Venue the event is hosted at will be contained within the _embedded field.

{
  "id": 31727,
  "name": "Anything Goes",
  "venue_id": 382,
  "start_time": "2011-04-29T19:00:00.000-04:00",
  "end_time": "2011-04-29T22:00:00.000-04:00",
  "_embedded": {
    "pw:venue": {
      "id": 382,
      "name": "Stephen Sondheim Theatre",
      "address1": "124 West 43rd St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10036",
      "_links": {
        "self": {
          "href": "/venues/382"
        },
        "pw:events": {
          "href": "/venues/382/events"
        },
        "pw:quotes": {
          "href": "/quotes?q=venue_id:382"
        },
        "curies": [
          {
            "name": "pw",
            "href": "https://api.parkwhiz.com/v4/{rel}",
            "templated": true
          }
        ]
      }
    }
  },
  "_links": {
    "self": {
      "href": "/events/31727"
    },
    "pw:venue": {
      "href": "/venues/382"
    },
    "pw:quotes": {
      "href": "/quotes?q=event_id:31727"
    },
    "curies": [
      {
        "name": "pw",
        "href": "http://api.parkwhiz.com/v4/{rel}",
        "templated": true
      }
    ]
  }
}

Many resources have default zoomed resources. If you want to ensure no embedded resources are included in the response, you may set zoom=:none.

Specifying fields on linked resources

The fields included on the linked resources can be specified as described in the including or limiting fields section. The key is to namespace the included parameters for the linked resource using the format fields=object_name:field_name or fields=object_name::field_group_name for grouped fields. Additionally, if display fields are specified for the primary resource, those fields should also be namespaced.

For example, to show the site url of an event and the timezone for the venue that the event is hosted at use GET /events/31727?zoom=pw:venue&fields=event:site_url,venue:timezone. The response will include timezone for venue and the site_url for the event that is being retrieved.

{
  "site_url": "/stephen-sondheim-theatre-parking/anything-goes-31727/",
  "_embedded": {
    "pw:venue": {
      "timezone": "America/New_York",
      "_links": {
        "self": {
          "href": "/venues/382"
        },
        "pw:events": {
          "href": "/venues/382/events"
        },
        "pw:quotes": {
          "href": "/quotes?q=venue_id:382"
        },
        "curies": [
          {
            "name": "pw",
            "href": "https://api.parkwhiz.com/v4/{rel}",
            "templated": true
          }
        ]
      }
    }
  },
  "_links": {
    "self": {
      "href": "/events/31727"
    },
    "pw:venue": {
      "href": "/venues/382"
    },
    "pw:quotes": {
      "href": "/quotes?q=event_id:31727"
    },
    "curies": [
      {
        "name": "pw",
        "href": "http://api.parkwhiz.com/v4/{rel}",
        "templated": true
      }
    ]
  }
}

Note that the GET /quotes endpoint does not support specifying fields on zoomed resources. Zooms can be applied to any endpoint and will load related data into the _embedded field of the response.

Envelope

If envelope=true is passed in the query string, the response will be embedded in the data attribute of the returned object and additional information will be returned.

For example, it might look something like:

    {
        "status":200,
        "record_count":1,
        "start_timestamp":"2013-12-02T19:31:35.5362308Z",
        "end_timestamp":"2013-12-02T19:31:35.6299946Z",
        "time_taken":0.0937638,
        "data":[{
            "payload" : "here",
        }]
    }

The envelope may also contain information about the original request query. For a parking quote search from 6:30-9:30pm CST on December 28, 2015, given location_id 3939, the envelope may look like:

{
  "status": 200,
  "record_count": 1,
  "start_timestamp": "2015-12-03T16:14:09.819Z",
  "end_timestamp": "2015-12-03T16:14:10.081Z",
  "time_taken": 0.262123,
  "query": {
    "location_id": 3939,
    "start_time": "2015-12-28T12:30:00-06:00",
    "end_time": "2015-12-28T15:30:00-06:00"
  },
  "meta": {
    "start_time": "2015-12-28T12:30:00-06:00",
    "end_time": "2015-12-28T15:30:00-06:00",
    "coordinates": [
      41.888460348494,
      -87.628169593019
    ],
    "count": {
      "transient": 1,
      "event": 0
    }
  },
  "data": (Full quotes payload will be here.)
}

Parking quote searches will also contain meta-information about the results in the envelope, such as the start and end times of parking, the geographical coordinates on which the search is centered (e.g. search coordinates, venue coordinates, or centroid of the search bounding box), and result counts grouped by quote type. For a GET /quotes by coordinate search, the envelope would look like:

    {
        "status":200,
        "record_count":1,
        "start_timestamp":"2013-12-02T19:31:35.5362308Z",
        "end_timestamp":"2013-12-02T19:31:35.6299946Z",
        "time_taken":0.0937638,
        "query": {
          "coordinates": [
            41.860273,
            -87.630049
          ],
          "distance": {
            "miles": 0.5
          },
          "start_time": 2015-12-28T18:30:00-06:00,
          "end_time": 2015-12-28T18:30:00-06:00
        },
        "meta": {
          "start_time": 2015-12-28T18:30:00-06:00,
          "end_time": 2015-12-28T18:30:00-06:00,
          "coordinates": [41.860273,-87.630049],
          "count": {
            "transient": 1,
            "event": 0
          }
        }
        "data":[{
            "payload" : "here",
        }]
    }

Envelope functionality is available on all endpoints.

Errors

Responses to unsuccessful requests will contain an errors array, with each error object detailing what went wrong with the following values:

Value Description
code Error code used to identify the specific cause of the problem (e.g. for debugging), and to allow clients to conditionally respond to specific errors
uuid Unique identifier of the error
status The HTTP status code returned
message This is a brief user-friendly description of the error. This can and should be shown to the user
details optional More details may be provided in this field. This is for debugging and development purposes, and should not be shown to the user, nor should it be programmatically parsed and used
fields optional If the error is related to validation of numerous fields, this will specify which input parameters were invalid

Here is an example of a general error:

{
    [
        "code": "customer_unauthorized_api_key",
        "uuid": "375a87d1-f5e3-441c-9a84-5285eb9f1fb5",
        "status": 403,
        "message": "You are not authorized to view this booking"
    ]
}

This example shows what a form validation error might look like:

{
    [
        "code": "booking_quote_id_missing",
        "uuid": "375a87d1-f5e3-441c-9a84-5285eb9f1fb5",
        "status": 400,
        "message": "A booking requires a valid quote",
        "fields": ["quote_id"]
    ]
}

Dates and times

Searching

Dates and times should be formatted like the following: 2015-09-01T12:44 as specified in ISO 8601.

The API will infer the intended time zone based on the destination or parking location. If a timezone is specified, it will be ignored.

Responses

Date Time objects in API responses will be formatted like the following: 2015-09-01T12:44:00.000-08:00 as specified in ISO 8601

Formatting conventions

  • Coordinates lists are always ordered as [latitude,longitude].
    • You may omit the brackets for convenience
  • If your request includes a pretty=true param, the response will be indented for readability

Preview and Checkout

The following section contains a procedure for obtaining a price preview and booking details prior to checkout. To do this, you should first obtain Authorization Credentials, then obtain a Quote ID.

Get a Price Preview

To purchase a booking, you must first call preview and obtain a final price for the purchase. This preview includes the application of any user credits (if applicable), any manually entered coupons or user-specific coupons assigned to an account if the token used is from a logged in user. Users who are not logged in will not have credits or coupons auto applied. More details on the preview endpoint can be found here.

Request:
POST /v4/bookings/previews/
Authorization: Bearer 158020bea60d04a36c844e55d471f4237d7d45a8130b2f2aa75fbe9d6804ef4a

form-data; name="quote_id"  b475180e-e7aa-42af-a736-f3c8d9ca4aa4

Response:
  {
    "user_credit_amount": {
        "USD": "0.0"
    },
    "quote_price": {
        "USD": "15.0"
    },
    "subtotal": {
        "USD": "15.0"
    },
    "final_price": {
        "USD": "15.0"
    },
    "coupon_amount": {
        "USD": "0.0"
    }
}

This response includes all data necessary to inform the user of any coupons or credits used as well as the price that will be paid. When purchasing a booking, the final price must be added to the request. This price must match what the customer was quoted in preview. If the newly calculated price does not match what is passed, an error will be returned.

Make the Booking

The final price should be supplied to the booking's endpoint along with customer information. The booking response below will include all of the data necessary to show details about the booking. Please note the requested fields. If future access to the booking details are desired without authenticating as the user, an authorization code may be requested by adding the field booking: authorization_code. The booking response will then return an authorization_code which will grant access to view the booking anonymously. If more information is desired about the location or seller, these can be added as zooms to the request.

Request:
POST /v4/bookings/
Authorization: Bearer 158020bea60d04a36c844e55d471f4237d7d45a8130b2f2aa75fbe9d6804ef4a

form-data; name="quote_id"  6385df7a-60c2-46e5-8ed6-1f71f596af1c
form-data; name="final_price"  15.00
form-data; name="customer_email"  jkrohn@test.com
form-data; name="customer_firstname"  Joshua
form-data; name="customer_lastname"  Krohn
form-data; name="invoice" true
form-data; name="send_email_confirmation"  true
form-data; name=”fields” booking::default,booking:parking_pass_web_url,booking:authorization_code

Response:
[
    {
        "id": 82256111,
        "customer_id": 2121421,
        "start_time": "2017-10-01T10:00:00.000-05:00",
        "end_time": "2017-10-02T00:00:00.000-05:00",
        "price_paid": {
            "USD": "15.0"
        },
        "full_price": {
            "USD": "15.0"
        },
        "purchased_at": "2017-08-14T11:00:19.867-04:00",
        "type": "transient_booking",
        "cancellable": true,
        "parking_pass_web_url": "http://sandbox.parkwhiz.com/ticket/82256111?u=a3e897e8",
        "authorization_code": "a3e897e8",
        "_embedded": {
            "pw:location": {
                "_links": {
                    "self": {
                        "href": "/locations/6157"
                    },
                    "pw:reviews": {
                        "href": "/locations/6157/reviews"
                    },
                    "pw:quotes": {
                        "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:00:19+00:00&end_time=2017-08-14T18:00:19+00:00"
                    },
                    "curies": [
                        {
                            "name": "pw",
                            "href": "https://api.parkwhiz.com/v4/{rel}",
                            "templated": true
                        }
                    ]
                }
            },
            "pw:parking_pass": {
                "id": 82256111,
                "status": "active",
                "start_time": "2017-10-01T10:00:00.000-05:00",
                "end_time": "2017-10-02T00:00:00.000-05:00",
                "pass_type": "transient",
                "amenities": [
                    {
                        "name": "Unobstructed",
                        "description": "Guaranteed to be unobstructed",
                        "key": "unobstructed",
                        "enabled": true,
                        "visible": true
                    },
                    {
                        "name": "Tailgating",
                        "description": "Tailgating",
                        "key": "tailgate",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Reentry Allowed",
                        "description": "Reentry allowed",
                        "key": "reentry_allowed",
                        "enabled": false,
                        "visible": true
                    },
                    {
                        "name": "Attended",
                        "description": "Attended",
                        "key": "attended",
                        "enabled": true,
                        "visible": true
                    },
                    {
                        "name": "Valet",
                        "description": "Valet",
                        "key": "valet",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Restrooms",
                        "description": "Restrooms",
                        "key": "restroom",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Covered",
                        "description": "Covered",
                        "key": "indoor",
                        "enabled": true,
                        "visible": true
                    },
                    {
                        "name": "Security",
                        "description": "Security",
                        "key": "security",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "RVs Allowed",
                        "description": "RVs allowed",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Accessible",
                        "description": "Accessible",
                        "key": "handicap",
                        "enabled": false,
                        "visible": true
                    },
                    {
                        "name": "Free Shuttle",
                        "description": "Free shuttle",
                        "key": "shuttle",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Free Shuttle To Venue",
                        "description": "Free shuttle to venue",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Free Shuttle From Venue",
                        "description": "Free shuttle from venue",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Electric Car Charging",
                        "description": "Electric car charging",
                        "key": "vehicle_charging",
                        "enabled": true,
                        "visible": true
                    },
                    {
                        "name": "Has Gallery",
                        "description": "Has gallery",
                        "key": "has_gallery",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Lowest Price Guaranteed",
                        "description": "Lowest price guaranteed",
                        "key": "lowest_price_guarantee",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Mobile Pass",
                        "description": "Mobile pass",
                        "key": "eticket",
                        "enabled": true,
                        "visible": false
                    },
                    {
                        "name": "Price Premium",
                        "description": "Price premium",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "ParkWhiz Perk",
                        "description": "ParkWhiz perk",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    }
                ],
                "seller_id": 652,
                "active": true,
                "disclaimers": "No Re-Entry. Customer Responsible for additional fees upon Early Arrivals/Late Departures in accordance with posted rates. Garage allow 10 min grace Period on Arrival and Departure.",
                "price_paid": {
                    "USD": 15
                },
                "full_price": {
                    "USD": 15
                },
                "validation": {
                    "display_message": "Your validation method is your scan code.",
                    "require_license_plate": false,
                    "require_printout": false,
                    "steps": [
                        {
                            "instructions": "Scan ParkWhiz Pass at entry gate",
                            "icon": {
                                "path": "https://d36ck51ol93c7a.cloudfront.net/files/77143/icon/validation-icons-11.png?1453405538"
                            }
                        },
                        {
                            "instructions": "Park in any spot not marked \"Reserved\"",
                            "icon": {
                                "path": "https://d36ck51ol93c7a.cloudfront.net/files/77149/icon/validation-icons-28.png?1453405541"
                            }
                        },
                        {
                            "instructions": "Upon departure, scan ParkWhiz Pass at exit gate",
                            "icon": {
                                "path": "https://d36ck51ol93c7a.cloudfront.net/files/77155/icon/validation-icons-11.png?1453405545"
                            }
                        }
                    ],
                    "scan_code": {
                        "code": "X82256111",
                        "format": "QR",
                        "qr_error_correction_level": "L"
                    },
                    "display": {
                        "pass_number": "required",
                        "scan_code": "required",
                        "license_plate": "hidden",
                        "full_price": "hidden",
                        "pricing_codes": "hidden",
                        "gate_button": "hidden",
                        "print_instructions": "hidden"
                    }
                },
                "reseller_pass": false,
                "_embedded": {
                    "pw:location": {
                        "_links": {
                            "self": {
                                "href": "/locations/6157"
                            },
                            "pw:reviews": {
                                "href": "/locations/6157/reviews"
                            },
                            "pw:quotes": {
                                "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:00:20+00:00&end_time=2017-08-14T18:00:20+00:00"
                            },
                            "curies": [
                                {
                                    "name": "pw",
                                    "href": "https://api.parkwhiz.com/v4/{rel}",
                                    "templated": true
                                }
                            ]
                        }
                    },
                    "pw:seller": {
                        "_links": {
                            "curies": [
                                {
                                    "name": "pw",
                                    "href": "https://api.parkwhiz.com/v4/{rel}",
                                    "templated": true
                                }
                            ]
                        }
                    },
                    "pw:partner": {
                        "_links": {
                            "curies": [
                                {
                                    "name": "pw",
                                    "href": "https://api.parkwhiz.com/v4/{rel}",
                                    "templated": true
                                }
                            ]
                        }
                    },
                    "pw:add_ons": []
                }
            },
            "pw:customer": {
                "email": "jkrohn@test.com",
                "first_name": "Joshua",
                "last_name": "Krohn",
                "_links": {}
            },
            "pw:add_ons": []
        },
        "_links": {
            "self": {
                "href": "/bookings/82256111"
            },
            "pw:location": {
                "href": "/locations/6157"
            },
            "curies": [
                {
                    "name": "pw",
                    "href": "https://api.parkwhiz.com/v4/{rel}",
                    "templated": true
                }
            ]
        }
    }

View Booking Details Without Authenticating as the User (parking pass)

Using the Booking ID generated above and the authorization code, make a request to view the booking:

Request:
GET /v4/bookings/82256111?authorization_code=a3e897e8
Authorization: Bearer 158020bea60d04a36c844e55d471f4237d7d45a8130b2f2aa75fbe9d6804ef4a

Response:
   {
    "id": 82256111,
    "customer_id": 2121421,
    "start_time": "2017-10-01T10:00:00.000-05:00",
    "end_time": "2017-10-02T00:00:00.000-05:00",
    "price_paid": {
        "USD": "15.0"
    },
    "full_price": {
        "USD": "15.0"
    },
    "purchased_at": "2017-08-14T11:00:19.867-04:00",
    "type": "transient_booking",
    "cancellable": true,
    "_embedded": {
        "pw:location": {
            "_links": {
                "self": {
                    "href": "/locations/6157"
                },
                "pw:reviews": {
                    "href": "/locations/6157/reviews"
                },
                "pw:quotes": {
                    "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:15:22+00:00&end_time=2017-08-14T18:15:22+00:00"
                },
                "curies": [
                    {
                        "name": "pw",
                        "href": "https://api.parkwhiz.com/v4/{rel}",
                        "templated": true
                    }
                ]
            }
        },
        "pw:parking_pass": {
            "id": 82256111,
            "status": "active",
            "start_time": "2017-10-01T10:00:00.000-05:00",
            "end_time": "2017-10-02T00:00:00.000-05:00",
            "pass_type": "transient",
            "amenities": [
                {
                    "name": "Unobstructed",
                    "description": "Guaranteed to be unobstructed",
                    "key": "unobstructed",
                    "enabled": true,
                    "visible": true
                },
                {
                    "name": "Tailgating",
                    "description": "Tailgating",
                    "key": "tailgate",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Reentry Allowed",
                    "description": "Reentry allowed",
                    "key": "reentry_allowed",
                    "enabled": false,
                    "visible": true
                },
                {
                    "name": "Attended",
                    "description": "Attended",
                    "key": "attended",
                    "enabled": true,
                    "visible": true
                },
                {
                    "name": "Valet",
                    "description": "Valet",
                    "key": "valet",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Restrooms",
                    "description": "Restrooms",
                    "key": "restroom",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Covered",
                    "description": "Covered",
                    "key": "indoor",
                    "enabled": true,
                    "visible": true
                },
                {
                    "name": "Security",
                    "description": "Security",
                    "key": "security",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "RVs Allowed",
                    "description": "RVs allowed",
                    "key": "",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Accessible",
                    "description": "Accessible",
                    "key": "handicap",
                    "enabled": false,
                    "visible": true
                },
                {
                    "name": "Free Shuttle",
                    "description": "Free shuttle",
                    "key": "shuttle",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Free Shuttle To Venue",
                    "description": "Free shuttle to venue",
                    "key": "",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Free Shuttle From Venue",
                    "description": "Free shuttle from venue",
                    "key": "",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Electric Car Charging",
                    "description": "Electric car charging",
                    "key": "vehicle_charging",
                    "enabled": true,
                    "visible": true
                },
                {
                    "name": "Has Gallery",
                    "description": "Has gallery",
                    "key": "has_gallery",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Lowest Price Guaranteed",
                    "description": "Lowest price guaranteed",
                    "key": "lowest_price_guarantee",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Mobile Pass",
                    "description": "Mobile pass",
                    "key": "eticket",
                    "enabled": true,
                    "visible": false
                },
                {
                    "name": "Price Premium",
                    "description": "Price premium",
                    "key": "",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "ParkWhiz Perk",
                    "description": "ParkWhiz perk",
                    "key": "",
                    "enabled": false,
                    "visible": false
                }
            ],
            "seller_id": 652,
            "active": true,
            "disclaimers": "No Re-Entry. Customer Responsible for additional fees upon Early Arrivals/Late Departures in accordance with posted rates. Garage allow 10 min grace Period on Arrival and Departure.",
            "price_paid": {
                "USD": 15
            },
            "full_price": {
                "USD": 15
            },
            "validation": {
                "display_message": "Your validation method is your scan code.",
                "require_license_plate": false,
                "require_printout": false,
                "steps": [
                    {
                        "instructions": "Scan ParkWhiz Pass at entry gate",
                        "icon": {
                            "path": "https://d36ck51ol93c7a.cloudfront.net/files/77143/icon/validation-icons-11.png?1453405538"
                        }
                    },
                    {
                        "instructions": "Park in any spot not marked \"Reserved\"",
                        "icon": {
                            "path": "https://d36ck51ol93c7a.cloudfront.net/files/77149/icon/validation-icons-28.png?1453405541"
                        }
                    },
                    {
                        "instructions": "Upon departure, scan ParkWhiz Pass at exit gate",
                        "icon": {
                            "path": "https://d36ck51ol93c7a.cloudfront.net/files/77155/icon/validation-icons-11.png?1453405545"
                        }
                    }
                ],
                "scan_code": {
                    "code": "X82256111",
                    "format": "QR",
                    "qr_error_correction_level": "L"
                },
                "display": {
                    "pass_number": "required",
                    "scan_code": "required",
                    "license_plate": "hidden",
                    "full_price": "hidden",
                    "pricing_codes": "hidden",
                    "gate_button": "hidden",
                    "print_instructions": "hidden"
                }
            },
            "reseller_pass": false,
            "_embedded": {
                "pw:location": {
                    "_links": {
                        "self": {
                            "href": "/locations/6157"
                        },
                        "pw:reviews": {
                            "href": "/locations/6157/reviews"
                        },
                        "pw:quotes": {
                            "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:15:22+00:00&end_time=2017-08-14T18:15:22+00:00"
                        },
                        "curies": [
                            {
                                "name": "pw",
                                "href": "https://api.parkwhiz.com/v4/{rel}",
                                "templated": true
                            }
                        ]
                    }
                },
                "pw:seller": {
                    "_links": {
                        "curies": [
                            {
                                "name": "pw",
                                "href": "https://api.parkwhiz.com/v4/{rel}",
                                "templated": true
                            }
                        ]
                    }
                },
                "pw:partner": {
                    "_links": {
                        "curies": [
                            {
                                "name": "pw",
                                "href": "https://api.parkwhiz.com/v4/{rel}",
                                "templated": true
                            }
                        ]
                    }
                },
                "pw:add_ons": []
            }
        },
        "pw:customer": {
            "email": "jkrohn@test.com",
            "first_name": "Joshua",
            "last_name": "Krohn",
            "_links": {}
        },
        "pw:add_ons": []
    },
    "_links": {
        "self": {
            "href": "/bookings/82256111"
        },
        "pw:location": {
            "href": "/locations/6157"
        },
        "curies": [
            {
                "name": "pw",
                "href": "https://api.parkwhiz.com/v4/{rel}",
                "templated": true
            }
        ]
    }
}

Models

Quote model

Field Type Description
location_id String ParkWhiz ID of the location for which this quote was made.
start_time ISO 8601 Timestamp Desired parking start time. Not present for monthly parking or packages.
end_time ISO 8601 Timestamp Desired parking end time. Not present for monthly parking or packages.
min_start ISO 8601 Timestamp The earliest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
max_end ISO 8601 Timestamp The lastest time that can be requesetd for this quote at the quoted prices. Not present for monthly parking or packages.
distance Distance Object Distance between parking location and the destination supplied in the q request parameter. This will not be included when bounds is your q parameter.
distance[straight_line] Object The distance between the quote's location and coordinate/event/venue/etc. It is a straight line, as the crow flies. The object supports numerous units (e.g. { "meters": 326, "feet": 1070 }).
seller_id Integer ParkWhiz ID of the seller of the location for which the quote was made.
disclaimers Array[Strings] A list of disclaimers for this quote.
non_bookable_options Array[Non-bookable Options] A list of non-bookable options for this quote. This will only be returned if the appropriate option_types are requested

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the quote, they are retrieved by default.

Field Description
pw:location The quote's location
pw:event The quote's event
pw:venue The quote's venue

Location model

Field Type Description
id String ParkWhiz location ID.
name String Name of the location.
address1 String First line of location's address.
address2 String Second line of location's address.
city String City where the location is located.
state String State where the location is located.
postal_code String Location's postal code.
country String Location's country.
currency String Location's currency. Can be used to fetch result from Price object.
entrances Array[Objects] Information about the location's entrances. This will always include a "coordinates" value, but may contain other helpful information like "max_dimensions". e.g. [ { "coordinates": [lat,lon], "max_dimensions: { "inches": { "height": 71, "width" : 112 }, "human_readable": "No Vehicles Over 6' 2" in Height"}} ]
photos Array[Photos] Photos of the location.
timezone String not included by default Timezone of the location.
description String not included by default Brief description of the location.
rating_summary Rating Summary Object not included by default The location's rating, based on feedback from ParkWhiz customers.
rating_summary[average_rating] String Average rating, from 0.0 to 5.0.
rating_summary[rating_count] Integer Number of ratings that the average_rating is based off of.
scan_format String not included by default How the location scans parking passes.
display_price Boolean not included by default Whether or not you should display the price on the parking pass for this location.
validation_method String not included by default How parking is validated at this location.
directions String not included by default How customers should get to the location.
site_url String not included by default The url path for this location. E.g. "/p/new-york-parking/1234-main-street"
phone Object not included by default e.g. { "default": "1-888-555-5555" }
hours Array[String] not included by default. This field contains a human readable set of hours for this location.
capacity Object not included by default. e.g. { "maximum": 300 }. Maximum vehicle capacity of the parking facility. If official capacity isn’t posted or accessible, this is an estimate of capacity based on manual count of stalls and/or square footage. This field will not be available unless you have a data license.
operating_hours Array[Time Periods] not included by default. This field will not be available unless you have a data license.
non_bookable_rates Array[Non-bookable Rates] not included by default. This field will not be available unless you have a data license.
outline Array[Coordinates] not included by default. Array of coordinate pairs representing the outline of the location. e.g. [[41.888387621536,-87.62872289526],[41.888173967631,-87.628725577469],[41.888179957937,-87.628242779847],[41.888391615061,-87.628256190892],[41.888387621536,-87.62872289526]]. This field will not be available unless you have a data license.
supports_booking_extension Boolean Whether or not this location supports booking extensions.
on_demand_options Object On demand booking options supported at this location (e.g. { "spg": true }). Currently spg (Scan/Pay/Go) is the only option returned.

Field groups

The following field groups are available for your convenience:

Name Fields included
:default id, name, address1, address2, city, state, postal_code, entrances, photos
:address address1, address2, city, state, postal_code

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:seller The location's seller

Purchase Option model

Field Type Description
id String ParkWhiz ID for this Purchase Option formatted as a UUID.
start_time ISO 8601 Timestamp Desired parking start time. Not present for monthly parking or packages.
end_time ISO 8601 Timestamp Desired parking end time. Not present for monthly parking or packages.
min_start ISO 8601 Timestamp The earliest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
max_end ISO 8601 Timestamp The lastest time that can be requesetd for this quote at the quoted prices. Not present for monthly parking or packages.
price Object Contains pricing in local currency (e.g. { "USD": "12.02" } or { "CAD": "25.75" }).
pricing_segments Array[Pricing Segments] An array of pricing segments, which your pricing is generated by.
add_ons Object Add ons eligible to be purchased with this parking, grouped by type. e.g. {"vehicle_size": {"required": true, "options":[ ... ]}} where "options" contains Add On models. "vehicle_size" is the most common type grouping. "required" indicates that the user needs to select one of the options from that group (again, most commonly for "vehicle_size").
shuttle Boolean Whether or not the location has a shuttle to the event. This will only show if the quote is for event pricing.
space_availability Space Availability Object Information about spaces for this option.
space_availability[status] String Describes the availability of spaces at this location. Either "available", "limited", or "unavailable".
space_availability[spaces_remaining] Integer If status is "limited", we will show you the number of spaces that are left at this location. Otherwise, this field will not be provided.
validation Validation Object Information about on-site parking validation
disclaimers Array[Strings] Pertinent parking information not displayed elsewhere on the pass/website/app For example, "Park only on levels A-D".
amenities Array[Amenities] not included by default A list of the amenities included with this purchase option.

Shuttle Time model

Field Type Description
start_time ISO 8601 Timestamp The time when this shuttle time information becomes valid.
end_time ISO 8601 Timestamp The time when this shuttle time information becomes invalid.
travel_time[minimum] Integer The minimum amount of time (in minutes) it will take for the shuttle to get to its destination.
travel_time[maximum] Integer The maximum amount of time (in minutes) it will take for the shuttle to get to its destination. If this doesn't come back, it means only the minimum travel time is relevant.
frequency[minimum] Integer The minimum amount of time (in minutes) between shuttles picking people up.
frequency[maximum] Integer The maximum amount of time (in minutes) between shuttles picking people up. If this doesn't come back, it means only the minimum frequency is relevant.
on_demand Boolean Whether or not the shuttle is ran on demand, rather than on a set frequency. If true, the user will have to call the phone number included below.
phone[on_demand] String The phone number the user should call if the shuttle is on demand.

Non-bookable Option model

Field Type Description
price Object Contains numerous pricing formats (e.g. { "USD": "12.02" }).
add_ons Object Add ons eligible to be purchased with this parking, grouped by type. e.g. {"vehicle_size": {"required": true, "options":[ ... ]}} where "options" contains Non-bookable Add On models. "vehicle_size" is the most common type grouping. "required" indicates that the user needs to select one of the options from that group (again, most commonly for "vehicle_size").
attributes Object e.g. { "oversize_advisory" : "OVERSIZE VEHICLES PROHIBITED", "covered": "Outdoor Lot", "type": "Self Park", "payment": "Cash Only", "services": [ "Car Wash", "Detailing", "Airport Shuttle" ]. Our parking data has a wealth of information, and only some of it is currently available via dedicated fields on this API. This attributes field will be used in short term to provide additional information, but please contact us if you find any of it useful and would like it more easily machine-readable.

Non-bookable Rates model

Parking companies express rates in numerous ways. Rates can be hourly ("up to 2 hours"), time-based ("maximum to closing time"), or a combination of the two, all of which can then be superseded by daily specials, which specify arrival time ranges and/or departure time ranges and/or hourly stay ranges.

There may also be an oversize vehicle surcharge. It can either be a surcharge to the regular vehicle rates or a flat rate that overrides the regular vehicle rates.

Field Type Description
rate_period Time Period The period of time in a week through which this rate applies. When receiving multiple rates, you may find overlap. For example a garage may reset its rates every day at 6 am and you will receive rates from midnight til 6am 30 hours later for each day.
rates Array[Objects] A list of prices applicable during this time period. Each rate will typically have an 'until_time' or 'duration' value, and sometimes an 'overnight' additional charge
rates[price] Object Contains numerous pricing formats (e.g. { "USD": "12.02" }).
rates[until_time] String "HH:MM" representation of what this rate ends. For example, if a garage has a rate_period until 19:00, it might just have a "max-to-close" rate of $10, which we would show as until_time="19:00".
rates[duration] Integer Maximum number of minutes allowed for the given price
rates[overnight] Object If the parking locations allows the customer to stay beyond the rate_period, it may provide this 'overnight' option. In addition to the "until_time" or "duration" rate, if the customer stays beyond the rate_period, the garage may charge this additional amount. e.g. { "rates": [ { "overnight": { until_time: "30:00", additional_cost: { "USD": "4.00" } } } ] }

TODO: Show a few examples here

Time Period model

Each instance of this model represents a period of time in any arbitrary week of the year. An array of these can be used to represent when a garage is open to the public, or when specific rates are applicable.

Field Type Description
start_week_day Integer 0-6, the day of the week at which this period starts.
start_time String 'HH:MM', e.g. '13:00' for 1pm, or '00:00' for midnight.
end_time String 'HH:MM', e.g. '13:00' for 1pm, or '00:00' for midnight.
end_days_later Integer The number of days offset from the start_day that this period ends

For example, a garage that is always open might have this record for its operating hours:

{
    "start_week_day": 0,
    "start_time": "00:00",
    "end_time": "00:00",
    "end_days_later": 7
}

A rate that is eligible from 8am-8pm on Monday would be represented as

{
    "start_week_day": 1,
    "start_time": "08:00",
    "end_time": "20:00",
    "end_days_later": 0
}

Photo model

Field Type Description
position Integer The order you should display the images.
alt String A description of the image for alternate text.
images Array[Image] An array of image objects. Image objects have the following fields:
images[URL] String The URL to the image.
images[width] Integer The width of the image.
images[height] Integer The height of the image.

Location Review model

Field Type Description
rating Integer The rating given (1-5)
comment String the comment given
recommended Boolean Did the user recommend the location?
created_at ISO 8601 Timestamp the DateTime the review was created.

Account model

Field Type Description
id Integer ParkWhiz ID of the account's user.
email String The account's email address.
first_name String The first name of the account's owner.
last_name String The last name of the account's owner.
phone_number String The phone number of the account's owner.

Optional fields

Field Type Description
api_key String The customer's API key.
is_reseller Boolean Whether or not the user is a reseller. Resellers cannot get refunds for their bookings or use coupons.
account_type[admin] Boolean Whether or not the user is a ParkWhiz admin.
account_type[seller] Boolean Whether or not the user is a seller. Sellers are members of and manage parking locations.
account_type[legacy_affiliate] Boolean Whether or not the user is a legacy affiliate. There is more information about the legacy affiliate program here.
is_admin Boolean Whether or not the user is an admin or not. Deprecated, use account_type[admin] instead.
created_at DateTime The Date and Time the user was created
Field Description
pw:vehicles A list of vehicles that the customer added to their account.
pw:payment_methods A list of payment methods that the customer added to their account.

Pricing Segment model

Field Type Description
id Integer The ParkWhiz ID for the pricing.
start_time ISO 8601 Timestamp The start time that is used for this pricing.
end_time ISO 8601 Timestamp The end time that is used at this price.
event Event Object Information about a specific event associated with a pricing
event[id] Integer The ID of the event associated with the pricing
event[name] String The name of the event associated with the pricing
event[additional_time] Integer The amount of time in hours a booking is valid after the event ends
purchase_limit Integer The maximum number of bookings that can be made by any single account for this pricing
space_availability Space Availability Object Information about spaces for this pricing.
space_availability[status] String Describes the availability of spaces at this price. Either "available", "limited", or "unavailable".
space_availability[spaces_remaining] Integer If status is "limited", we will show you the number of spaces that are left at this price. Otherwise, this field will not be provided.

Add On model

Field Type Description
id Integer The ParkWhiz ID for this add on formatted as a UUID
name String Name of the add on
description String Description of the add on
start_time ISO 8601 Timestamp The start time for this add on
end_time ISO 8601 Timestamp The end time for this add on
price Object Contains numerous pricing formats (e.g. { "USD": 12.02 })
items Array[String] A list of the items that come with or are covered by this add on (e.g. ["coupe", "sedan", "hatchback"])
availability Add On Availability Object Information about spaces for this pricing
availability[status] String Describes the availability of add ons at this price. Either "available", "limited", or "unavailable."
availability[spaces_remaining] Integer If status is "limited", we will show you the number of add ons that are left at this price. Otherwise, this field will not be provided.

Non-bookable Add On model

Field Type Description
name String Name of the add on
description String Description of the add on
price Object Contains numerous pricing formats (e.g. { "USD": 12.02 }).
items Array[String] A list of the items that come with or are covered by this add on (e.g. ["coupe", "sedan", "hatchback"])

Amenity model

Field Type Description
name String The name of the amenity.
key String The short identifier of this amenity.
description String A brief description of this amenity.
enabled Boolean Whether this amenity is available with the purchased parking space.
visible Boolean Whether ParkWhiz suggests display of this amenity, even if not enabled.

Here are some example keys. This list may not be complete, though:

  • covered
  • valet
  • restroom
  • accessible
  • security
  • attended
  • attended_arrival
  • attended_departure
  • attended_always
  • unobstructed
  • rv
  • tailgating
  • vehicle_charging

Validation model

Field Type Description
steps Array[Step Objects] Steps to validate parking. The fields are as follows:
step[instructions] String Parking validation instructions
step[icon] Object Illustrative image for this validation step. It's an object with a path to the image, e.g. { "path": "/path/to/image.jpg" }.
require_license_plate Boolean Whether validation requires the customer provide vehicle license plate information
require_printout Boolean Whether validation requires the customer to print their parking pass for redemption
scan_code Scan Code Object Information needed for rendering the parking pass scan code. This is not shown when searching for quotes. The fields are as follows:
scan_code[code] String Text representation of the validation scan code
scan_code[format] String Format in which to render the validation scan code. Values will be QR or 1D-128B
scan_code[qr_error_correction_level] String Error correction level to use for QR codes
display Display Object Information on what validation data to display. When the string is required, the field should always be shown on the pass. When hidden, never show it on the pass. When optional, you can hide it on the pass, but give users the option to see it. The fields are as follows:
display[scan_code] String Should the scan code be displayed? required, optional, or hidden
display[pass_number] String Should the pass number be displayed? required, optional, or hidden
display[license_plate] String Should the customer license plate number be displayed? required, optional, or hidden
display[full_price] String Should the full price value of the pass be displayed? required, optional, or hidden
display[pricing_codes] String Should the pricing codes be displayed on the pass? required, optional, or hidden
display[gate_button] String Should the Vendgate gate open button be displayed on the pass? required, optional, or hidden
display[print_instructions] String Should the print instructions be displayed on the pass? required, optional, or hidden
display_message String Explanatory text about the validation method
instructions String Additional parking instructions

Booking model

Field Type Description
id Integer ParkWhiz booking ID
scan_code String Text representation of parking pass QR or barcode
location_id String ParkWhiz ID of this booking's location
pricing_ids Array[Integers] List of ParkWhiz pricing IDs for this booking
event_id Integer ParkWhiz ID of this booking's event
amenity_set_id Integer ParkWhiz ID of the amenity set that comes with this booking
start_time ISO 8601 Timestamp Booked parking start time
end_time ISO 8601 Timestamp Booked parking end time
price_paid Object Amount the customer paid for this booking with pricing format (e.g. {"USD": 12.02 })
full_price Object Amount the seller charged for this booking with pricing format (e.g. {"USD": 12.02 })
purchased_at ISO 8601 Timestamp When the customer purchased this booking
cancelled_at ISO 8601 Timestamp When the customer or ParkWhiz cancelled this booking.
cancellable Boolean Indicates whether or not this pass can be cancelled
type String The type of booking it is. Possible values: "monthly_booking", "event_booking", "transient_booking"
business_purchase Boolean Whether the booking was purchased using a Business Profile or ParkWhiz for Business Account
package Object If the booking belongs to an event package, we will return additional information about the event package
package[id] Integer ParkWhiz event package ID
package[name] String The name of the event package, for example: "Chicago Bears Season Tickets: VIP"
on_demand Boolean Was this booking a reservation (false) or on demand (true)?

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:location The booking's location
pw:event The booking's event
pw:parking_pass The parking pass used to validate this booking
pw:vehicle The vehicle attached to the booking. Not all bookings require the user to add a vehicle. It depends on the location's or pricing's validation method.
pw:receipt A convenient receipt for the booking. It contains all of the customer's purchase information.
pw:coupons The coupons that the customer used with their purchase. As of now, this will just be an array of one element, but could change without notice in the future. Note: for a snapshot of coupon information at the time of purchase, look at the pw:receipt zoom instead.
pw:review The user's review of the location.

Booking modification model

Field Type Description
modified_at ISO 8601 Timestamp The time at which the modification took place.
previous_end_time ISO 8601 Timestamp The previous parking period end time prior to this booking modification.
modified_end_time ISO 8601 Timestamp The new parking period end time after this modification took place.

Booking preview model

Field Type Description
quote_price Object Base price of the parking (e.g. {"USD": 12.02 })
subtotal Object Price of the parking plus add ons before discounts (e.g. {"USD": 12.02 })
final_price Object Final price to be charged to the customer for full purchase (e.g. {"USD": 12.02 })
user_credit_amount Object User credits applied to the discounted final price (e.g. {"USD": 12.02 })
coupon_amount Object Amount discounted by use of coupon (e.g. {"USD": 12.02 })
coupon_code String Coupon used to generate final_price
prior_payment Object Prior amount paid (e.g. {"USD": 12.02 }). Only applicable when extending an existing booking.

Booking extend preview model

Field Type Description
requested Object The requested quote with preview (e.g. {"preview": {...}, "quote": {...}) if successful, otherwise not returned.
suggested Array[Object] Suggested quotes with previews (e.g. [{"preview": {...}, "quote": {...}]) if successful, otherwise not returned.

Receipt model

Field Type Description
user_credit_amount[USD] Decimal How many of the customer's credits were applied to this purchase in USD.
quote_price[USD] Decimal How much the base booking cost, before add ons were added or coupons/credits applied in USD.
subtotal[USD] Decimal The quote_price + add_on costs in USD. In other words, the whole booking price before coupons or credits are applied.
final_price[USD] Decimal What the customer actually paid. The subtotal, minus the user_credit_amount and coupon_amount.
coupon_amount[USD] Decimal How many dollars the customer's coupon took off the subtotal.
add_ons[][name] String The name of an add on that was purchased with the booking.
add_ons[][quote_price][USD] Decimal How much the purchased add on cost, before any coups or credits applied.
purchase_time ISO 8601 Timestamp When the customer purchased this booking
payment_type String How the customer paid for the booking. Possible values: Credit Card, PayPal, Apply Pay, Android Pay, Enterprise Account, Facebook.

Parking Pass model

Field Type Description
id Integer ParkWhiz booking ID
status String Text representation of parking pass QR or barcode
pass_type String Description of the type of pass returned. May be transient, event, or mixed
pricing_codes Array[Strings] List of ParkWhiz price codes for this booking
start_time ISO 8601 Timestamp Booked parking start time
end_time ISO 8601 Timestamp Booked parking end time
arrive_by ISO 8601 Timestamp Time by which a driver must arrive for a restricted pricing
depart_after ISO 8601 Timestamp Time by which a driver must depart for a restricted pricing
min_parking_hours Integer Minimum amount of time time for which a driver must park for a restricted pricing
event_id Integer ParkWhiz evnet ID for the event the customer searched for when purchasing
pricing_event_id Integer ParkWhiz evnet ID for the event associated with the pricing the booking was purchased under
hours_after_event Float Number of hours for which a customer may remained parked after the end of the event associated with the booking. Only applicable when event_id and pricing_event_id match.
price_paid Object Amount the customer paid for this booking with pricing format (e.g. {"USD": 12.02 })
full_price Object Amount the seller charged for this booking with pricing format (e.g. {"USD": 12.02 })
amenities Array[Amenities] A list of the amenities included with this purchase option
validation Validation Object Information about on-site parking validation
disclaimers String Pertinent parking information not displayed elsewhere on the pass/website/app For example, "Park only on levels A-D".
seller_id Integer ParkWhiz ID of the seller who operates the booked parking facility
active Boolean Whether the parking pass is active (true), or has been cancelled, refundeded, or has expired (false).
reseller_pass Boolean Whether the parking pass was originally booked by an identified reseller. Passes marked as such are subject to restrictions.
web_url String not included by default An authenticated URL that can be used to retrieve the parking pass by a user
pickup_instructions String Text representation of the pricing pickup instructions
dropoff_instructions String Text representation of the pricing dropoff instructions

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:location The booking's location
pw:event The booking's event
pw:venue The venue for the booking's event or venue of booking
pw:vehicle The vehicle for the booking
pw:seller The seller who operates the booked location
pw:partner The partner trough whom the pass was purchased
pw:add_ons The add ons purchased with the booking
pw:booking_modifications The modifications made to this booking

Vehicle model

Field Type Description
id Integer ParkWhiz vehicle ID
label String Customer supplied label for this vehicle
default Boolean Whether this vehicle is the customer's default when booking
plate_number String License plate number of the vehicle
plate_state String License plate state of the vehicle

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:bookings Bookings made with this vehicle

Venue model

Field Type Description
id Integer ParkWhiz venue ID
name String Name of the venue
address1 String First line of venue's address
address2 String Second line of venue's address
city String City where the venue is located
state String State where the venue is located
postal_code String Venue's postal code
distance Object Distance to the venue from the search coordinates, if provided (e.g. { "miles": 0.75, "meters": 1207.01 })
timezone String not included by default Timezone of the venue
description String not included by default Brief description of the venue
venue_type String not included by default Category of the venue (e.g. arena, park, etc.)
website URL not included by default URL of the venue's non-ParkWhiz website (e.g. http://soldierfield.net)
coordinates Array not included by default Coordinates of the venue (e.g. [ lat,lon]).
msa String not included by default Name of the major city this venue is within
primarily_transient Boolean not included by default Whether this venue has events (false) or is for transient parking only (true)
seo_meta Object not included by default SEO data about the venue, including title and description
enhanced_airport Boolean not included by default Whether or not the venue is an enhanced airport

The following resources can be retrieved with the zoom parameter as described in the section on linking

Field Description
pw:upcoming_events A list of upcoming events that are at the venue. It is sorted by the event's starting time, soonest event first. It will return a maximum of 100 events by default, but is configurable by supplying a zoom_resource_limits URL parameter, such as zoom_resource_limits=pw:upcoming_events:20.

Event model

Field Type Description
id Integer ParkWhiz event ID
name String Name of the event
venue_id String ParkWhiz venue ID
start_time ISO 8601 Timestamp The event's start time
end_time ISO 8601 Timestamp The event's estimated end time
event_type String not included by default Category of the venue (e.g. concert, baseball, etc.)
site_url String not included by default The url path for this event. E.g. /house-of-blues-chicago-parking/classic-rock-night-12345/

The following resources can be retrieved with the zoom parameter as described in the section on linking

Field Description
pw:venue The event's venue

Field groups

The following field groups are available for your convenience:

Name Fields included
:default id, name, address1, address2, city, state, postal_code, entrances, photos
:address address1, address2, city, state, postal_code

Hub model

Field Type Description
id Integer ParkWhiz hub ID
name String Display name of the hub, ex: "Chicago Loop"
coordinates Array Center coordinates of the hub (e.g. [ lat,lon])
city String not included by default City that the hub is in
state String not included by default State that the hub is in

Coupon model

Field Type Description
id Integer ParkWhiz coupon ID
description String A short description of the coupon
dollar_discount String The discount that the coupon provides the customer, in dollars
pricing_type String Whether the coupon applies to daily parking or monthly parking
label String A short label for the coupon
expiration_date ISO 8601 Timestamp When the coupon expires

Payment method model

In this context, payment methods will only refer to Credit Cards or ParkWhiz For Business accounts. It will also refer to a user's Business Profile, which is technically a credit card.

Common fields:

Field Type Description
id Integer ParkWhiz payment method ID.
type String What type of payment method it is. Either "credit_card" or "Enterprise". "Enterprise" refers to PW4B.
required_license_plate Boolean Whether or not the pricing requires a license plate.
is_default Boolean Whether or not this is the user's default payment method.

Credit card fields:

Field Type Description
last_4 String The last 4 digits of the credit card.
label String The label that the customer chose to give the credit card.
card_type String The type of credit card the customer saved.
expiration_month Integer The month that the credit card expires.
expiration_year Integer The year that the credit card expires.
postal_code String The zip code that the credit card is registered under.

ParkWhiz For Business fields:

Field type Description
account_name String The client selected name for the account.
account_id Integer The PW id for the enterprise account that the credit care belongs to.

Sellers model

Field Type Description
id Integer ParkWhiz seller ID if available.
name String Seller public name.

Ticket model

Field Type Description
id Integer The id of the ticket
amount Object The amount the customer was charged for parking (e.g. amount: { USD: '15.00' })
coupon_code String The coupon code that will be used to discount the purchase
parking_transaction_id String The transaction id associated with this ticket
on_site_ticket_id String The ticket number provided by the parking system
parking_start DateTime The time the customer began parking
parking_end DateTime The time that the customer exited the facility
status String The current status of the ticket

Ticket Statuses

The status for a ticket will generally follow this path unless there is a problem:

open -> closed -> reconciled

Status Description
open Parking has started
closed Parking has ended but the customer has not yet been charged
payment_failed Parking has ended and charging the customer's payment method failed
invalidated The parking ticket has been invalidated
reconciled Parking has ended and the customer's payment method was successfully charged

The following resources can be retrieved with the zoom parameter as described in the section on linking.

Field Description
pw:booking The ticket's booking (only present after a Ticket has been closed)
pw:location The ticket's location

Ticket Preview model

Field Type Description
coupon_code String The coupon code being applied to this preview
on_site_ticket_id String The ticket number provided by the parking system
ticket_start_time DateTime The time the ticket parking began
warnings Array A list of warnings indicating problems which will prevent a successful checkout (e.g. [{ code: 'invalid_payment_method', message: 'The provided payment method is invalid'}])

Warnings

Code Message
active_ticket Customer already has an active ticket which needs to be closed out
invalid_payment_method The provided payment method is invalid
unverified_phone_number Customer's phone number has not been verified

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the quote, they are retrieved by default.

Field Description
pw:location The ticket preview's location

Endpoints

Price Quotes and Locations

ParkWhiz provides the ability to search for parking at locations across the world. This API provides information on both the bookable parking spaces you can purchase through this API or via the ParkWhiz site and apps, as well as non-bookable parking locations.

Understand that the bookable purchase options and non-bookable rate information will often be different. ParkWhiz bookable inventory often has discounts, may have reduced operating hours, or other restrictions.

Please note that access to non-bookable inventory and drive-up rate information requires a license. Contact us for more details.

GET /quotes Search for parking price and availability

Request

Parameter Type Description
q String required The query for the destination near which you require parking. See above for how to use this parameter.
start_time ISO 8601 Timestamp required for non-event searches The date and time to start parking. If searching for an event, this will default to the event time.
end_time ISO 8601 Timestamp required for non-event searches The date and time to end parking.
mobile_only Boolean This is a deprecated field. Use returns Will return only facilities that are mobile enabled. Default false.
include_sold_out Boolean This is a deprecated field. Use returns Will return sold out locations as well as purchasable locations Default true.
option_types String bookable (default), non_bookable, or all. This determines whether the endpoint returns bookable quotes that can be purchased from ParkWhiz, non-bookable drive-up rate information, or both.
returns Return One or more items from the returns collection. If no returns are requested and no booleans passed in offstreet_bookable will be used
external_id String A unique ID generated by the partner to be used in conjunction with the partner to identify a user.

Note: pagination is not supported on this endpoint.

Query Parameters

There are numerous sub-parameters for the q parameter. For some sub-parameters, you can also include distance, which will return quotes within that distance. If not supplied, distance is set to 1 mile. Available sub-parameters are as follows:

Query type Description
event_id A ParkWhiz Event ID.
venue_id A ParkWhiz Venue ID.
location_id A ParkWhiz Location ID.
stubhub_venue_id A Stubhub Venue ID
ticketmaster_venue_id A TicketMaster Venue ID
seller_id One or more ParkWhiz Seller IDs separated by commas.
coordinates A set of coordinates. See the note on coordinates
bounds A list of coordinates. They must be sequential clockwise, though you can start with any coordinate and bounds can be any polygon. See the note on coordinates
distance The radius around a pair of coordinates, event, or venue. This is measured in miles and defaults to 1.
search_type Specify the type of parking to search for (transient, monthly, event_package). A default search will be for transient parking.
anchor_coordinates A set of coordinates. This will server as the anchor for distance calculation. See the note on coordinates
event_package_id A ParkWhiz Event Package ID.
ticketmaster_event_id A Ticketmaster Event ID.

Note: Search areas larger than 50 square miles are not supported. If your search exceeds this size you will receive an error response indicating the requested area is too large.

Returns

Returns help to filter out undesired results and ensure that all content returned is relevant to the client requesting the search. Returns are additive to the result set and their order does not matter. More returns will be added as new data types are introduced to the API.

Returns Properties
offstreet Offstreet inventory. Include bookable, nonbookable, and sold out
offstreet_bookable Offstreet, bookable inventory
offstreet_bookable_mobile Offstreet bookable inventory that is only mobile enabled
offstreet_bookable_sold_out Offstreet bookable incentory that is currently unavailable due to being sold out
offstreet_non_bookable Offstreet, non bookable inventory

Sample Searches

Coordinate Example

https://api.parkwhiz.com/v4/quotes/?q=coordinates:41.881943,-87.630976&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable

Bounds Example

https://api.parkwhiz.com/v4/quotes/?q=bounds:[[41.881943,-87.630976],[41.882071,-87.626191],[41.878205,-87.626148],[41.878301,-87.633680]]&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable

For convenience, you may omit the brackets. e.g.

https://api.parkwhiz.com/v4/quotes/?q=bounds:41.881943,-87.630976,41.882071,-87.626191,41.878205,-87.626148,41.878301,-87.633680&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable

Coordinates, only mobile enabled

https://api.parkwhiz.com/v4/quotes/?q=coordinates:41.881943,-87.630976&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable_mobile

Coordinates, bookable and non bookable data

https://api.parkwhiz.com/v4/quotes/?q=coordinates:41.881943,-87.630976&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable offstreet_non_bookable

Response

The response will be an array of Quote models.

Envelope: When requesting the envelope there is an additional meta object that has the following information:

Field Type Description
start_time ISO 8601 Timestamp The start time that you passed to GET /quotes.
end_time ISO 8601 Timestamp The end time that you passed to GET /quotes.
coordinates Array[Coordinates] The coordinates of the center of your search.
count Object A count of the different types of quotes returned, with keys transient, event, monthly, unavailable. E.g. {"transient":71,"event":0,"monthly":0,"unavailable":1}

Error responses

Status Message
404 No quotes found
400 This will supply a field and relevant validation error message (e.g. {"field": "query_type", "message": "Query type is required"})

The following resources can be retrieved with the zoom parameter as described in the section on linking

Field Description
pw:location A location model

Note that this endpoint does not support specifying fields on nested resources.

GET /locations Search for parking facilities in a geographic area.

Please note this endpoint requires a data license.

Request

Parameter Type Description
q String required The query for the destination near which you require parking. See above for how to use this parameter.

Note: pagination is not supported on this endpoint.

There are numerous sub-parameters for the q parameter. For some sub-parameters, you can also include distance, which will return quotes within that distance. If not supplied, distance is set to 1 mile. Available sub-parameters are as follows:

Query type Description
venue_id A ParkWhiz Venue ID.
coordinates A set of coordinates. See the note on coordinates
bounds A list of coordinates. They must be sequential clockwise, though you can start with any coordinate and bounds can be any polygon. See the note on coordinates
distance The radius around a pair of coordinates, event, venue, or gplaces_place. This is measured in miles and defaults to 1.

Response

The response will be an array of Location models.

GET /locations/{location_id} Retrieve single facility

Retrieve details about the specified parking facility.

Request

Parameter Type Description
location_id String required ParkWhiz Location ID

Response

The response will be a location model.

Error responses

Status Message
404 Location not found
400 This will supply a field and relevant validation error message

POST /locations/{location_id}/reviews Create facility review

Create a review for the specified facility.

Request

Parameter Type Description
booking_id Integer required ParkWhiz Location ID
rating Integer required The user's rating of the location, from 1-5.
comment String The comment left by the user about the location.

Response

The response will be a location model.

GET /locations/{location_id}/reviews Retrieve facility reviews

Retrieve reviews for specified parking facility.

Request

Parameter Type Description
location_id String required ParkWhiz Location ID

Response

The response will be an array of review models.

Error responses

Status Message
404 No reviews found
400 This will supply a field and relevant validation error message (e.g. {"field": "location_id", "message": "Location ID is required"})

GET /locations/{location_id}/reviews/{review_id} Retrieve single review

Retrieve a specific parking facility review.

Request

Parameter Type Description
location_id Integer required ParkWhiz Location ID
review_id Integer required ParkWhiz Review ID

Response

The response will be a review model.

Error responses

Status Message
404 Review not found
400 This will supply a field and relevant validation error message (e.g. {"field": "review_id", "message": "Review ID must be an integer"})

Bookings

The following endpoints allow you to create and manage your parking bookings. These will return a 401 status if you are not authenticated.

Note: If you are providing access control solutions for a parking location and need a list of upcoming bookings, contact dev-admin@parkwhiz.com for a different Access Control API. These are only for managing and viewing your own, personal parking.

Required Scopes

The bookings endpoints are accessible via tokens with the scope internal, mobile, partner, or public. See the scopes section for more information.

POST /bookings Book parking

Book parking based on a quote.

Request

Booking parameters should be provided in the POST body.

Parameter Type Description
final_price Float required Purchase price returned by POST /bookings/previews
quote_id String ParkWhiz Purchase Option ID (supplied by GET /quotes, resembling a UUID)
booking_hold_id Integer ParkWhiz Partner Booking Hold ID
add_on_ids String Comma separated list of ParkWhiz Add On IDs to purchase with this quote (supplied by GET /quotes, resembling a UUID)
customer_id Integer ParkWhiz ID of the customer that the quote is being purchased for
customer_email String Email of the customer that the quote is being purchased for
customer_first_name String First name of the customer that the quote is being purchased for
customer_last_name String Last name of the customer that the quote is being purchased for
payment_method_nonce String One time use Braintree payment nonce generated by the client
saved_payment_token String BT token of previously saved parment method
save_credit_card Boolean Whether the customer wants their credit card saved for future use
skip_credit_card_vaulting Boolean Should the credit card vaulting in Braintree be skipped
enterprise_account_id Integer ID of the Enterprise account being used to pay for this purchase
expense_memo String Note attached to this purchase when made through Enterprise
invoice Boolean Whether to book parking for a partner on invoice
coupon_code String ParkWhiz coupon code
auto_apply_coupon Boolean Whether to automatically apply ParkWhiz coupons attached to the customer
device_data String Braintree/Kount device data for fraud prevention
purchase_vector String deprecated Information about how the customer accessed and purchased parking
portal_affiliate_id Integer ID of the Portal affiliate account to be credited for this purchase
legacy_affiliate_id Integer ID of the legacy affiliate account to be credited for this purchase
monthly_start_date ISO 8601 Timestamp Date on which the customer's monthly parking begins
send_email_confirmation Boolean Whether to send a ParkWhiz booking confirmation email to the customer (default false)
plate_number String If sent in this will add a license plate to the booking.

Either the quote_id or booking_hold_id MUST be provided.

The customer_id should be supplied for purposes of customer identification. However, the customer's email may be used as an alternative. One of these two identifications MUST be provided.

POST /bookings requires use of either a client credentials or user authorization OAuth token as

Header Description
Authorization Bearer authorization token

Response

The response will be an arry of booking model objects.

Error responses

Status Message
404 Location not found
400 This will supply a field and relevant validation error message (e.g. {"field": "location_id", "message": "Location ID must be an integer"})

POST /bookings/previews Preview booked parking

Preview the booking resulting from purchase of a parking quote.

Request

Booking parameters should be provided in the POST body.

Parameter Type Description
quote_id String required ParkWhiz Purchase Option ID (supplied by GET /quotes, resembling a UUID)
hold_expires_in Integer Time in seconds after which the booking hold will expire
auto_apply_coupon Boolean Whether to automatically apply ParkWhiz coupons attached to the customer
add_on_ids String Comma separated list of ParkWhiz Add On IDs to purchase with this quote (supplied by GET /quotes, resembling a UUID)
book_extend_times Boolean Whether to book auto-extended start and end times (true) or those from the original search (false)
coupon_code String ParkWhiz coupon code
purchase_vector String Information about how the customer accessed and purchased parking
validate_add_ons Boolean Whether to validate the add ons or not

If this endpoint is called with a token that is associated with a partner that has opted in to booking holds, then a booking hold will be created.

POST /bookings/previews requires use of either a client credentials or user authorization OAuth token as

Header Description
Authorization Bearer authorization token

Response

The response will be a booking preview model.

Error responses

Status Message
404 Location not found
400 This will supply a field and relevant validation error message (e.g. {"field": "location_id", "message": "Location ID must be an integer"})

GET /bookings Retrieve booking list

Retrieve a list of bookings that have been purchased under your account.

Request

Parameter Type Description
q See below The query for your bookings search. See above for how to use this parameter.

There are numerous sub-parameters for the q parameter. For some sub-parameters, you can also include distance, which will return locations within that distance. If not supplied, distance is set to 1 mile. Available sub-parameters are as follows:

Query types Description
starting_after A timestamp, limiting returned bookings to those starting after this time
starting_before A timestamp, limiting returned bookings to those starting before this time
upcoming A shortcut to specifying starting_after with today's date. Activated with value true
past A shortcut to specifying starting_before with today's date. Activated with value true
active A shortcut specifying that you want bookings that have not been cancelled or refunded
cancelled A shortcut specifying that you want bookings that have been cancelled or refunded
busines_purchase A shortcut specifying that you want bookings purchased with a Business Profile or ParkWhiz for Business account
location_id The ID(s) of a ParkWhiz location, limiting bookings to those facilities e.g. 1234,5678
license_plate A list of license plates, limiting bookings to those with the following license plates e.g. ABC123,ZYX987. Also can be activated by the value true, limiting bookings to those with any license plates.

GET /bookings requires use of a user authorization OAuth token for the user whose bookings you are accessing as

Header Description
Authorization Bearer authorization token

Response

The response will be an array of booking models.

Error responses

Status Message
400 This will only happen if you don't send any valid parameters, e.g. {"fields": ["starting_after", "starting_before", "account_id", "past", "upcoming"], "message": "At least one parameter is required"}
403 You do not have permission to retrieve these bookings (e.g. not having access to the account you provided with account_id)
404 No bookings found

GET /bookings/{booking_id} Retrieve booking details

Get details of a booking

Request

Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID or Partner Booking Hold ID
authorization_code String One click authorization code for the ParkWhiz booking

If a Partner Booking Hold ID is supplied in place of a Booking ID, then a booking hold will be returned. If you are looking up a booking hold, you must supply the booking hold authorization code, an internal token, the partner's token, or the user token that was used to create the booking hold.

GET /booking/{booking_id} requires use of a user authorization OAuth token for the user whose bookings you are accessing as

Header Description
Authorization Bearer authorization token

Response

The response will be a booking model

Error responses

Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found

DELETE /bookings/{booking_id} Cancel booking

Cancel a booking

Request

Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID or Partner Booking Hold ID
send_email_confirmation Boolean Whether or not you would like ParkWhiz to send an email confirmation to the customer
authorization_code String One click authorization code for the ParkWhiz booking

DELETE /bookings/{booking_id} requires use of either a client credentials token or user authorization token passed in the header. Alternatively you can pass the booking's authorization_code as a parameter.

If a Partner Booking Hold ID is passed in instead of a Booking ID, then the booking hold will be deleted. Deleting a booking hold requires the booking hold authorization code, an internal token, the partner's token, or the user token that was used to create the booking hold.

Header Description
Authorization Bearer authorization token

Response

The response will be a 204 (No Content) HTTP status.

Error responses

Status Message
400 Past bookings cannot be cancelled
403 Not authorized to cancel this booking
404 Booking not found

GET /bookings/{booking_id}/parking_passes Retrieve booking parking pass

Get a pre-formatted ParkWhiz parking pass for this booking. This parking pass will be the only element of a length 1 array.

Request

Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID

GET /booking/{booking_id}/parking_passes requires use of a user authorization OAuth token for the user whose bookings you are accessing as

Header Description
Authorization Bearer authorization token

Response

The response will be an array of parking pass models containing one element.

Error responses

Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found

GET /bookings/{booking_id}/vehicles Retrieve vehicle associated with this booking

Get information about the vehicle associated with a booking, used to validate vehicle parking at many locations.

Request

Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID

GET /booking/{booking_id}/vehicles requires use of a user authorization OAuth token for the user whose booking you are accessing as

Header Description
Authorization Bearer authorization token

Response

The response will be an array of vehicle models containing one element.

Error responses

Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found

PUT /bookings/{booking_id}/vehicles Set the vehicle associated with this booking

Add information about the vehicle associated with a booking, used to validate vehicle parking at many locations.

Request

Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID
vehicle_id Integer A ParkWhiz vehicle ID
plate_number String A vehicle license plate number
plate_state String A vehicle license plate state
label String A descriptive label for the vehicle
default Boolean Whether this is the customer's default vehicle
booking_authorization_code String When this is set, a new vehicle will be created to be associated with this booking. This new vehicle will not be set as the default vehicle for the user.

A known, existing vehicle can be attached to the booking by specifying a vehicle_id. If the desired vehicle does not exist in the ParkWhiz system, the plate_number and plate_state must be specified to add a new vehicle, with label and default optional.

PUT /booking/{booking_id}/vehicles requires use of a user authorization OAuth token for the user whose booking you are accessing.

Header Description
Authorization Bearer authorization token

Response

The response will be a vehicle model.

Error responses

Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found

POST /bookings/{booking_id}/previews Preview extended booking parking

Quote and preview the result of modifying the time of an existing booking.

Request

Preview parameters should be provided in the POST body.

Parameter Type Description
authorization_code String One click authorization code for the ParkWhiz booking
end_time ISO 8601 Timestamp The new parking end time
include_suggestions Boolean Whether or not to return up to 3 suggested new parking times. Defaults to false

Currently you can only use this endpoint AFTER the booking has started. If an end_time parameter is not provided, you must specify include_suggestions=true. An authorization token or authorization_code is required.

Response

The response will be a booking extend preview model.

Error responses

Status Message
400 Booking was already cancelled
400 End time was in an invalid format
400 Location does not support booking extension
400 Modifying a booking (before the start time) is not yet supported
400 New end_time must be greater than booking's current end time
401 You are not authorized for this booking
404 Booking not found
500 Resources required to complete this request are currently not available

PUT /bookings/{booking_id} Book extended parking

Extend the time of an existing booking given a quote id obtained from the extend preview endpoint.

Request

Parameter Type Description
final_price Float required Purchase price returned by POST /bookings/{booking_id/previews
quote_id String required ParkWhiz purchase option id returned by POST /bookings/{booking_id/previews resembling a UUID
authorization_code String One click authorization code for the ParkWhiz booking
device_data String Braintree/Kount device data for fraud prevention
enterprise_account_id Integer ID of the Enterprise account being used to pay for this purchase
expense_memo String Note attached to this purchase when made through Enterprise
invoice Boolean Whether to book parking for a partner on invoice
payment_method_nonce String One time use Braintree payment nonce generated by the client
saved_payment_token String Braintree token of previously saved payment method
send_email_confirmation Boolean Whether to send a ParkWhiz booking confirmation email to the customer (default false)

Currently you can only use this endpoint AFTER the booking has started. At least one of enterprise_account_id, invoice, payment_method_nonce or saved_payment_token must be provided. An authorization token or authorization_code is required.

Response

The response will be an updated booking model reflecting the changes.

Error responses

Status Message
400 Booking was already cancelled
400 Location does not support booking extension
400 Modifying a booking (before the start time) is not yet supported
400 New end_time must be greater than booking's current end time
400 The requested quote id has expired
401 You are not authorized for this booking
404 Booking not found
500 Resources required to complete this request are currently not available

Monthly Bookings

Required Scopes

The monthly bookings endpoints are accessible via tokens with the scope internal, mobile, or public. See the scopes section for more information.

GET /monthly_bookings Retrieve monthly booking list

Retrieve a list of monthly bookings that have been purchased under your account.

Request

Parameter Type Description
q See below The query for your monthly bookings search. See above for how to use this parameter.

Query types Description
starting_after A timestamp, limiting returned monthly bookings to those starting after this time
starting_before A timestamp, limiting returned monthly bookings to those starting before this time
upcoming A shortcut to specifying starting_after with today's date
past A shortcut to specifying starting_before with today's date
active A shortcut specifying that you want monthly bookings that have not been cancelled or refunded
cancelled A shortcut specifying that you want monthly bookings that have been cancelled or refunded
location_id The ID(s) of a ParkWhiz location, limiting monthly bookings to those facilities e.g. 1234,5678

GET /monthly_bookings requires use of a user authorization OAuth token for the user whose monthly bookings you are accessing as

Header Description
Authorization Bearer authorization token

Response

The response will be an array of monthly booking models.

Error responses

Status Message
400 There are no valid fields in your request.
401 Not authorized to view this monthly booking
404 Monthly Booking was not found

GET /monthly_bookings/{monthly_booking_id} Retrieve monthly booking details

Get details of a monthly booking

Request

Parameter Type Description
monthly_booking_id Integer required A ParkWhiz Monthly Booking ID
authorization_code String One click authorization code for the ParkWhiz booking

GET /monthly_booking/{monthly_booking_id} requires use of a user authorization OAuth token for the user whose bookings you are accessing as

Header Description
Authorization Bearer authorization token

Response

The response will be a booking model

Error responses

Status Message
400 There are no valid fields in your request.
401 Not authorized to view this monthly booking
404 Monthly Booking was not found

Venues and Events

GET /venues Search venues

Request

Parameter Type Description
q Query String The search query string
sort Sort String The search query string

Query types Type Description
name String Name of your destination venue
coordinates Coordinates The coordinate of your destination
slug String Unique URL identifier for venue
stubhub_venue_id String A StubHub venue ID
ticketmaster_venue_id String A Ticketmaster venue ID
Sort by Description
name The names of the venues
distance Distance to the venue, with respect to the search coordinates (if provided)

Response

The response will be an array of venue models.

GET /venues/{venue_id} Retrieve venue details

Retrieve details about a specific venue.

Request

Parameter Type Description
venue_id Integer required ParkWhiz Venue ID

Response

The response will be a venue model.

Error responses

Status Message
404 Venue not found
400 This will supply a field and relevant validation error message (e.g. {"field": "venue_id", "message": "Venue ID must be an integer"})

GET /venues/{venue_id}/events Retrieve events at venue

Retrieve a list of events at a specific venue

Request

Parameter Type Description
venue_id Integer required ParkWhiz Venue ID
q Query String The search query string
sort Sort String The search query string

Query types Type Description
name String Name of your destination event
starting_before ISO 8601 Timestamp Only return events starting before this time
starting_after ISO 8601 Timestamp Only return events starting after this time. Default: the current time.
Sort by Description
name The names of the events
start_time Start times of the events

Response

The response will be an array of event models.

GET /events Search events

Request

Parameter Type Description
q Query String The search query string
sort Sort String The search query string

Query types Type Description
name String Name of your destination event
starting_before ISO 8601 Timestamp Only return events starting before this time
starting_after ISO 8601 Timestamp Only return events starting after this time
venue_id Integer(s) list of ParkWhiz venue ID(s) to filter events by e.g. 1234,5678
Sort by Description
name The names of the events
start_time Start times of the events

Response

The response will be an array of event models.

GET /events/{event_id} Retrieve event details

Retrieve details about the specified event

Request

Parameter Type Description
event_id Integer required ParkWhiz Event ID

Response

The response will be a event model.

Error responses

Status Message
404 Event not found
400 This will supply a field and relevant validation error message (e.g. {"field": "event_id", "message": "Event ID must be an integer"})

Hubs

GET /hubs Search hubs

Request

Parameter Type Description
q Query String The search query string

Query types Type Description
nearby_coordinates Coordinates Coordinates that are near to the hub
distance Integer the maximum distance between nearby_coordinates and the hubs to be matched. Default 50
only_major_metros Boolean Will only return major metro areas (eg: New York, Chicago, San Francisco, DC)

Response

The response will be an array of hub models.

Accounts

Required Scopes

The accounts/payment_methods endpoints are accessible via tokens with the scope internal, mobile, or public. See the scopes section for more information.

POST /accounts Create new account

Create a new account

Request

Parameter Type Description
email String Required The email address that you want to use.
password String Required The password that you want to use.
first_name String Required The first name that you want to use.
last_name String Required The last name that you want to use.
phone_number Integer The phone number that you want to use.
phone_country_code Integer Phone country code, defaults to 1

Response

The response will be an account model.

Errors

Status Message
400 (An array of validation errors.)

GET /accounts/me Your account overview

Get your account info. This is an alias for /accounts/{account_id} and "me" may be used in place of the account ID in all accounts endpoints.

Request

There are no additional parameters for this request.

Response

The response will be an account model.

Error responses

Status Message
403 You must be logged in to use this shortcut.

GET /accounts/{account_id} Account overview for user

Get your account overview.

Request

There are no additional parameters for this request.

Response

The response will be an account model.

Error responses

Status Message
403 You must be logged in to use this shortcut.
404 That account could not be found.

PUT /accounts/{account_id} Update account info

Update your account info

Request

Parameter Type Description
email String The email address that you want to use.
password String The password that you want to use.
first_name String The first name that you want to use.
last_name String The last name that you want to use.
phone_number Integer The phone number that you want to use.

Response

The response will be an account model.

Errors

Status Message
400 Account could not be updated.
404 You must use 'me' as the ID.

GET /accounts/{account_id}/frequent_locations Get a list of your frequent locations

Retrieve a list of the customer's frequent locations. These are active locations that the customer has booked at more than once, ordered by number and recency of bookings.

Response

The response will be a list of location models.

Errors

Status Message
404 You must use 'me' as the ID.

Retrieve a list of recommended locations and times for the customer to book at. These are based on the customers previous purchase history.

Request

Parameter Type Description
limit Integer Maximum number of recommendations to return. Defaults to 5, 100 max.

Response

The response will be a list of recommendations ordered by relevancy as follows:

Field Type Description
start_time ISO 8601 Timestamp The recommended start time to book.
end_time ISO 8601 Timestamp The recommended end time to book.
location_id Integer The ParkWhiz location ID of the recommended location.

The following resources can be retrieved with the zoom parameter as described in the section on linking. The location is part of the default zoom.

Field Description
pw:location The quote's location

Errors

Status Message
404 You must use 'me' as the account_id.

GET /accounts/{account_id}/vehicles Retrieve vehicles

Retrieve a list of vehicles saved to the account

Request

No additional parameters are required.

Response

The response will be an array of vehicle models.

Errors

Status Message
404 You must use 'me' as the ID.

POST /accounts/{account_id}/vehicles Add vehicle

Store vehicle information for use in a future booking

Request

Parameter Type Description
label String Required A brief label for the vehicle. For example, "Bill's SUV".
plate_number String Required The license plate number.
plate_state String The license plate state.
default Boolean Whether or not this vehicle is the account's default vehicle. Note: an account can only have one default vehicle.

Response

The response will be a vehicle model.

Errors

Status Message
404 You must use 'me' as the ID.

GET /accounts/{account_id}/vehicles/{vehicle_id} Retrieve vehicle details

Retrieve details about a specified vehicle saved to the account.

Request

There are no additional parameters for this request.

Response

The response will be a vehicle model.

Errors

Status Message
404 That vehicle was not found.
404 You must use 'me' as the ID.

PUT /accounts/{account_id}/vehicles/{vehicle_id} Update vehicle details

Update the specified vehicle saved to the account

Request

Parameter Type Description
label String A brief label for the vehicle. For example, "Bill's SUV".
plate_number String The license plate number.
plate_state String The license plate state.
default Boolean Whether or not this vehicle is the account's default vehicle. Note: an account can only have one default vehicle.

Response

The response will be a vehicle model.

DELETE /accounts/{account_id}/vehicles/{vehicle_id} Remove vehicle

Remove the specified vehicle from the account

Request

There are no additional parameters for this endpoint.

Response

The response will be a Status 204 NO CONTENT code.

Errors

Status Message
400 This vehicle could not be deleted.
404 That vehicle was not found.
404 You must use 'me' as the ID.

GET /accounts/{account_id}/payment_methods Get payment methods associated with the account

Request

There are no additional parameters for this request.

Response

The response will be an array of payment methods.

Errors

Status Message
400 There are no valid fields in your request.
404 You must use 'me' as the ID.

POST /accounts/{account_id}/payment_methods Add payment method to account

Request

Parameter Type Description
payment_method_nonce String Required Braintree nonce passed in from client

Response

The response will be a payment method.

Errors

Status Message
400 Unable to save payment method
404 You must use 'me' as the ID.

PUT /accounts/{account_id}/payment_methods/{braintree_token} Edit a user's payment method

Payment methods represent both credit card and ParkWhiz For Business accounts. You're able to edit these payment methods through this endpoint. A side effect of a successful call is that the payment method model attributes will be refreshed with data from braintree. So if the payment object stored on braintree is somehow different from the payment method model, this will cause the attributes to be updated.

This endpoint requires a Braintree payment method nonce. To learn more about the Braintree payment method nonce refer to the Braintree documentation.

Request

Parameter Type Description
payment_method_nonce String Required Braintree nonce passed in from client
label String Optional The label for the credit card
is_default Boolean Optional Whether or not the card is the user's default payment method

Response

The response will be a payment method.

Errors

Status Code Message
200 n/a Payment method was edited successfully
400 no_valid_fields There are no valid fields in your request.
400 braintree_payment_method_error unable to save payment method
400 update_payment_method_has_active_ticket Can't update a payment method that has an active ticket
401 unauthorized_payment_tokens You must be logged in to use this endpoint
404 payment_method_not_found Payment method not found.

DELETE /accounts/{account_id}/payment_methods/{braintree_token} Delete or disable payment methods

Payment methods represent both credit card and ParkWhiz For Business accounts. You're able to delete credit cards and disable your enterprise account status.

Request

There are no additional parameters for this request.

Response

The response will be a 204 status code.

Errors

Status Code Message
400 del_payment_method_has_active_ticket Can't delete a payment method that has an active ticket
401 unauthorized_payment_tokens You must be logged in to use this endpoint
403 no_enterprise_membership User is not attached to supplied enterprise account.
404 del_payment_methods_id_not_me You must use 'me' as the ID.
404 del_no_method Payment method was not found.

POST /accounts/recoveries Recover account

Send recovery email

Request

Parameter Type Description
email String Required The email address of that account that you are recovering.

Response

The response will be a 202 status code.

Errors

Status Message
400 Sorry, your account's password was not reset.
404 We could not find an account with that email address.

POST /accounts/reset_password Reset account password

Reset an account's password after recovery email sent.

Request

Parameter Type Description
email String Required The email address of that account that you are recovering.
password String Required The new password for the account.
password_reset_token String Required The reset token provided in the password reset email.
client_id String The client id for the oauth application, ParkWhiz application is the default.
scope String The request scope, only allows public and mobile.

Response

The response will be token information with a 202 status code.

Errors

Status Message
400 Invalid scope requested:
400 Could not update password.
400 Invalid account information provided.

POST /accounts/{account_id}/phone_verification Verify phone number

Send verification request or attempt to verify the phone number depending on if the verification code is present.

Request

Parameter Type Description
phone_number String Required Phone number to verify
phone_country_code Integer Phone country code, defaults to 1
verification_code String Code received after previous verification request, sends code if not passed.

Response

If verification_code was ommitted, response will be a status of 204, otherwise the response will be an account model.

Errors

Status Message Code
400 Verification code does not match. verification_code_mismatch
400 Verification timeframe expired. verification_timeframe_expired
400 Phone number already in use. phone_already_in_use
400 Failed to send SMS invalid_sms
400 Failed to start verification request phone_verification_not_started
404 Invalid phone number. invalid_phone_number
404 You must use 'me' as the account_id. account_phone_verification_id

Sellers

GET /seller/{seller_id} Lookup seller by ID

Get the seller associated with a seller ID.

Request

Parameter Type Description
seller_id Integer Required ID of the seller that you're looking up

Response

The response will be an seller models.

Errors

Status Message
404 That pricing could not be found.

Business Profiles

Tickets

GET /tickets Retrieve tickets

Note: please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Returns tickets associated with a given customer's account which are currently in the open or payment_failed state.

Request

Note: GET /v4/tickets requires a user authorization token.

Header Description
Authorization Bearer authorization token

Response

A successful response will include a 200 status code with an array of ticket model objects in the body.

POST /tickets/previews Preview a ticket

Note: please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Previews a ticket ticket before creating it.

Request

Parameters should be provided in the POST body.

Parameter Type Description
ticket_encoded_string String required A bar or QR encoded string
ticket_type String required The scanned ticket type. Supported values include: Code-39, I2/5 and QR-Code
enterprise_account_id Integer ID of the Enterprise account being used to pay for the parking
saved_payment_token String Braintree token of previously saved payment method
coupon_code String Coupon code to validate for the preview
purchase_vector String Information about how the customer accessed and purchased parking
auto_apply_coupon Boolean Attempt to automatically apply any coupons which are relevant for the current user. Auto applied coupon codes will be returned in the coupon_code response and should be manually passed in when creating the ticket.

Note: GET /v4/tickets/previews requires a user authorization token.

Header Description
Authorization Bearer authorization token

Response

A successful response will be a ticket preview model with a 200 status. Please note the warnings that can be returned from a preview. The warnings will become errors when attempting to create the ticket unless they are resolved.

Error responses

Status Code Message
400 barcode_damaged Barcode is damaged and cannot be decrypted
400 barcode_not_supported Barcode is not supported
400 invalid_pw_location This location does not support scanning tickets
400 invalid_token_type The provided token must be a user token
400 user_suspended Customer's account has been suspended
404 parking_lot_not_found Parking lot not found
500 internal_server_error An internal server error has occurred
500 malformed_ticket_scan_response Resources required to complete this request are currently not available
503 scan_timed_out Resources required to complete this request are currently not available
503 unable_connect Unable to connect to the PARCS

POST /tickets Create a ticket

Note: please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Creates a new ticket with the open status. Creating a new ticket authorizes payment to be collected after the customer exits the facility. A customer can only have one active ticket at a time (where an active status is open, closed or payment_failed).

Request

Parameters should be provided in the POST body.

Parameter Type Description
ticket_encoded_string String required A bar or QR encoded string
ticket_type String required The scanned ticket type. Supported values include: Code-39, I2/5 and QR-Code
enterprise_account_id Integer ID of the Enterprise account being used to pay for the parking
saved_payment_token String Braintree token of previously saved payment method
coupon_code String Coupon code to apply against the purchase
purchase_vector String Information about how the customer accessed and purchased parking

At least one of enterprise_account_id or saved_payment_token must be provided. Note: GET /v4/tickets requires a user authorization token.

Header Description
Authorization Bearer authorization token

Response

A successful response will be a newly created ticket model with a 201 status.

Error responses

Status Code Message
400 active_ticket Customer already has too many active tickets
400 barcode_damaged Barcode is damaged and cannot be decrypted
400 barcode_not_supported Barcode is not supported
400 invalid_payment_method The provided payment method is invalid
400 invalid_pw_location This location does not support scanning tickets
400 invalid_token_type The provided token must be a user token
400 ticket_open Ticket was already approved
400 ticket_paid Ticket was already paid
400 unverified_phone_number Customer's phone number has not been verified
400 user_suspended Customer's account has been suspended
404 parking_lot_not_found Parking lot not found
500 internal_server_error An internal server error has occurred
500 malformed_ticket_scan_response Resources required to complete this request are currently not available
503 approve_payment_timed_out Resources required to complete this request are currently not available
503 scan_timed_out Resources required to complete this request are currently not available
503 unable_connect Unable to connect to the PARCS

Coupon errors

Status Code Message
400 coupon_expired Coupon is expired
400 coupon_first_purchase_only This promo code is just for new users
400 coupon_first_purchase_vector_purchase_only This promo code is only good for your first purchase in app
400 coupon_invalid_email_domain Coupon is only valid for users with <@domain> email
400 coupon_invalid_location Coupon is not valid at this location
400 coupon_invalid_msa Coupon is only valid for parking in
400 coupon_invalid_purchase_vector Coupon is only valid when purchased through
400 coupon_nonrefundable_user Coupon is invalid for this user
400 coupon_pricing_mismatch Coupon is only valid for parking
400 coupon_user_required Coupon is only valid for existing users
400 invalid_coupon_code Coupon code is invalid
400 seller_coupon_mismatch Coupon is not valid for this seller
400 user_coupon_mismatch Coupon is not valid for this user
400 user_coupon_whitelist_mismatch Coupon is not valid for this user

POST /tickets/:id/payments Pay a ticket

Note: please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Typically a customer's payment method will automatically be charged after they exit the garage. In some cases that payment may fail (e.g. bad credit card, payment declined, etc). When payment fails, this endpoint can be used to manually pay for the ticket. This endpoint can only be used for tickets with a status of payment_failed.

Request

Parameters should be provided in the POST body.

Parameter Type Description
amount String required The amount being paid - should match the value of the ticket
enterprise_account_id Integer ID of the Enterprise account being used to pay for the parking
saved_payment_token String Braintree token of previously saved payment method

At least one of enterprise_account_id or saved_payment_token must be provided. Note: POST /v4/tickets/:id/payments requires a user authorization token.

Header Description
Authorization Bearer authorization token

Response

A successful response will be a ticket model with a 200 status.

Error responses

Status Code Message
400 invalid_enterprise_account_id User does not have active membership in business account
400 invalid_payment_method The provided payment method is invalid
400 invalid_saved_credit_card_id Unable to find saved credit card
400 invalid_ticket_amount Ticket amount due is '{ticket.amount}' but was given: '{amount}'
400 invalid_ticket_status Ticket is {ticket.status} and can't be paid
400 invalid_token_type Token is not authorized for this endpoint
400 no_enterprise_account_payment_method Business account does not have active payment method
400 user_suspended Customer's account has been suspended
404 ticket_not_found Could not find ticket {id}