Response Codes

The following response codes are what we can respond to API requests with.

Success

Code Name Description
200 Ok Standard response for successful HTTP requests.
201 Created The request has been fulfilled and resulted in a new resource being created.
202 Accepted The request has been accepted for processing, but the processing has not been completed.
204 No Content The server successfully processed the request, but is not returning any content.
205 Processed The server successfully processed the request, but is not returning any content.

Redirection

Code Name Description
301 Moved Permanently This and all future requests should be directed to the given Location header.
302 Found This request should be directed to the given Location header.
303 See Other The response to the request can be found under another Location (header) using a GET method.

Client Error

Code Name Description
400 Bad Request The request cannot be fulfilled due to bad syntax.
401 Unauthorized Authentication is possible but has failed or not yet been provided.
403 Forbidden The request was a legal request, but the server is refusing to respond to it.
404 Not Found The requested resource could not be found but may be available again in the future.
405 Method Not Allowed A request was made of a resource using a request method not supported by that resource.
406 Not Acceptable The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.
410 Gone Indicates that the resource requested is no longer available and will not be available again.
429 Too Many Requests The user has sent too many requests in a given amount of time.

Server Error

Code Name Description
500 Server Error An internal error has occured and we have been notified.
503 Service Unavailable The server is currently unavailable.

Employees

You can update your entire employee directory with our csv upload.

Import Employees

You can automatically refresh your employee directory as long as you can export to a csv. If you’re using LDAP or Active Directory, both systems have easy ways to export their data. When crafting your employee directory csv, it’s very important you strictly follow the format prescribed. It has to be in the exact order of Full Name, Email, and then Phone Number.

CSV Format

Column Description
Full Name String (required) The full name of the employee
Email String (optional) The email of the employee
Phone Number String (optional) The phone number of the employee

Although optional, email is used as the primary identifier by Envoy. If your csv does not contain email entries, it will override the previous employee directory in full. This means that any assistant information will have to be added back in. Your employees will also not be able to take advantage of the Envoy mobile app.

curl -F [email protected] https://app.envoy.com/api/configuration/employee_list?api_key=YOUR_API_KEY_HERE

After your csv has been prepared, you can easily upload it to Envoy using curl. Be careful as this will replace your existing employee directory.

On OSX, crontab -e opens crontab

00 9 * * * curl -F [email protected] https://app.envoy.com/api/configuration/employee_list?api_key=YOUR_API_KEY_HERE

If you’re using Mac, the easiest way to do this is using a cronjob. To learn more about setting up a cronjob, check out this quick reference.

This example will upload the CSV of your employee directory to Envoy every day at 9:00am.

Visitor Pre-Registration

Bulk Visitor Pre-Registration

This version of bulk visitor pre-registration allows you to pre-register guests by uploading a CSV. We’re working to support a variety of upload and file formats in the future.

CSV Format

"Peter Parker","[email protected]","2015-12-25 12:00 PM",,"Tony Stark"
"John Doe","[email protected]","2015-10-05 3:30 PM",,"Beverly"
Column Description
invitee_name String (required) The full name of the person being invited.
invitee_email String (optional) The email of the person being invited.
expected_arrival_time DateTime (required) This needs to be in an iso6601 format. It should follow this format 2014-07-29 4:00 PM in their local time.
private_notes String (optional)
host_name String (required) The person who is hosting the visitor.

Request

POST https://app.envoy.com/api/invites/upload
curl "https://app.envoy.com/api/invites/upload?api_key=API_KEY" \
  -F file=@invites.csv

Request Parameters

Name Description
api_key String (required) The account api key to upload for.
file String (required) The CSV file you wish to upload.
notify_invitee Boolean (optional) Will send email invites to those on the list.

Response Codes

Status Description Cause
200 Ok Found.
400 Bad Request Request parameters may be incorrect.
401 Unauthorized Invalid api_key.
500 Server Error Something on our end is wrong.
503 Unavailable Overloaded servers / Routing issues.

