Invitebase | Events

This reference is generated from the Invitebase OpenAPI contract.

Ingest events that drive referral qualification.

Ingest an event

POST/v1/events

Records an event for a referred user. Events are the raw material the referral-definition engine evaluates gates against. Accepts publishable (client SDK) or secret (server) keys. Idempotent.

Authentication

Authorization: Bearer <secret key> or X-Publishable-Key header.

Parameters

Name	In	Required	Schema	Description
`Idempotency-Key`	header	No	{"type":"string"}	A unique key for one logical mutation. The same key and request replay the original result for 24 hours; using the key with a different request returns 409.

Request body

Required.

application/json schema:

{
  "$ref": "#/components/schemas/EventCreate"
}

Responses

202

Event accepted for processing.

application/json schema:

{
  "$ref": "#/components/schemas/Event"
}

The request was malformed or invalid. Before an event attributes a referral, the referrer, the referred user ID, and any email or device ID in properties are checked against the app's block list and the central disposable-email list. A match is refused with code blocked_identifier (param referral_code): nothing is attributed and the attempt is recorded. The response does not say which identifier matched.

application/json schema:

{
  "$ref": "#/components/schemas/Error"
}

blocked_identifier:

{
  "error": {
    "type": "invalid_request_error",
    "code": "blocked_identifier",
    "message": "This referral involves a blocked identifier.",
    "param": "referral_code",
    "doc_url": "https://docs.invitebase.com/implementation/platform/errors#blocked_identifier"
  }
}

401

Missing or invalid API key.

application/json schema:

{
  "$ref": "#/components/schemas/Error"
}

429

Too many requests.

Response headers:

{
  "Retry-After": {
    "description": "Seconds until the caller may retry.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  }
}

application/json schema:

{
  "$ref": "#/components/schemas/Error"
}

Schemas

Schema references below resolve against these definitions. Required fields, enums, bounds, and composed types are preserved from the contract.

The EventCreate object

Field	Type	Required	Description
`name`	string	Yes	Event name, e.g. "signup", "subscription_started", "completed_onboarding".
`referred_user_id`	string	Yes	The customer's id for the referred end-user this event belongs to.
`referral_code`	string	No	The referral code/link the user came in through (for attribution), if known. It must identify an active link for the authenticated app and mode and must have a prior clicked referral. The first valid code claims attribution for a referred user within a campaign; retries of that same code are idempotent.
`properties`	object	No	Arbitrary properties gates can match on (e.g. plan = paid). When claiming a `referral_code`, also send the referred user's known `email` (or `email_address` / `user_email`). A web integration may additionally provide a consented browser identifier or an opaque payment fingerprint using the conventions on `ReferrerCreate`. Invitebase rejects a match against the referrer's identifiers before attribution; Gmail plus-addressing and dots are normalized. Invitebase does not derive browser or device fingerprints in an SDK.
`timestamp`	string	No
`idempotency_key`	string	No	Optional dedup key in the body (in addition to the header).

Full schema:

{
  "type": "object",
  "required": [
    "name",
    "referred_user_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Event name, e.g. \"signup\", \"subscription_started\", \"completed_onboarding\".",
      "example": "subscription_started"
    },
    "referred_user_id": {
      "type": "string",
      "description": "The customer's id for the referred end-user this event belongs to."
    },
    "referral_code": {
      "type": "string",
      "description": "The referral code/link the user came in through (for attribution), if known. It must identify an active link for the authenticated app and mode and must have a prior clicked referral. The first valid code claims attribution for a referred user within a campaign; retries of that same code are idempotent.\n"
    },
    "properties": {
      "type": "object",
      "additionalProperties": true,
      "description": "Arbitrary properties gates can match on (e.g. plan = paid). When claiming a `referral_code`, also send the referred user's known `email` (or `email_address` / `user_email`). A web integration may additionally provide a consented browser identifier or an opaque payment fingerprint using the conventions on `ReferrerCreate`. Invitebase rejects a match against the referrer's identifiers before attribution; Gmail plus-addressing and dots are normalized. Invitebase does not derive browser or device fingerprints in an SDK.\n"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional dedup key in the body (in addition to the header)."
    }
  }
}

The Event object

Field	Type	Required	Description
`name`	string	Yes	Event name, e.g. "signup", "subscription_started", "completed_onboarding".
`referred_user_id`	string	Yes	The customer's id for the referred end-user this event belongs to.
`referral_code`	string	No	The referral code/link the user came in through (for attribution), if known. It must identify an active link for the authenticated app and mode and must have a prior clicked referral. The first valid code claims attribution for a referred user within a campaign; retries of that same code are idempotent.
`properties`	object	No	Arbitrary properties gates can match on (e.g. plan = paid). When claiming a `referral_code`, also send the referred user's known `email` (or `email_address` / `user_email`). A web integration may additionally provide a consented browser identifier or an opaque payment fingerprint using the conventions on `ReferrerCreate`. Invitebase rejects a match against the referrer's identifiers before attribution; Gmail plus-addressing and dots are normalized. Invitebase does not derive browser or device fingerprints in an SDK.
`timestamp`	string	No
`idempotency_key`	string	No	Optional dedup key in the body (in addition to the header).
`id`	string	Yes
`object`	string	Yes
`mode`	Mode	No	Whether the object exists in test or live mode (determined by the API key).
`livemode`	boolean	Yes
`source`	string	No	Where the event came from.
`received_at`	string	Yes

Full schema:

{
  "allOf": [
    {
      "$ref": "#/components/schemas/EventCreate"
    },
    {
      "type": "object",
      "required": [
        "id",
        "object",
        "livemode",
        "received_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "example": "evt_123"
        },
        "object": {
          "type": "string",
          "const": "event"
        },
        "mode": {
          "$ref": "#/components/schemas/Mode"
        },
        "livemode": {
          "type": "boolean"
        },
        "source": {
          "type": "string",
          "enum": [
            "sdk",
            "api",
            "revenuecat",
            "adapty",
            "stripe",
            "segment"
          ],
          "description": "Where the event came from."
        },
        "received_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  ]
}

The Mode object

Whether the object exists in test or live mode (determined by the API key).

Full schema:

{
  "type": "string",
  "enum": [
    "test",
    "live"
  ],
  "description": "Whether the object exists in test or live mode (determined by the API key)."
}

The Error object

Field	Type	Required	Description
`error`	object	Yes

Full schema:

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "type",
        "code",
        "message",
        "doc_url"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "invalid_request_error",
            "authentication_error",
            "rate_limit_error",
            "api_error"
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "param": {
          "type": "string"
        },
        "doc_url": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}