Skip to main content
Fidel API logo
  • Category: developer tools
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 39
  • Triggers: 0
  • Slug: FIDEL_API
  • Version: 20261101_00

Tools

Slug: FIDEL_API_CREATE_BRANDCreate a new brand in Fidel API. Use this action to register a brand with a unique name. Brands are independent of Programs and can be reused between different programs. Once created, the brand can be associated with locations and offers. Returns the created brand object with its unique ID and timestamps.

Input Parameters

string
required
The brand name. Must be unique within your account and between 2-50 characters.
string
URL to the brand’s logo image. Supported formats: GIF, JPG, JPEG, PNG.
object
Custom key-value pairs for storing additional brand data. Max size: 2KB.
string
URL to the brand’s website.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_CREATE_BRAND_WEBHOOKTool to create a webhook at the brand level for receiving real-time event notifications. Use when you need to be notified of brand-related events, such as when brand consent is approved. In test mode, the webhook triggers immediately after creating a brand; in live mode, it triggers when the brand user approves the consent request.

Input Parameters

string
required
HTTPS URL where webhook notifications will be sent. Must be a valid HTTPS endpoint that can receive POST requests.
string
required
Event type to receive notifications for. For brand webhooks, use ‘brand.consent’ to receive notifications when brand consent is approved.
object
Optional custom headers (max 5) to include in webhook requests. Useful for adding authentication tokens or custom identifiers.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_CREATE_LOCATIONCreate a new location for a program in Fidel API. Use when you need to add a physical store or merchant location to track card transactions at that specific address.

Input Parameters

string
required
City name where the location is situated.
string
required
Street address of the location.
string
required
UUID of the brand to associate with this location. Obtain brand IDs from the List Brands action.
string
required
Postal or ZIP code of the location.
object
Merchant IDs for card schemes.
string
required
UUID of the program to create the location in. Obtain program IDs from the List Programs action.
string
Required for US locations (countryCode=‘USA’). Two-letter state code (e.g., ‘CA’ for California, ‘NY’ for New York).
string
required
Three-letter ISO 3166-1 alpha-3 country code (e.g., ‘GBR’ for United Kingdom, ‘USA’ for United States).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_CREATE_MID_REQUESTTool to create a new MID (Merchant ID) request for a specific program and location. Use when you need to onboard a new MID or reassign an existing MID to a location.

Input Parameters

string
Visa MID alternative field. Required when scheme is ‘visa’. Either this or visaAcquiringMid must be provided for Visa.
string ("onboard" | "reassign")
required
Action type for the MID request. ‘onboard’ adds a new MID, ‘reassign’ moves an existing MID to a new location.
string ("missing-transaction-lookup" | "manual-mid-lookup" | "brand-provided-mid" | "processor-provided-mid" | "third-party-provided-mid")
required
Origin of the MID request. Indicates how the MID was discovered or provided.
string ("visa" | "mastercard" | "amex")
required
Card scheme for the MID. Must match the MID field provided (e.g., ‘visa’ requires visaAcquiringMid or vmid).
string
required
The program ID to create MID request in.
string
required
The location ID for the MID request.
string
Mastercard acquiring MID. Required when scheme is ‘mastercard’.
string
Visa acquiring MID. Required when scheme is ‘visa’. Either this or vmid must be provided for Visa.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_CREATE_OFFERCreate a new offer in Fidel API. Use this to set up promotional offers with reward configurations (fixed amount or percentage discount) for specific brands and countries. The offer will be associated with your publisher account and can be activated by customers.

Input Parameters

string
required
Name of the offer. Must be descriptive and unique within your brand.
object
required
Type and value of the offer (amount or discount).
string
required
Unique identifier for the Brand presenting the Offer.
string
The end date for the Offer in ISO 8601 format. If not provided, the offer has no end date.
string
required
The start date for the Offer in ISO 8601 format (local time relative to the Location). Example: ‘2026-03-01T00:00:00’.
object
Activation configuration for the offer.
string
required
3-letter ISO country code where the Offer will be available (e.g., ‘GBR’, ‘USA’).
string
required
Your Fidel Account ID (Publisher ID).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_CREATE_PROGRAMCreates a new card-linked loyalty program in Fidel. A Program is the parent object for tracking card transactions - all Cards, Locations, Webhooks, and Transactions are linked to a Program. Use this before adding cards or locations.

Input Parameters

string
Emoji icon representation (colon-wrapped), e.g., ‘:avocado:’.
string
required
Name of the program to create. Must be 4-50 characters. Avoid special characters like <, >, &, or quotes.
object
Optional custom metadata key/value pairs.
string
Background color for the icon in hex format, e.g., ‘#BADA55’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_CREATE_PROGRAM_WEBHOOKTool to register a new webhook for program-related events. Use when you need to receive real-time notifications for specific program events in your application.

