# Runmerge API Overview

# Introduction

Runmerge provides a unified API for integrating with event management systems. It standardizes data across multiple platforms, enabling seamless retrieval of events, attendees, exhibitors, sessions, and more.

This document outlines the structure of the Runmerge API, including authentication, request parameters, pagination, and error handling.

# Base URL

All API requests should be made to:

https://api.runmerge.com/v1/

# Authentication

Runmerge uses API keys for authentication. Every request must include the following headers:

x-api-key: Your API key, used to authenticate requests.
x-integration-key: Identifies the integration and associates requests with a specific integration instance.

Requests without valid authentication headers will receive a 401 Unauthorized response.

{# For details on obtaining and managing API keys, refer to the Getting Started guide. #}

# Request Parameters

# General Query Parameters

The following parameters apply to all endpoints and help refine the data retrieved:

Parameter	Type	Required	Description
`tenantId`	`string`	No	The unique identifier for the tenant. If omitted, data for all accessible tenants is returned.
`cursor`	`string`	No	Used for pagination; represents the position of the last retrieved item.
`limit`	`string`	No	Specifies the number of records to fetch per request.
`sourceId`	`string`	No	Filters data by the originating source system.
`updatedAfter`	`string`	No	Returns only records updated after the provided timestamp (ISO 8601 format).
`sourceRawData`	`boolean`	No	If `true`, the response includes raw data from the source system.

# Relationship Filters

All entities in Runmerge support filtering by related objects. This allows retrieving data based on relationships with other entities.

Parameter	Type	Required	Description
`linkedEventId`	`string`	No	Filters results to only include records associated with the given event.
`linkedExhibitorId`	`string`	No	Filters results to only include records linked to this exhibitor.
`linkedPersonId`	`string`	No	Filters results by a specific person (attendee, speaker, etc.).
`linkedProductId`	`string`	No	Retrieves only records associated with a given product.
`linkedResourceId`	`string`	No	Filters results to records linked to a specific resource.
`linkedSessionId`	`string`	No	Returns only records linked to a specific session.
`linkedSponsorId`	`string`	No	Retrieves only records associated with a given sponsor.
`linkedTicketId`	`string`	No	Filters data to records associated with a particular ticket.

These filters enable precise queries when fetching data from the API.

# Entity-Specific Parameters

Some API endpoints accept additional parameters specific to the type of entity being queried.

# Events

The Events API supports filtering by event status:

Parameter	Type	Required	Description
`status`	`enum`	No	Filters events based on their current state. Accepted values: `Upcoming`, `Ongoing`, `Completed`, `Cancelled`, `Postponed`.

# People

The People API (attendees, speakers, etc.) includes an additional status filter:

Parameter	Type	Required	Description
`status`	`enum`	No	Filters people based on their current status. Accepted values: `Active`, `Inactive`.

# Pagination

Runmerge uses cursor-based pagination for handling large datasets efficiently.

# How Cursor-Based Pagination Works

The cursor parameter is used to fetch the next batch of records.
The limit parameter defines the number of records returned in a single request.
When paginating through results, each response includes a nextCursor field.
To retrieve the next page, pass nextCursor as the cursor in the next request.

# Error Handling

The API follows a consistent error response format. If a request is invalid or encounters an issue, the response will include an error object.

# Common Error Codes

Error Code	Description
`INVALID_PARAMETER`	The request contained an invalid or missing parameter.
`UNAUTHORIZED`	Authentication failed or missing API keys.
`FORBIDDEN`	The request is not permitted due to access restrictions.
`NOT_FOUND`	The requested resource was not found.
`INTERNAL_SERVER_ERROR`	An unexpected server error occurred.

# Handling Errors

Ensure that required parameters are provided in the correct format.
Verify API keys and permissions if receiving UNAUTHORIZED or FORBIDDEN errors.
Use the message field in the error response to debug issues.

This API Reference provides a structured guide to Runmerge’s API, covering authentication, request parameters, pagination, and error handling.