Requesting A Review

The Nearby New Review Request API is organized around REST. JSON will be returned in all responses from the API, including errors.



All calls made to the Nearby Now Review Request API require authentication.

You authenticate to the Nearby Now API by providing your Agency API key, and one of your client’s Account API keys in the request. Your agency API keys, and customer account API keys carry many privileges, so be sure to keep them secret.

Authentication to the API occurs via HTTP Basic Auth. Provide your agency API key as the basic auth username, and your client’s Account API key as the basic auth password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.


  • name: (required) The customer’s first or full name
  • email: (required – if smsPhoneNumber is not provided) The customer’s email address you wish to send the review request to
  • smsPhoneNumber: (required – if email is not provided) The customer’s mobile number you wish to send the review request to. You are responsible for ensuring that the number is a mobile number capable of receiving SMS messages
  • Note – email or smsPhoneNumber must be present. Both can be present. If neither are present, the request will be rejected.
  • reference: (optional) A message about the work performed
  • street: (required) The customer’s street
  • city: (required) The customer’s city
  • state: (required) The customer’s state
  • postalCode: (required) The customer’s postal code
  • userEmail: (required) The email address of the user you want to check-in as and send the review request. Must be a verified active user on the Storefront. Use the Users List Endpoint to retrieve a list of StoreFront Users that can publish a check-in.
  • userCheckinId: (optional) The id of an existing checkin that you want to sent a review request from. If a check-in id is not provided, a new check-in will be created.
  • photo: (optional) The photo to attach to the checkin, if not using an existing checkin reference. Please note, if sending a photo, you’ll need to send a request of type multipart/form-data


The Nearby Now API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, authentication information was missing, etc.), and codes in the 5xx range indicate an error with Nearby Now’s servers.

All requests, success or failure, will return a JSON response with a Review Request Object and a success flag. A failed request will contain an error message string describing the problem.


Here’s an example cURL request that shows how simple it is to call the Nearby Now API, as well as an example success and error response:

curl -v -s -k \
  --user 'agency_api_token:account_api_token' \
  -F 'name=John Q Sample'\
  -F '' \
  -F 'reference=Installing a new System' \
  -F 'street=201 E Jefferson St' \
  -F 'city=Phoenix' \
  -F 'state=AZ'\
  -F 'postalCode=85251'
  -F ''

Latest Blog Posts