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.
  • Invitation tracking: Invitations can also carry a sourceId — your identifier for the guest. essentry uses it to match invitations within an event for creates and updates, similar to how event sourceId works. If you send the same invitation sourceId across multiple events, essentry recognizes them as the same person and keeps their contact details (name, email, company) in sync. If omitted, essentry falls back to matching by email and name.
  • 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 a sourceId (recommended — your identifier for this guest), 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": [
        {
          "sourceId": "guest-101",
          "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": [
        {
          "sourceId": "guest-101",
          "email": "external.advisor@consulting.com",
          "firstName": "Michael",
          "lastName": "Brown",
          "companyName": "Advisory Consulting"
        },
        {
          "sourceId": "guest-102",
          "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"
    }
  ]
}

​
Partial Update

Only the fields you include are updated — omitted fields remain unchanged. This applies to all fields, including invitations. The following example updates only the event title without affecting the time, location, host, or guest list: 
{
  "events": [
    {
      "sourceId": "meeting-456",
      "name": "Board Meeting Q2 Review - Rescheduled"
    }
  ]
}

​
Adding a Single Guest

By default, the invitations array is treated as the complete guest list — any existing guest not included is removed. To add a guest without resending the full list, set ?ignoreMissingInvitations=true: 
PUT /api/pre-processor/events?ignoreMissingInvitations=true

{
  "events": [
    {
      "sourceId": "meeting-456",
      "invitations": [
        {
          "sourceId": "guest-102",
          "email": "new.participant@partner.com",
          "firstName": "Lisa",
          "lastName": "Chen",
          "companyName": "Partner Corp"
        }
      ]
    }
  ]
}

​
Removing a Single Guest

To remove a specific guest without affecting others, set ?ignoreMissingInvitations=true and add deletedAt to that invitation. A cancellation email will be sent to the guest: 
PUT /api/pre-processor/events?ignoreMissingInvitations=true

{
  "events": [
    {
      "sourceId": "meeting-456",
      "invitations": [
        {
          "sourceId": "guest-101", // or match by email + name
          "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 within an event are matched by their sourceId (or by email and name if no sourceId is provided). If you omit the invitations array entirely, the guest list is not touched. If you include it, it is treated as the complete guest list — any existing guest not present in the array is removed from the event. Set ?ignoreMissingInvitations=true to change this: omitted guests are preserved, and you can remove individual guests by setting deletedAt on their invitation. See the examples above.

​
What’s the difference between event and invitation sourceId?

Both use the same field name but serve different purposes:
  • Event sourceId: Must be globally unique within your integration. Identifies the event for create, update, and delete operations.
  • Invitation sourceId: Must be unique within an event. Identifies the guest. The same value can (and should) appear across multiple events when the same person is invited — essentry recognizes them as the same contact and keeps their details (name, email, company) in sync.
If omitted on an invitation, essentry falls back to matching by email and name.

​
What if I don’t want contact updates to affect other events?

When you use the same invitation sourceId across events, essentry treats them as one contact — updating their name or email in one event updates it everywhere. If you need fully independent invitations, build a composite sourceId that includes the event identifier, e.g. "meeting-456-guest-101". This way each invitation is treated as a separate guest even if the underlying person is the same.

​
Can I use the invitation sourceId with the post-processor API?

Yes. When a guest checks in, the post-processor API includes the invitation sourceId so you can correlate the check-in back to your system. This also works with custom QR codes: guests can scan codes containing the sourceId value instead of using essentry’s built-in QR codes.

​
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.