Invitebase | Referrers

This reference is generated from the Invitebase OpenAPI contract.

End-users of the customer's app who refer others.

Create or identify a referrer

POST/v1/referrers

Idempotent on external_id within an org+mode — call it whenever a user could become a referrer. Accepts publishable or secret keys.

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/ReferrerCreate"
}

Responses

200

Referrer created or updated.

application/json schema:

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

400

The request was malformed or invalid.

application/json schema:

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

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"
}

List referrers

GET/v1/referrers

Parameters

Name	In	Required	Schema	Description
`limit`	query	No	{"type":"integer","minimum":1,"maximum":100,"default":25}
`starting_after`	query	No	{"type":"string"}	A cursor (object id) for pagination; returns the page after this object.

Responses

200

A paginated list of referrers.

application/json schema:

{
  "allOf": [
    {
      "$ref": "#/components/schemas/ListResponse"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Referrer"
          }
        }
      }
    }
  ]
}

400

The request was malformed or invalid.

application/json schema:

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

401

Missing or invalid API key.

application/json schema:

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

403

The API key is valid but is not permitted to call this endpoint.

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"
}

Retrieve a referrer

GET/v1/referrers/{referrerId}

Parameters

Name	In	Required	Schema	Description
`referrerId`	path	Yes	{"type":"string"}

Responses

200

The referrer.

application/json schema:

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

401

Missing or invalid API key.

application/json schema:

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

403

The API key is valid but is not permitted to call this endpoint.

application/json schema:

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

404

The requested resource does not exist.

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"
}

Register a referrer's payout destination for deduplication

POST/v1/referrers/{referrerId}/payout-destinations

Trusted-server only. Send the actual PayPal email or Venmo handle only from your backend; Invitebase normalizes and HMACs it, then discards it. For bank, send the payout provider's opaque fingerprint — never an account or card number. The response contains neither the identifier nor its hash. V1 compares only referrer accounts within this app and mode.

Authentication

Authorization: Bearer <secret key>.

Parameters

Name	In	Required	Schema	Description
`referrerId`	path	Yes	{"type":"string"}

Request body

Required.

application/json schema:

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

Responses

200

Destination replaced or registered; only a safe dedup summary is returned.

application/json schema:

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

400

The request was malformed or invalid.

application/json schema:

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

401

Missing or invalid API key.

application/json schema:

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

403

The API key is valid but is not permitted to call this endpoint.

application/json schema:

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

404

The requested resource does not exist.

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 ReferrerCreate object

Field	Type	Required	Description
`external_id`	string	Yes	The customer's stable id for this user.
`email`	string	No
`name`	string	No
`properties`	object	No	Optional user attributes. A consented web integration may explicitly send a browser identifier as `device_id`, `deviceId`, `visitor_id`, or `fingerprint_visitor_id`; Invitebase never derives one in an SDK. A trusted backend may also send an opaque payment fingerprint as `payment_fingerprint`, `paymentFingerprint`, `card_fingerprint`, or `cardFingerprint`. Native SDKs must not collect or send browser or device fingerprints.

Full schema:

{
  "type": "object",
  "required": [
    "external_id"
  ],
  "properties": {
    "external_id": {
      "type": "string",
      "description": "The customer's stable id for this user."
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "name": {
      "type": "string"
    },
    "properties": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional user attributes. A consented web integration may explicitly send a browser identifier as `device_id`, `deviceId`, `visitor_id`, or `fingerprint_visitor_id`; Invitebase never derives one in an SDK. A trusted backend may also send an opaque payment fingerprint as `payment_fingerprint`, `paymentFingerprint`, `card_fingerprint`, or `cardFingerprint`. Native SDKs must not collect or send browser or device fingerprints.\n"
    }
  }
}

The Referrer object

Field	Type	Required	Description
`external_id`	string	Yes	The customer's stable id for this user.
`email`	string	No
`name`	string	No
`properties`	object	No	Optional user attributes. A consented web integration may explicitly send a browser identifier as `device_id`, `deviceId`, `visitor_id`, or `fingerprint_visitor_id`; Invitebase never derives one in an SDK. A trusted backend may also send an opaque payment fingerprint as `payment_fingerprint`, `paymentFingerprint`, `card_fingerprint`, or `cardFingerprint`. Native SDKs must not collect or send browser or device fingerprints.
`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
`referral_propensity_score`	number	No	AI-predicted propensity (0–100) that this user will refer (super-referrer targeting).
`created_at`	string	Yes

Full schema:

{
  "allOf": [
    {
      "$ref": "#/components/schemas/ReferrerCreate"
    },
    {
      "type": "object",
      "required": [
        "id",
        "object",
        "livemode",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "example": "ref_123"
        },
        "object": {
          "type": "string",
          "const": "referrer"
        },
        "mode": {
          "$ref": "#/components/schemas/Mode"
        },
        "livemode": {
          "type": "boolean"
        },
        "referral_propensity_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "AI-predicted propensity (0–100) that this user will refer (super-referrer targeting)."
        },
        "created_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"
        }
      }
    }
  }
}

The ListResponse object

Field	Type	Required
`object`	string	Yes
`has_more`	boolean	Yes
`data`	array	Yes

Full schema:

{
  "type": "object",
  "required": [
    "object",
    "data",
    "has_more"
  ],
  "properties": {
    "object": {
      "type": "string",
      "const": "list"
    },
    "has_more": {
      "type": "boolean"
    },
    "data": {
      "type": "array",
      "items": {}
    }
  }
}

The PayoutDestinationCreate object

Field	Type	Required	Description
`kind`	string	Yes	`bank` accepts only the payout provider's opaque fingerprint, not a bank-account or card number.
`identifier`	string	Yes	A PayPal email, Venmo handle, or provider fingerprint. Transient: Invitebase HMACs it and does not store or return the original value.

Full schema:

{
  "type": "object",
  "required": [
    "kind",
    "identifier"
  ],
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "paypal",
        "venmo",
        "bank"
      ],
      "description": "`bank` accepts only the payout provider's opaque fingerprint, not a bank-account or card number.\n"
    },
    "identifier": {
      "type": "string",
      "maxLength": 512,
      "description": "A PayPal email, Venmo handle, or provider fingerprint. Transient: Invitebase HMACs it and does not store or return the original value.\n"
    }
  }
}

The PayoutDestination object

Field	Type	Required	Description
`object`	string	Yes
`referrer_id`	string	Yes
`kind`	string	Yes
`shared_referrer_count`	integer	Yes	Number of referrer accounts in this app and mode sharing this destination.
`threshold`	integer	Yes
`exceeds_threshold`	boolean	Yes
`livemode`	boolean	Yes

Full schema:

{
  "type": "object",
  "required": [
    "object",
    "referrer_id",
    "kind",
    "shared_referrer_count",
    "threshold",
    "exceeds_threshold",
    "livemode"
  ],
  "properties": {
    "object": {
      "type": "string",
      "const": "payout_destination"
    },
    "referrer_id": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "paypal",
        "venmo",
        "bank"
      ]
    },
    "shared_referrer_count": {
      "type": "integer",
      "description": "Number of referrer accounts in this app and mode sharing this destination."
    },
    "threshold": {
      "type": "integer",
      "minimum": 2
    },
    "exceeds_threshold": {
      "type": "boolean"
    },
    "livemode": {
      "type": "boolean"
    }
  }
}

What's next

Referral links

Create unique, attributable share links and codes.

Referrals

Individual referral attempts and their lifecycle state.

Rewards

What's owed once a referral validates, and its fulfillment.

Balance

Your prefunded reward balance and top-ups.

Referrers

On this page