# Fidel API

Fidel API provides a developer-friendly, secure, and reliable API for businesses to link payment cards with mobile and web applications, enabling real-time transaction monitoring and event-based experiences.

- **Category:** payment processing
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 39
- **Triggers:** 0
- **Slug:** `FIDEL_API`
- **Version:** 20260312_00

## Tools

### Create Brand

**Slug:** `FIDEL_API_CREATE_BRAND`

Create 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | The brand name. Must be unique within your account and between 2-50 characters. |
| `logoURL` | string | No | URL to the brand's logo image. Supported formats: GIF, JPG, JPEG, PNG. |
| `metadata` | object | No | Custom key-value pairs for storing additional brand data. Max size: 2KB. |
| `websiteURL` | string | No | URL to the brand's website. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Brand Webhook

**Slug:** `FIDEL_API_CREATE_BRAND_WEBHOOK`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | HTTPS URL where webhook notifications will be sent. Must be a valid HTTPS endpoint that can receive POST requests. |
| `event` | string | Yes | Event type to receive notifications for. For brand webhooks, use 'brand.consent' to receive notifications when brand consent is approved. |
| `headers` | object | No | Optional custom headers (max 5) to include in webhook requests. Useful for adding authentication tokens or custom identifiers. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Location

**Slug:** `FIDEL_API_CREATE_LOCATION`

Create 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

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

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create MID Request

**Slug:** `FIDEL_API_CREATE_MID_REQUEST`

Tool 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

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

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Offer

**Slug:** `FIDEL_API_CREATE_OFFER`

Create 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name of the offer. Must be descriptive and unique within your brand. |
| `type` | object | Yes | Type and value of the offer (amount or discount). |
| `brandId` | string | Yes | Unique identifier for the Brand presenting the Offer. |
| `endDate` | string | No | The end date for the Offer in ISO 8601 format. If not provided, the offer has no end date. |
| `startDate` | string | Yes | The start date for the Offer in ISO 8601 format (local time relative to the Location). Example: '2026-03-01T00:00:00'. |
| `activation` | object | No | Activation configuration for the offer. |
| `countryCode` | string | Yes | 3-letter ISO country code where the Offer will be available (e.g., 'GBR', 'USA'). |
| `publisherId` | string | Yes | Your Fidel Account ID (Publisher ID). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Program

**Slug:** `FIDEL_API_CREATE_PROGRAM`

Creates 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `icon` | string | No | Emoji icon representation (colon-wrapped), e.g., ':avocado:'. |
| `name` | string | Yes | Name of the program to create. Must be 4-50 characters. Avoid special characters like <, >, &, or quotes. |
| `metadata` | object | No | Optional custom metadata key/value pairs. |
| `iconBackground` | string | No | Background color for the icon in hex format, e.g., '#BADA55'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Program Webhook

**Slug:** `FIDEL_API_CREATE_PROGRAM_WEBHOOK`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | HTTPS URL where webhook notifications will be sent |
| `event` | string ("card.linked" | "card.failed" | "program.status" | "location.status" | "transaction.auth" | "transaction.auth.qualified" | "transaction.clearing" | "transaction.clearing.qualified" | "transaction.refund" | "transaction.refund.qualified") | Yes | Event type to receive notifications for |
| `programId` | string | Yes | Unique ID of the program to which to register the webhook |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Location

**Slug:** `FIDEL_API_DELETE_LOCATION`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `locationId` | string | Yes | The unique identifier (UUID) of the location to delete. Can be obtained from the list locations action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Offer

**Slug:** `FIDEL_API_DELETE_OFFER`

Tool to delete a specified offer by its ID. Use after confirming the correct offer ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `offerId` | string | Yes | The unique identifier (UUID) of the offer to delete. Obtain this from the list offers or get offer endpoints. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Program Webhook

**Slug:** `FIDEL_API_DELETE_PROGRAM_WEBHOOK`

