Skip to main content

​
When to Use the Synchronization API

The Synchronization API is designed for systems that maintain their own event database and need to keep essentry synchronized with their current state. Use this API when:
  • Integrating with proprietary calendar systems not supported out of the box.
  • Supporting existing visitor management systems while migrating to essentry.
  • Synchronizing with custom employee portals where guests can be invited.

​
How Synchronization Works

The Synchronization API operates on a state-based model:
  1. Send current state: Submit events as they currently exist in your system (can be all events or a subset).
  2. Automatic reconciliation: essentry determines which events to create or update.
  3. Source ID tracking: Events are matched using your system’s unique identifiers (sourceId).
Unlike traditional API integrations, you don’t need to store essentry’s internal IDs in your database. Instead:
  • Use your existing IDs: Send your system’s unique identifiers as sourceId.
  • essentry stores the mapping: We maintain the relationship between your IDs and our internal IDs.
  • Automatic operation detection: essentry uses the sourceId you provide to determine the correct action automatically:
    • Create: If the sourceId has never been seen by essentry before, a new event is created.
    • Update: If the sourceId matches an existing event, that event is updated with the new data you provide.
    • Delete: If you provide an existing sourceId along with the deletedAt field, the event is deleted.
  • Automatic host creation: Hosts become employees in essentry.
  • Subset synchronization: Events not included in a sync are left unchanged.
This approach keeps your existing data structure unchanged while enabling full synchronization capabilities.

​
Implementation Steps

​
Step 1: Authentication

Obtain an integration token from the essentry dashboard and include it in the Authorization header. For detailed authentication information, see the Authentication guide.

​
Step 2: Find Required IDs

Even though essentry remembers the IDs of your events, you still need to know the IDs of locations, entrances, and custom fields to reference them in your API calls.

​
Location IDs

Go to https://app.essentry.com/settings/company/locations and click on the location you want to use. The location ID appears in the browser URL (e.g., if the URL is https://app.essentry.com/settings/locations/123/general, the location ID is 123).

​
Entrance IDs