Input Parameters

string
required
HTTPS URL where webhook notifications will be sent
string ("card.linked" | "card.failed" | "program.status" | "location.status" | "transaction.auth" | "transaction.auth.qualified" | "transaction.clearing" | "transaction.clearing.qualified" | "transaction.refund" | "transaction.refund.qualified")
required
Event type to receive notifications for
string
required
Unique ID of the program to which to register the webhook

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_DELETE_LOCATIONTool to delete a location by its ID. Use after confirming the correct location ID. The operation is idempotent - deleting an already-deleted location returns success.

Input Parameters

string
required
The unique identifier (UUID) of the location to delete. Can be obtained from the list locations action.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_DELETE_OFFERDeletes a specified offer by ID. Only self-sourced offers created by publishers can be deleted; content provider and Fidel Marketplace offers cannot be deleted.

Input Parameters

string
required
The unique identifier (UUID) of the offer to delete. Obtain this from the list offers or get offer endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_DELETE_PROGRAM_WEBHOOKPermanently deletes a webhook by its ID. This is a destructive operation that cannot be undone. The webhook will immediately stop receiving event notifications. Use List Program Webhooks first to get the webhook ID if needed.

Input Parameters

string
required
The unique identifier (UUID) of the webhook to delete. Obtain this from the List Program Webhooks or Create Program Webhook actions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_BRANDTool to retrieve information about a specific brand. Use when you have a brand ID and need its details.

Input Parameters

string
required
The unique identifier (UUID format) of the brand to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_LOCATIONTool to retrieve details of a specific location by its ID. Use when you have a location ID and need its full details.

Input Parameters

string
required
The unique identifier (UUID format) of the location to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_MIDTool to retrieve details of a specific MID (Merchant ID). Use when you have a program ID and MID ID to get full MID details.

Input Parameters

string
required
Unique identifier (UUID) of the MID to retrieve.
string
required
Unique identifier (UUID) of the program.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_MID_REQUESTTool to retrieve details of a specific MID request. Use when you have a program ID and MID request ID and need to check the status or details of a Merchant ID request.

Input Parameters

string
required
Unique identifier (UUID) of the program to which the MID request belongs.
string
required
Unique identifier (UUID) of the MID request to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_OFFERRetrieves an offer by ID, including reward configuration, status, dates, card schemes, transaction limits, brand details, location count, and metadata.

Input Parameters

string
required
Unique identifier (UUID) of the offer to retrieve. Example: ‘bfa3c107-0852-41b3-9ec2-c1581bcc9397’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_PROGRAMTool to retrieve details of a specific program. Use when you have a program ID and need its full details.

Input Parameters

string
required
Unique identifier (UUID) for the Program to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_TRANSACTIONTool to retrieve details of a specific transaction by its ID. Use when you need to get complete information about a card-linked transaction including amount, currency, timestamp, and associated metadata.

Input Parameters

string
required
Unique identifier of the transaction to retrieve. Example: ‘bf8071de-eb6b-4c40-bd33-735c8d459b4b’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_GET_WEBHOOKRetrieve details of a specific webhook by its unique identifier. Use this tool when you need to inspect webhook configuration, verify its URL, check the subscribed event type, or obtain the secret key for signature verification.

Input Parameters

string
required
The unique identifier (UUID) of the webhook to retrieve. Obtain this ID from the Create Webhook or List Webhooks endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_BRANDSRetrieves a paginated list of all brands associated with your Fidel API account. Use this tool to: - Get an overview of all brands in your account - Retrieve brand IDs for use in other operations (e.g., getting locations, creating offers) - Paginate through large sets of brands using the cursor-based pagination Returns brand details including name, ID, consent status, and live/test mode indicator.

Input Parameters

integer
Number of brands to return (1-100).
string
Cursor for pagination. Use the first value from the ‘last.sort’ array of a previous response to fetch the next page of results.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_CARDSList all payment cards linked to a Fidel program. Returns card details including scheme (visa/mastercard/amex), last 4 digits, expiry date, and country. Use this to view which cards are enrolled in a loyalty/rewards program. Requires a valid programId - use list_programs first if you don’t have one.

Input Parameters

integer
Maximum number of cards to return per page. Defaults to API default if not specified.
string
Pagination cursor from the ‘last’ field of a previous response. Use to fetch the next page of results.
string
required
The UUID of the program whose linked cards you want to list. Get this from list_programs action.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_CARDS_BY_METADATATool to list payment cards filtered by metadata ID. Use when you need to retrieve all cards that share a specific metadata identifier. Returns card details including scheme, last 4 digits, expiry date, and country. Useful for segmenting cards by custom tags or user groups.