Permanently 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hookId` | string | Yes | The unique identifier (UUID) of the webhook to delete. Obtain this from the List Program Webhooks or Create Program Webhook actions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Brand

**Slug:** `FIDEL_API_GET_BRAND`

Tool to retrieve information about a specific brand. Use when you have a brand ID and need its details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `brandId` | string | Yes | The unique identifier (UUID format) of the brand to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Location

**Slug:** `FIDEL_API_GET_LOCATION`

Tool to retrieve details of a specific location by its ID. Use when you have a location ID and need its full details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `locationId` | string | Yes | The unique identifier (UUID format) of the location to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get MID

**Slug:** `FIDEL_API_GET_MID`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `midId` | string | Yes | Unique identifier (UUID) of the MID to retrieve. |
| `programId` | string | Yes | Unique identifier (UUID) of the program. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get MID Request

**Slug:** `FIDEL_API_GET_MID_REQUEST`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `programId` | string | Yes | Unique identifier (UUID) of the program to which the MID request belongs. |
| `midRequestId` | string | Yes | Unique identifier (UUID) of the MID request to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Offer

**Slug:** `FIDEL_API_GET_OFFER`

Retrieves detailed information about a specific offer by its unique ID. Use this tool when you need to: - Get full details about a known offer (reward type, value, dates, etc.) - Verify offer status (active, expired, requests) - Check offer configuration (schemes, days of week, transaction limits) - View brand and location information for an offer Returns comprehensive offer details including reward configuration, eligibility criteria, and metadata.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `offerId` | string | Yes | Unique identifier (UUID) of the offer to retrieve. Example: 'bfa3c107-0852-41b3-9ec2-c1581bcc9397'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Program

**Slug:** `FIDEL_API_GET_PROGRAM`

Tool to retrieve details of a specific program. Use when you have a program ID and need its full details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `programId` | string | Yes | Unique identifier (UUID) for the Program to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Transaction

**Slug:** `FIDEL_API_GET_TRANSACTION`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `transactionId` | string | Yes | Unique identifier of the transaction to retrieve. Example: 'bf8071de-eb6b-4c40-bd33-735c8d459b4b'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Webhook

**Slug:** `FIDEL_API_GET_WEBHOOK`

Retrieve 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hookId` | string | Yes | The unique identifier (UUID) of the webhook to retrieve. Obtain this ID from the Create Webhook or List Webhooks endpoints. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Link All Program Locations to Offer

**Slug:** `FIDEL_API_LINK_ALL_PROGRAM_LOCATIONS_TO_OFFER`

Tool to link all brand locations in a program to an offer. Use when you need to associate all locations from a specific program with an offer, making the offer available at all those brand locations.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `offerId` | string | Yes | Unique identifier (UUID) of the offer to link locations to. Example: 'd930876e-388f-42f7-a6a2-6deaff246886'. |
| `programId` | string | Yes | Unique identifier (UUID) of the program whose brand locations will be linked to the offer. Example: '1f5d0666-bb84-4d11-bb28-779bfe1af006'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Link Location to Offer

**Slug:** `FIDEL_API_LINK_LOCATION_TO_OFFER`

Link a location to an offer in Fidel API. Use this action to associate a specific location with an offer, making the offer available at that location. Once linked, transactions at the location will be eligible for the offer's rewards.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `offerId` | string | Yes | The unique identifier (UUID) of the offer to link the location to. Example: 'd930876e-388f-42f7-a6a2-6deaff246886'. |
| `locationId` | string | Yes | The unique identifier (UUID) of the location to link to the offer. Example: '04756e05-412e-478d-b5c6-d865db2f9403'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Brands

**Slug:** `FIDEL_API_LIST_BRANDS`

Retrieves 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Number of brands to return (1-100). |
| `startingAfter` | string | No | Cursor for pagination. Use the first value from the 'last.sort' array of a previous response to fetch the next page of results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Cards

**Slug:** `FIDEL_API_LIST_CARDS`

List 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of cards to return per page. Defaults to API default if not specified. |
| `start` | string | No | Pagination cursor from the 'last' field of a previous response. Use to fetch the next page of results. |
| `programId` | string | Yes | The UUID of the program whose linked cards you want to list. Get this from list_programs action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Cards By Metadata