Response

{
  "message": "Invitee list is updated successfully."
}

Only application/json is returned.

Field Description
message String The message if the request was successful.

Error Response

{
  "error": "`file` parameter is invalid"
}
Field Description
error String If there was an issue with the upload it will be output here.

Entries

You can pull entry data on a per location basis in JSON format. We’re making this end point more robust, but in the meantime you can use our v1 end point.

Location visitors

GET https://app.envoy.com/api/entries.json?api_key=API_KEY
[
  {
    "id":1275527,
    "signed_in_time_utc":"2015-06-04 21:32:01",
    "signed_in_time_local":"2015-06-04 14:32:01",
    "signed_out_time_utc":"",
    "signed_out_time_local":"",
    "your_full_name":"Tony Stark",
    "your_email_address":"[email protected]",
    "nda_pdf_url":"",
    "photo_url":"",
    "Custom Fields":[
      {
        "Your Full Name":"Tony Stark"
      },
      {
        "Your Email Address":"[email protected]"
      }
    ]
  }
]

See all the entries for the master location. By default, it will return all time entries but you can also filter by to and from dates to get a range.

Request Parameters

Name Description
api_key String (required) The location API key to download for.
from_date DateTime (optional) iso8601 format ie. 2014-03-01.
to_date DateTime (optional) iso8601 format ie. 2014-03-31.

Webhooks

Webhooks are formatted as application/x-www-form-urlencoded.

# Headers
Total-Route-Time: 0
Accept: */*
X-Newrelic-Id: VwEAVFNaGwEEUFBTAQU=
Content-Length: 1076
Connect-Time: 0
X-Newrelic-Transaction: PxQAWAQFDAsEU1QABwQOA1ACFB8EBw8RVU4aVQFaUgYLUQ5UU1EGWwECBENKQQ0AB1ZXU1QCFTs=
Connection: close
Content-Type: application/x-www-form-urlencoded
Via: 1.1 vegur
User-Agent: Ruby
X-Request-Id: 0f554867-236e-4ae3-a603-b337cea9fb76
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Host: requestb.in

# Form / Post Parameters
entry: {"id":1386119,"signed_in_time_utc":"2015-06-18 22:11:20","signed_in_time_local":"2015-06-18 15:11:20","signed_out_time_utc":"","signed_out_time_local":"","your_full_name":"Tony Stark","your_email_address":"[email protected]","your_child's_full_name":"","which_teacher_are_you_here_to_see?":"","nda_pdf_url":"","photo_url":"","Custom Fields":[{"Your Full Name":"Tony Stark"},{"Your Email Address":"[email protected]"}]}
status: sign_in
timestamp: 1434665483
signature: 158b30d24210c8cd20d8584102b3038e1bb743fb636802e35f40711569db196e
token: kROKtOVVR-l1iqzbFieiYQ

Create custom workflows that get triggered when a visitor signs in on the iPad. You can see the details on your Settings > Integrations and add a webhook for your custom integration.

A webhook makes Envoy servers perform an HTTP request to the specified URL whenever a new visitor signs into your office. Be sure to have a valid SSL certificate, all webhooks must use HTTPS. The request includes a POST with the following parameters:

Name Description
entry String (required) Details about the visitor.
status String (optional) Either sign_in or sign_out.
timestamp DateTime (optional) Returned in UTC as Unix time.
token String (optional) Random string.

A signature of the parameters (to ensure the request is actually coming from us). The signature is calculated as such: OpenSSL::HMAC.hexdigest (OpenSSL::Digest::Digest.new ('sha256'), api_key, '%s%s' % [timestamp, token])

A great way to test this and experiment is to use RequestBin (but only for testing!)

Note that we retry accessing your servers 5 times over the span of 10 minutes, after which the request will be dropped if unsuccessful.

If you need help with getting the webhook working, feel free to contact us.