Input Parameters

integer
Maximum number of cards to return per page (1-100, default: 100).
string
Pagination cursor from a previous response’s ‘last’ field. Use to fetch the next page of results.
string
required
The metadata ID to filter cards by. Cards with this metadata ID will be returned.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_CARDS_WITH_ACTIVE_OFFERList all payment cards that have activated a specific offer. Returns card details for cards enrolled in the offer, including activation status and timestamps. Use this to track which cards are participating in a specific loyalty offer. Requires a valid offerId - use list_offers first if you don’t have one.

Input Parameters

integer
Maximum number of cards to return per page. Defaults to API default (100) if not specified.
string ("asc" | "desc")
Sort order for card results.
string
Pagination cursor from the ‘last’ field of a previous response. Use to fetch the next page of results.
string
required
The unique identifier (UUID) of the offer to list activated cards for.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_LOCATIONSTool to list all locations for a program. Use when you need to retrieve paginated store locations within a specific program.

Input Parameters

integer
(Deprecated) Number of locations to return. Use ‘limit’ instead.
integer
Number of locations to return per page (1-100).
Filter locations by name or address substring.
string
required
UUID of the program to list locations for. Obtain program IDs from the List Programs action.
string
Filter locations by 2-letter country code, e.g., ‘GB’.
string
Location UUID for pagination. Returns locations created before this ID.
string
Location UUID for pagination. Returns locations created after this ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_LOCATIONS_BY_BRANDTool to list all locations for a specific brand within a program. Use when you need to retrieve locations filtered by both brand and program IDs with optional pagination, status, and postcode filters.

Input Parameters

integer
Number of locations to return per page (1-100). Default is 100.
string ("asc" | "desc")
Sort order for location results by creation date.
string
Pagination cursor from the ‘last’ field of a previous response to fetch the next page.
string ("active" | "syncing" | "failed")
Status of a location in the Fidel API system.
string
required
UUID of the brand to filter locations. Obtain brand IDs from the List Brands action.
string
Filter locations by postal code (4-20 characters).
string
required
UUID of the program to filter locations. Obtain program IDs from the List Programs action.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_LOCATIONS_BY_OFFERTool to list all locations linked to a specific offer. Use when you need to retrieve locations where an offer is valid or active.

Input Parameters

integer
Maximum number of locations to return (1-100, default: 100).
string ("asc" | "desc")
Sort order for listing locations.
string
Pagination cursor from previous response for fetching next page of results.
string
required
UUID of the offer to list locations for. Obtain offer IDs from the List Offers action.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_MID_REQUESTSList all MID (Merchant ID) requests for a specific program. Use when you need to retrieve MID requests associated with a program for card-linking operations. Supports pagination via the ‘start’ parameter using cursors from previous responses.

Input Parameters

integer
Maximum number of MID requests to return (1-100). Default is 100.
string
Sort order by creation date. Valid values: ‘asc’ (ascending) or ‘desc’ (descending). Default is ‘desc’.
string
Pagination cursor from the ‘last’ field of a previous response. Used for fetching subsequent pages.
string
required
Unique identifier (UUID) of the program to list MID requests from.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_MIDSTool to list all MIDs (Merchant IDs) for a program. Use when you need to retrieve merchant IDs associated with a specific program for transaction tracking or location management.

Input Parameters

integer
Number of MIDs to return per page (1-100).
string
required
UUID of the program to list MIDs for. Obtain program IDs from the List Programs action.
string
MID UUID for pagination. Returns MIDs created after this ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_MISSING_TRANSACTION_REQUESTSTool to list all missing transaction requests for a specific program. Use when you need to retrieve reports of transactions that were expected but not recorded in the system.

Input Parameters

integer
Maximum number of missing transaction requests to return per page (1-100).
string
Sort order for missing transaction requests by created date. Use ‘asc’ for oldest first or ‘desc’ for newest first.
string
Pagination cursor from a previous response’s ‘last’ field. Use this to fetch the next page of results.
string
required
The unique identifier (UUID) of the program to list missing transaction requests for. Required.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_OFFERSList all offers in the Fidel API. Retrieves offers associated with the account, optionally filtered by brand. Returns offer details including type (amount/discount), validity period, card schemes, and activation settings.

Input Parameters