From the location settings page, click Entrances in the left navigation, then click on the specific entrance. The entrance ID appears in the URL (e.g., https://app.essentry.com/settings/locations/123/entrances/456 means the entrance ID is 456).

​
Custom Field IDs

Go to https://app.essentry.com/settings/company/custom-fields and click on the custom field you want to use. The custom field ID appears in the URL (e.g., https://app.essentry.com/settings/company/custom-fields/789 means the ID is 789).

​
Step 3: Map Your Data

Understanding how your system’s data maps to essentry’s event model is crucial for successful integration.

​
essentry Event Model

In essentry, an event represents a scheduled appointment or meeting with the following components:
  • Start and end datetime
  • Location where the event takes place
  • Host (the person organizing/responsible for the event)
  • Title/name of the event
  • One or more guests to be invited (called “invitations”)
You might refer to these concepts differently in your system - for example, your “access requests” or “appointments” map to our “events”, and your “visitors” or “guests” become “invitations” in essentry.

​
Data Mapping Requirements

Map your system’s data to these required essentry fields:
  • Event identification (sourceId): Your unique identifier for each event. Must be unique within your integration.
  • Start and end times: Convert to ISO 8601 format with timezone.
  • Location: Map to essentry location IDs.
  • Host information: Email address (required) to identify the employee. We create the employee if they don’t exist, or update their name and phone number if they do. Each email represents a unique employee in essentry.
  • Guest details: For each guest, provide email, name, and company information.
If your system naturally groups multiple guests under one event (like a meeting with several attendees), send one event with multiple invitations. If your system treats each guest separately, you can create individual events for each guest - both approaches work with essentry.

​
Step 4: Implement Synchronization

Build the synchronization logic to transform your events into the required format and submit them via the API. See the Synchronize Events and Invitations endpoint for detailed specifications.

​
Step 5: Handle Responses

Process the response to identify successful operations and handle any errors. See the Responses and Error Handling section below for details.

​
Integration Examples

​
Creating a New Event

When you want to create a new event in essentry, include a unique sourceId that has not yet been shared with essentry. Here’s an example of creating a board meeting with one external visitor: 
{
  "events": [
    {
      "sourceId": "meeting-456",
      "name": "Board Meeting Q2 Review",
      "startsAt": "2025-07-15T14:00:00+02:00",
      "endsAt": "2025-07-15T16:00:00+02:00",
      "locationId": 42,
      "host": {
        "email": "sarah.jones@company.com",
        "firstName": "Sarah",
        "lastName": "Jones"
      },
      "invitations": [
        {
          "email": "external.advisor@consulting.com",
          "firstName": "Michael",
          "lastName": "Brown",
          "companyName": "Advisory Consulting"
        }
      ]
    }
  ]
}

​
Updating an Existing Event

To update an event, send the same sourceId with the changes. Apart from required fields, you only need to include the fields that you want to update: 
{
  "events": [
    {
      "sourceId": "meeting-456",
      "name": "Board Meeting Q2 Review - Extended",
      "startsAt": "2025-07-15T14:00:00+02:00",
      "endsAt": "2025-07-15T17:00:00+02:00",
      "invitations": [
        {
          "email": "external.advisor@consulting.com",
          "firstName": "Michael",
          "lastName": "Brown",
          "companyName": "Advisory Consulting"
        },
        {
          "email": "new.participant@partner.com",
          "firstName": "Lisa",
          "lastName": "Chen",
          "companyName": "Partner Corp"
        }
      ]
    }
  ]
}

​
Deleting an Event

To delete an event, include the sourceId and add a deletion marker. The event will be cancelled and cancellation emails will be sent to all invited guests: 
{
  "events": [
    {
      "sourceId": "meeting-456",
      "deletedAt": "2025-07-10T09:00:00Z"
    }
  ]
}

​
Responses and Error Handling

The API is designed to handle errors as gracefully as possible. When processing multiple events from your source system, one bad event should not lead to a failed synchronization.

​
Response Structure

First, check the HTTP status code:
  • 200 OK: The request was processed successfully. Individual event results are returned in an array with one element for each event sent.
  • Non-200 status: The entire request was rejected due to fundamental errors (wrong JSON syntax, incorrectly formatted ISO dates, etc.).

​
Individual Event Status

For successful requests (200 OK), each event in the response has one of these statuses:
  • SUCCESS: Event was processed successfully
  • Specific error codes for issues the client cannot prevent (e.g., ERROR_USER_CANNOT_HOST_AT_LOCATION if the host exists but lacks permissions)
For detailed error code specifications, see the Synchronize Events and Invitations endpoint.

​
FAQ

​
Do I have to send all fields during update?

To update an event, send the same sourceId with the changes. A best practice is to include all fields if you can, as you might not know if we have seen the event before. However, apart from the sourceId, you only need to include the fields that you want to update. If the event doesn’t exist yet and you omitted some required fields, an error will be returned. Invitations must always be complete since they don’t have individual deletion markers - any invitation not included will be removed from the event. Use the ignoreMissingInvitations query flag if you want to preserve existing invitations that you don’t include in your update.

​
What happens when I set the same custom field on both the event and invitation?

When you set the same custom field with different values on both the event and individual invitations, the invitation value takes precedence for that specific guest. This allows you to:
  • Set default values at the event level that apply to all guests
  • Override those defaults for specific guests at the invitation level
Best practices for custom field placement:
  • Event-level custom fields: Use for information that applies to all guests, such as “event type”, “security clearance required”, or “parking instructions”.
  • Invitation-level custom fields: Use for guest-specific information, such as “license plate number”, “dietary restrictions”, or “VIP status”.
This hierarchical approach gives you flexibility while maintaining clean data organization.

​
Important: Invitation sourceId (Advanced Use Case)

⚠️ Warning: Don’t confuse this with the event sourceId discussed throughout this guide. Each invitation can optionally have its own sourceId field. Most customers don’t need this field and can ignore it completely.

​
When You Might Need Invitation sourceIds

You only need to set invitation sourceId if:
  • Post-processor integration: You’re also integrating the post-processor API and need to know “this guest who just checked in corresponds to which guest in my system?”.
  • Custom QR codes: You want guests to scan QR codes that you generate (containing your guest ID) instead of using essentry’s built-in QR codes.

​
How It Works

  • Set invitation.sourceId to your system’s identifier for that guest (not necessarily unique across all events).
  • When a guest checks in, the post-processor API will include this sourceId so you can identify which guest in your system checked in.
  • If you generate custom QR codes, guests can scan codes containing this sourceId value.
Note: Most customers use essentry’s built-in QR codes and don’t need this functionality.