**Slug:** `FIDEL_API_LIST_CARDS_BY_METADATA`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `metadataId` | string | Yes | The metadata ID to filter cards by. Cards with this metadata ID will be returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Cards with Active Offer

**Slug:** `FIDEL_API_LIST_CARDS_WITH_ACTIVE_OFFER`

List 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of cards to return per page. Defaults to API default (100) if not specified. |
| `order` | string ("asc" | "desc") | No | Sort order for card results. |
| `start` | string | No | Pagination cursor from the 'last' field of a previous response. Use to fetch the next page of results. |
| `offerId` | string | Yes | The unique identifier (UUID) of the offer to list activated cards for. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Locations

**Slug:** `FIDEL_API_LIST_LOCATIONS`

Tool to list all locations for a program. Use when you need to retrieve paginated store locations within a specific program.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `count` | integer | No | (Deprecated) Number of locations to return. Use 'limit' instead. |
| `limit` | integer | No | Number of locations to return per page (1-100). |
| `search` | string | No | Filter locations by name or address substring. |
| `programId` | string | Yes | UUID of the program to list locations for. Obtain program IDs from the List Programs action. |
| `countryCode` | string | No | Filter locations by 2-letter country code, e.g., 'GB'. |
| `endingBefore` | string | No | Location UUID for pagination. Returns locations created before this ID. |
| `startingAfter` | string | No | Location UUID for pagination. Returns locations created after this ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Locations by Brand

**Slug:** `FIDEL_API_LIST_LOCATIONS_BY_BRAND`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Number of locations to return per page (1-100). Default is 100. |
| `order` | string ("asc" | "desc") | No | Sort order for location results by creation date. |
| `start` | string | No | Pagination cursor from the 'last' field of a previous response to fetch the next page. |
| `status` | string ("active" | "syncing" | "failed") | No | Status of a location in the Fidel API system. |
| `brandId` | string | Yes | UUID of the brand to filter locations. Obtain brand IDs from the List Brands action. |
| `postcode` | string | No | Filter locations by postal code (4-20 characters). |
| `programId` | string | Yes | UUID of the program to filter locations. Obtain program IDs from the List Programs action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Locations by Offer

**Slug:** `FIDEL_API_LIST_LOCATIONS_BY_OFFER`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of locations to return (1-100, default: 100). |
| `order` | string ("asc" | "desc") | No | Sort order for listing locations. |
| `start` | string | No | Pagination cursor from previous response for fetching next page of results. |
| `offerId` | string | Yes | UUID of the offer to list locations for. Obtain offer IDs from the List Offers action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List MID Requests

**Slug:** `FIDEL_API_LIST_MID_REQUESTS`

List 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of MID requests to return (1-100). Default is 100. |
| `order` | string | No | Sort order by creation date. Valid values: 'asc' (ascending) or 'desc' (descending). Default is 'desc'. |
| `start` | string | No | Pagination cursor from the 'last' field of a previous response. Used for fetching subsequent pages. |
| `programId` | string | Yes | Unique identifier (UUID) of the program to list MID requests from. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List MIDs

**Slug:** `FIDEL_API_LIST_MIDS`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Number of MIDs to return per page (1-100). |
| `programId` | string | Yes | UUID of the program to list MIDs for. Obtain program IDs from the List Programs action. |
| `startingAfter` | string | No | MID UUID for pagination. Returns MIDs created after this ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Missing Transaction Requests

**Slug:** `FIDEL_API_LIST_MISSING_TRANSACTION_REQUESTS`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of missing transaction requests to return per page (1-100). |
| `order` | string | No | Sort order for missing transaction requests by created date. Use 'asc' for oldest first or 'desc' for newest first. |
| `start` | string | No | Pagination cursor from a previous response's 'last' field. Use this to fetch the next page of results. |
| `programId` | string | Yes | The unique identifier (UUID) of the program to list missing transaction requests for. Required. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Offers

**Slug:** `FIDEL_API_LIST_OFFERS`

List 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `brandId` | string | No | Filter offers by brand UUID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Programs

**Slug:** `FIDEL_API_LIST_PROGRAMS`