integer
Maximum number of offers to return per page (1-100, default: 100).
string
Sort order by created date: ‘asc’ for ascending, ‘desc’ for descending.
string
Pagination cursor from a previous response’s ‘last’ field. Use to fetch the next page of results.
string
Filter offers by brand UUID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_PROGRAMSList all Fidel programs in your account. Use this to retrieve programs for card-linking, loyalty, or reward systems. Supports pagination via the ‘start’ parameter using cursors from previous responses. Returns program details including name, type, status, and sync state.

Input Parameters

integer
Maximum number of programs to return (1-100). Default is 100.
string
Sort order by creation date. Valid values: ‘asc’ (ascending) or ‘desc’ (descending).
string
Pagination cursor from the ‘last’ field of a previous response. Used for fetching subsequent pages.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_PROGRAM_WEBHOOKSTool to list all registered webhooks for a specific program. Use when you need to retrieve existing webhooks after confirming the programId.

Input Parameters

string
required
The unique identifier (UUID) of the program whose webhooks you want to list.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_LIST_TRANSACTIONSList card-linked transactions for a Fidel program with pagination and optional creation-date ordering. Use this to retrieve transaction data for loyalty, rewards, or analytics.

Input Parameters

integer
Maximum number of transactions to return per page (1-100). Defaults to 10.
string
Sort order for transactions by created date. Use ‘asc’ for oldest first or ‘desc’ for newest first.
string
Pagination cursor from a previous response’s ‘last’ field (JSON string). Use this to fetch the next page of results.
integer
Number of transactions to skip for pagination. Defaults to 0.
string
required
The unique identifier of the Fidel program to list transactions for. Required.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_UPDATE_BRANDUpdate an existing brand’s details in Fidel API. Use this to modify websiteURL, logoURL, or metadata for a brand. The brand name cannot be changed after creation. Requires a valid brand ID from get_brand or list_brands.

Input Parameters

string
required
The unique identifier (UUID) of the brand to update.
string
URL to the brand’s logo image.
object
Custom key-value pairs for storing additional brand data. Max size: 2KB.
string
URL to the brand’s website.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_UPDATE_OFFERUpdates specified properties of an existing offer, such as its name, dates, transaction amounts, terms, or metadata. At least one field must be provided; the response contains selected updated offer properties.

Input Parameters

string
Name of the offer to update.
string
ISO 8601 date/time string when the offer ends (e.g., ‘2024-12-31T23:59:59Z’).
string
required
Unique identifier (UUID) of the offer to update.
object
Custom metadata key-value pairs for the offer. Maximum size is 2KB.
string
ISO 8601 date/time string when the offer starts (e.g., ‘2024-01-01T00:00:00Z’).
array
Array of integers representing days when the offer is valid (0=Sunday, 1=Monday, …, 6=Saturday).
integer
Return period in days for transaction reversals.
string
Additional terms and conditions for the offer.
number
Maximum transaction amount that qualifies for the offer (0 means no limit).
number
Minimum transaction amount required to qualify for the offer.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_UPDATE_PROGRAMUpdates a Fidel API program’s properties. Can modify name (4-50 chars), icon (emoji in :name: format), iconBackground (HEX color), metadata (key/value pairs, max 2KB), or status (‘syncing’ for live programs only). Requires a valid program ID obtained from list_programs or create_program.

Input Parameters

string
Emoji icon in colon-wrapped format (e.g., ‘:avocado:’, ‘:star:’). Must be 4-200 characters.
string
New name for the Program. Must be between 4-50 characters.
string
Set to ‘syncing’ to trigger program synchronization. Only works for live programs.
object
Custom metadata as key/value pairs. Maximum size is 2KB.
string
required
Unique identifier (UUID) of the Program to update.
string
Background color for the icon in HEX format (e.g., ‘#BADA55’, ‘#FF5733’).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: FIDEL_API_UPDATE_WEBHOOKTool to update an existing webhook’s configuration. Use when you need to change the webhook URL or event type. The event field is required even when updating.

Input Parameters

string
The HTTPS endpoint URL where webhook payloads will be delivered. If not provided, the existing URL will remain unchanged.
string ("card.linked" | "card.failed" | "program.status" | "location.status" | "transaction.auth" | "transaction.auth.qualified" | "transaction.clearing" | "transaction.clearing.qualified" | "transaction.refund" | "transaction.refund.qualified" | "brand.consent")
required
The event type this webhook is subscribed to (e.g., ‘transaction.auth’, ‘card.linked’, ‘brand.consent’). This field is required even when updating.
string
required
The unique identifier (UUID) of the webhook to update. Obtain this ID from the Create Webhook or List Webhooks endpoints.
string
required
The ID of the program this webhook is associated with. This field is required for program webhooks.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not