Skip to main content

FAQ

How do I get an API key?​

Create an API key from the RemyPass integrations API screen. The key is shown once when it is created.

Where should I send API requests?​

Use your RemyPass backend URL with the public API base path:

https://api.remypass.com/api/v1/public

What authentication type is supported?​

API key authentication in the X-API-Key header.

Are write methods supported?​

Yes. The public API supports selected write operations for members, passes, pass expiry, pass emails, and event tickets when the key has the required permission.

Which IDs should I use?​

Use the database _id values returned by the API when an endpoint asks for an id.

  • Member id: Returned by member endpoints as _id.
  • memberId: Your organisation's external member identifier. This is not the same as the member _id.
  • passTemplateId: Returned by GET /pass-templates.
  • Pass instance id: Returned by pass instance endpoints as _id.

What happens when I create a member with issuePass set to true?​

The member is created first. If issuePass is true, provide passTemplateId; you can also provide expiryDate for the issued pass.

The response includes pass issuance information, including whether a pass was issued. If pass issuance fails after the member is created, the member remains created and the failure is recorded on the member activity log.

Which permissions do I need?​

Common permission mappings:

  • members:read: List and view members.
  • members:write: Create and update members.
  • passes:read: List and view issued pass instances.
  • passes:issue: Issue passes and event tickets.
  • passes:revoke: Revoke issued passes.
  • passes:reinstate: Reinstate inactive passes.
  • passes:update_expiry: Update or remove pass expiry dates.
  • passes:send_email: Send pass delivery emails.
  • pass_templates:read: List and view pass templates.

Permission checks are enforced per endpoint.

How does pagination work?​

List endpoints use page and limit query parameters.

  • page defaults to 1.
  • limit defaults to 10.
  • limit can be up to 100.

Paginated responses include a pagination object with currentPage, totalPages, totalItems, itemsPerPage, hasNextPage, and hasPrevPage.

How do custom fields work?​

Custom fields are organisation-defined key/value fields on members and issued passes. Keys should match the custom field keys configured for your organisation.

For event ticket pass designs, custom dynamic fields use the custom_ prefix in the template but not in API payloads. For example, a design field configured as custom_guardianSpaces is populated with customFields.guardianSpaces when calling POST /passes/issue.

Event ticket built-in fields do not go in customFields: use eventName, eventTime, and seatInfo for event name, date/time, gate, section, row, and seat. eventTime is optional only when the selected template is configured as redeemable any time. seatInfo requirements follow the selected template: visible section, row, and seat fields are required; hidden seat fields can be omitted; gate is optional for backwards compatibility. Row and seat should be sent separately as seatInfo.row and seatInfo.seat; Google Wallet may display them together as Row / Seat. Pass templates can also use company_name as a dynamic field for the company name, including the Google Wallet venue name.

Example:

{
  "customFields": {
    "membershipLevel": "Gold",
    "favoriteLocation": "Main Street",
    "newsletterOptIn": true
  }
}

What pass statuses are supported?​

Passes can have one of four statuses:

  • active: Pass is currently active and can be used.
  • inactive: Pass is temporarily suspended and can be reinstated.
  • expired: Pass has passed its expiry date. Update the expiry date to reactivate it.
  • void: Pass is permanently revoked and cannot be reinstated.

Status transitions:

  • Between active and inactive: Via toggle or reinstate endpoints.
  • From active to expired: Automatic when the expiry date passes.
  • From expired to active: Via the update expiry endpoint with a future date.
  • From any status to void: Via the revoke endpoint. This is permanent and irreversible.

Can revoked passes be restored?​

No. Revoked passes have void status and cannot be reinstated. Use inactive for temporary suspension.

What date formats are supported?​

All date fields must be in ISO 8601 format.

Examples:

  • "2024-12-31T23:59:59.000Z": Full timestamp with timezone.
  • "2024-12-31T23:59:59Z": Timestamp without milliseconds.
  • "2024-12-31": Date only, interpreted as midnight UTC.

When date fields are provided, they must use a valid ISO 8601 format.

How should I handle validation errors?​

Validation errors return HTTP 400 with success: false, a message, and sometimes an errors array with field-level details.

How should I handle rate limits?​

Handle HTTP 429 using retry with exponential backoff and jitter.