List 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of programs to return (1-100). Default is 100. |
| `order` | string | No | Sort order by creation date. Valid values: 'asc' (ascending) or 'desc' (descending). |
| `start` | string | No | Pagination cursor from the 'last' field of a previous response. Used for fetching subsequent pages. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Program Webhooks

**Slug:** `FIDEL_API_LIST_PROGRAM_WEBHOOKS`

Tool to list all registered webhooks for a specific program. Use when you need to retrieve existing webhooks after confirming the programId.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `programId` | string | Yes | The unique identifier (UUID) of the program whose webhooks you want to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Transactions

**Slug:** `FIDEL_API_LIST_TRANSACTIONS`

List transactions for a Fidel program with optional filtering and pagination. Use this tool to retrieve card-linked transaction data for loyalty, rewards, or analytics purposes. Requires a valid programId.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of transactions to return per page (1-100). Defaults to 10. |
| `order` | string | No | Sort order for transactions by created date. Use 'asc' for oldest first or 'desc' for newest first. |
| `start` | string | No | Pagination cursor from a previous response's 'last' field (JSON string). Use this to fetch the next page of results. |
| `offset` | integer | No | Number of transactions to skip for pagination. Defaults to 0. |
| `programId` | string | Yes | The unique identifier of the Fidel program to list transactions for. Required. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unlink Location From Offer

**Slug:** `FIDEL_API_UNLINK_LOCATION_FROM_OFFER`

Tool to unlink a location from an offer by removing the location association. Use after confirming the correct offer ID and location ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `offerId` | string | Yes | The unique identifier (UUID) of the offer to unlink the location from. Obtain this from the list offers or get offer endpoints. |
| `locationId` | string | Yes | The unique identifier (UUID) of the location to unlink from the offer. Obtain this from the list locations endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Brand

**Slug:** `FIDEL_API_UPDATE_BRAND`

Update 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `brandId` | string | Yes | The unique identifier (UUID) of the brand to update. |
| `logoURL` | string | No | URL to the brand's logo image. |
| `metadata` | object | No | Custom key-value pairs for storing additional brand data. Max size: 2KB. |
| `websiteURL` | string | No | URL to the brand's website. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Offer

**Slug:** `FIDEL_API_UPDATE_OFFER`

Updates specific properties of an existing offer. Use this when you need to modify offer details such as name, dates, transaction amounts, terms, or metadata. At least one field must be provided to update. Returns the complete updated offer object with all current properties.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Name of the offer to update. |
| `endDate` | string | No | ISO 8601 date/time string when the offer ends (e.g., '2024-12-31T23:59:59Z'). |
| `offerId` | string | Yes | Unique identifier (UUID) of the offer to update. |
| `metadata` | object | No | Custom metadata key-value pairs for the offer. Maximum size is 2KB. |
| `startDate` | string | No | ISO 8601 date/time string when the offer starts (e.g., '2024-01-01T00:00:00Z'). |
| `daysOfWeek` | array | No | Array of integers representing days when the offer is valid (0=Sunday, 1=Monday, ..., 6=Saturday). |
| `returnPeriod` | integer | No | Return period in days for transaction reversals. |
| `additionalTerms` | string | No | Additional terms and conditions for the offer. |
| `maxTransactionAmount` | number | No | Maximum transaction amount that qualifies for the offer (0 means no limit). |
| `minTransactionAmount` | number | No | Minimum transaction amount required to qualify for the offer. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Program

**Slug:** `FIDEL_API_UPDATE_PROGRAM`

Updates 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

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

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Webhook

**Slug:** `FIDEL_API_UPDATE_WEBHOOK`

Tool 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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | The HTTPS endpoint URL where webhook payloads will be delivered. If not provided, the existing URL will remain unchanged. |
| `event` | 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") | Yes | The event type this webhook is subscribed to (e.g., 'transaction.auth', 'card.linked', 'brand.consent'). This field is required even when updating. |
| `hookId` | string | Yes | The unique identifier (UUID) of the webhook to update. Obtain this ID from the Create Webhook or List Webhooks endpoints. |
| `programId` | string | Yes | The ID of the program this webhook is associated with. This field is required for program webhooks. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |