> ## Documentation Index > Fetch the complete documentation index at: https://docs.norbelys.com/llms.txt > Use this file to discover all available pages before exploring further. # List an integration's available events > The events this app can notify Norbelys about, with the config each one takes. Pass a `slug` from here when creating a trigger. ## OpenAPI ````yaml /openapi.json get /integrations/{id}/events openapi: 3.1.1 info: description: >- The **Norbelys API** is a single, predictable REST surface for cold email and outreach — people, senders, programs, and sending all live behind the five patterns below. Developer-first and AI-first: every name is either already invented (Schema.org) or obvious. ## Authentication Every request authenticates with an **org-scoped API key**. Create one in **Settings → API keys** and send it as a bearer token: ```http GET https://api.norbelys.com/v1/people Authorization: Bearer ak_live_… ``` Interactive agents may instead use OAuth 2.1 (see `/auth.md` and the `/.well-known/oauth-protected-resource` metadata). ## Conventions - **Base URL** — `https://api.norbelys.com/v1`. - **JSON in, JSON out.** Timestamps are ISO-8601 in UTC. - **Cursor pagination.** List endpoints take `limit` + `cursor` and return `{ data, hasMore, nextCursor }` (offset-paged tables add `page` + `total`). - **Expansions.** Detail GETs take an `expand[]` query param to inline related data (e.g. `GET /people/{id}?expand[]=timeline`) instead of extra calls. - **Soft deletes.** Anything that has been used is archived, never hard-deleted — `DELETE` archives the resource and returns it. ## Errors Failures return the same envelope on every 4xx/5xx, with the matching HTTP status: ```json { "error": { "type": "invalid_request", "code": "invalid_param", "message": "…", "hint": "…", "doc_url": "…" } } ``` `type` is a broad, machine-routable category derived from the status; `code` is the stable machine contract you branch on (never the human `message`). See the `ApiError` schema. ## Idempotency Every `POST` accepts an optional **`Idempotency-Key`** header. Reuse the same key to replay the original result for 24h instead of re-executing — so a retried create can never double-charge or duplicate a record. ## Rate limits & versioning Abuse control is enforced at the edge; responses advertise the policy via the `RateLimit-Policy` header, and a `429` carries `Retry-After`. The API is versioned in the URL path (`/v1`). Breaking changes ship under a new version; a retiring surface is announced with `Deprecation` + `Sunset` response headers at least 90 days ahead. title: Norbelys API version: 0.0.1 x-api-lifecycle: currentVersion: v1 deprecationPolicyUrl: https://docs.norbelys.com/conventions#versioning deprecationSignals: - Deprecation header - Sunset header minNoticeDays: 90 versioning: url-path servers: - description: Production url: https://api.norbelys.com/v1 security: - bearerAuth: [] tags: - description: Your workspace — profile and onboarding state. name: Organization - description: >- The people you reach out to: create, import, segment, and read a person's timeline. name: People - description: >- Custom person fields — the tenant-defined attributes that ride on every person under `customFields`. name: Fields - description: >- Static lists of people — hand-curated audiences you add to and remove from. name: Groups - description: >- Saved audience filters — dynamic rule-trees evaluated live against your people. name: Segments - description: >- Connected mailboxes that send your email — the sending identity behind each program. name: Senders - description: >- Every domain concern in one place: sending domains (verification, DNS records, daily caps) and DMARC monitoring (collection addresses, ingested reports). name: Domains - description: >- Campaigns and sequences — with their steps, variants and enrollments nested underneath. name: Programs - description: >- Send email through the unified send door, read the unified sent/received log, and fetch a message's exact sent source. name: Messages - description: >- The one analytics door: named catalog queries (funnels, feeds, health, A/B, DMARC) over the event store. name: Analytics - description: Addresses excluded from sending — unsubscribes, bounces, and complaints. name: Suppressions - description: >- Connected tools (Slack, CRMs): mint a Connect session, configure notifications, disconnect. name: Integrations - description: >- Synchronous email verification — deliverability, reachability, and identity signals for an address. name: Verify - name: Files paths: /integrations/{id}/events: get: tags: - Integrations summary: List an integration's available events description: >- The events this app can notify Norbelys about, with the config each one takes. Pass a `slug` from here when creating a trigger. operationId: integrations.events parameters: - name: id in: path required: true schema: type: string description: The resource id (path). responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationEventList' '400': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: The request was malformed or failed validation. '401': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Missing or invalid credentials. '403': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Authenticated, but not permitted. '404': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: No such resource (or it has been archived). '409': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: The request conflicts with the resource's current state. '422': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Well-formed but semantically invalid. '429': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: Rate limit exceeded — retry after the `Retry-After` interval. '500': content: application/json: schema: $ref: '#/components/schemas/ApiError' description: An unexpected error on our side. x-codeSamples: - label: TypeScript / JavaScript lang: typescript source: >- import { createClient } from "@norbelys/sdk"; const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY }); const { data, error } = await norbelys.integrations.events("int_9k4m2p"); if (error) { throw new Error(error.error.message); } console.log(data); - label: Python lang: python source: >- import norbelys config = norbelys.Configuration(host="https://api.norbelys.com/v1", access_token="ak_live_…") with norbelys.ApiClient(config) as client: api = norbelys.IntegrationsApi(client) result = api.integrations_events("int_9k4m2p") print(result) - label: Go lang: go source: >- cfg := norbelys.NewConfiguration() cfg.Servers = norbelys.ServerConfigurations{{URL: "https://api.norbelys.com/v1"}} client := norbelys.NewAPIClient(cfg) ctx := context.WithValue(context.Background(), norbelys.ContextAccessToken, "ak_live_…") result, _, err := client.IntegrationsAPI.IntegrationsEvents(ctx, "int_9k4m2p").Execute() - label: Ruby lang: ruby source: |- require "norbelys" Norbelys.configure { |c| c.access_token = ENV["NORBELYS_API_KEY"] } api = Norbelys::IntegrationsApi.new result = api.integrations_events("int_9k4m2p") puts result - label: CLI lang: bash source: norbelys integrations events int_9k4m2p - label: curl lang: bash source: |- curl -X GET "https://api.norbelys.com/v1/integrations/{id}/events" \ -H "Authorization: Bearer $NORBELYS_API_KEY" components: schemas: IntegrationEventList: type: object properties: events: type: array items: $ref: '#/components/schemas/IntegrationEvent' description: The events this app can notify Norbelys about. required: - events title: IntegrationEventList ApiError: properties: error: properties: code: description: >- Stable machine code — branch on this, never on the human `message`. enum: - invalid_param - missing_param - invalid_expand - duplicate_email - already_exists - unauthorized - forbidden - mailbox_already_connected - suppression_protected - program_not_launchable - database_unavailable - rate_limited - idempotency_key_reuse - idempotency_in_progress type: string doc_url: description: Optional link to the relevant documentation. format: uri type: string hint: description: Optional one-sentence remediation. type: string message: description: Human-readable explanation. Never a contract. type: string type: description: Broad, machine-routable category derived from the HTTP status. examples: - invalid_request - authentication_error - rate_limit type: string required: - type - code - message title: ApiErrorDetail type: object required: - error title: ApiError type: object IntegrationEvent: type: object properties: configSchema: type: object propertyNames: type: string additionalProperties: {} description: JSON Schema for the `config` this event accepts. description: anyOf: - type: string - type: 'null' description: What fires this event, or null. name: type: string description: The event's display name. examples: - New contact object: const: integration_event default: integration_event description: Always "integration_event". slug: type: string description: The event slug — pass it as `event` when creating a trigger. examples: - HUBSPOT_NEW_CONTACT required: - configSchema - description - name - slug title: IntegrationEvent securitySchemes: bearerAuth: description: >- Org-scoped Norbelys API key. Create one in Settings → API keys and send it as `Authorization: Bearer ak_…`. scheme: bearer type: http ````