> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.americanexpress.ferndocs.com/utilities/network-loyalty/api-reference/get-benefits/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.americanexpress.ferndocs.com/_mcp/server.

# Provides a list of benefits which are for the given date range.

POST https://api.qa2s.americanexpress.com/loyalty/benefits/search_results
Content-Type: application/json

This endpoint returns a list of benefits.

Reference: https://developer.americanexpress.ferndocs.com/utilities/network-loyalty/api-reference/get-benefits

## Authentication

- `X-AMEX-API-KEY` header (required) — Application API key issued during app registration.
- `Authorization` header (required) — HMAC (one-way TLS). A `MAC` authorization header signed with your client secret. See https://developer.americanexpress.com/documentation/api-security/hmac
- `Authorization` header (required) — HMAC over mutual TLS. Requires a client certificate in addition to the signed `MAC` authorization header.
- `Authorization` header (bearer token, required) — OAuth 2.0 client credentials. Exchange your API key and secret for a bearer token, then send it as `Authorization: Bearer <token>`.

## Servers

- `https://api.qa2s.americanexpress.com/loyalty` (Sandbox, default)
- `https://api.qa2s.americanexpress.com/loyalty/v1/network` (Sandbox, default)

## Request

### Query parameters

- `start_date` (datetime, optional) — The start date, in RFC3339 format, for the date range being requested.e.g., 2021-06-10T19:25:30.000Z.
- `end_date` (datetime, optional) — The end date, in RFC3339 format, for the date range being requested.e.g., 2021-06-10T19:25:30.000Z.
- `SUBSCRIBED` (string, optional) — The subscription status.YES: This will list what Customer is subscribed to (pending/active).NO: This will list what Customer is eligible to subscribe in (inactive).If it is blank, it will return a list of all benefits subscribed and unsubscribed.e.g., SUBSCRIBED=YES.
- `status` (list of string, optional) — The status of the benefit.Accepted values are,ACTIVECANCELLEDINACTIVEe.g., status=ACTIVE&status=CANCELLED.
- `filter` (enum, optional) — The filter parameters to narrow the results.Accepted values are,SUBSCRIBABLE: Returns only the manually subscribable benefits which are eligible as well as subscribed.e.g., filter=SUBSCRIBABLE.
  - Allowed values: `SUBSCRIBABLE`

### Headers

- `Authorization` (string, required) — The Authorization header for the authentication at APIGEE. The following should be in the format of this header:MAC id: The Partner's Client ID. The Client ID is generated during the Partner Onboarding and the App Registration.ts: A client-generated timestamp (Unix Epoch format in milli-seconds).nonce: A unique identifier string. The value of nonce must be unique for the each request.mac: The request mac is generated using the HMAC SHA256 algorithm. Use the Client Secret to generate a hash/signature. The Client ID and Client Secret is generated during the Partner Onboarding and App registration.e.g., MAC id="adc3af10-7bf6-4d8a-87ea-35519ff6e1ad",ts="1466548572491",nonce="be3bd46c-b052-4ae8-9f61-993635e5bc98",bodyhash="cRPVGQWU+89HNR0ASAJFjhKqDF9X0pApGYuC/NVQNEU=",mac="NqbqNO3vSBwk6EE7pBi11DzvgLCh50IPAICCIWgjxYA="
- `correlation_id` (string, required) — A unique identifier used to track the request. This is with the current debugging standard in mind to track the request end-to-end. This will be mainly passed by the originating server (if it's a Webapp) or empty in case of the direct browser/app calls.e.g., GUID.
- `sender` (string, required) — The sender contains the sender information.e.g., Issuer or Service Provider.
- `keyname` (string, required) — The value assigned to the key used to encrypt the payload. For HIPED operations, this value must start with 'MK'.e.g., AA3434342323.

### Body (application/json)

This endpoint expects a Get_Benefit_Search.

- `network_info` (Network_Info, required) — An object containing the GNS-related information.
- `instrument_id` (string, required) — A unique ID for an instrument that is internal to the Issuer.e.g., GUID.
- `product_info` (Benefit_Product_Info, optional) — The reference to a marketable product.e.g., Platinum Card.

## Response

### 200

This response provides a list of benefits based on request parameters.

- `list of BenefitsSearchResultsPostResponsesContentApplicationJsonSchemaItems`

## Errors

### 400 Bad Request Error

Bad request.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 403 Forbidden Error

Forbidden.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 404 Not Found Error

Not Found.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 409 Conflict Error

Conflict: Business error.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

### 500 Internal Server Error

Internal server error.

- `error_code` (string, optional)
- `user_message` (string, optional) — An error occurred when processing your request.
- `developer_message` (string, optional) — A named\_exception was thrown by service\_method when performing processing\_task.

## Types

### Network_Info

An object containing the GNS-related information.

- `institution_id` (string, required) — A unique ID which recognizes the Issuer.e.g., Bank_1, Bank_2.
- `network_id` (string, optional) — A unique ID which identifies the Issuer Network and will be provided, if required.e.g., Express_Company.

### Benefit_Product_Info

The reference to a marketable product.e.g., Platinum Card.

- `market` (double, optional) — The code of the country.e.g., 101.
- `family` (string, optional) — The family code from the GNS Issuer identifying a product.e.g., mock-family.

### BenefitsSearchResultsPostResponsesContentApplicationJsonSchemaItems

The information related to the benefit's resource.

- `id` (string, optional) — A unique ID that is associated with the benefit. This field is only mandatory if the Issuer chooses not to use external_benefit_id.e.g., mock_benefit_id_001.
- `external_benefit` (External_Benefit, optional) — The reference to a benefit set up in an external system. If Issuer chooses to use benefit_id from R42 then this field is not required.e.g., A benefit from a GNS Issuer, such as the Express Company (EC).
- `name` (string, optional) — The name of the benefit ID.e.g., mock_benefit_name.
- `start_date` (datetime, optional) — The start date for the benefit in RFC3339 format.e.g., 2021-06-10T19:25:30Z.
- `end_date` (datetime, optional) — The end date for the benefit in RFC3339 format.e.g., 2021-06-10T19:25:30Z.
- `instrument_id` (string, optional) — A unique ID for an instrument that is internal to the Issuer.e.g., GUID.
- `status` (enum, optional) — The status of the benefit.ACTIVEINACTIVEe.g., ACTIVE.
  - Allowed values: `ACTIVE`, `INACTIVE`
- `characteristics` (Characteristics, optional) — An object containing the flags and the metadata associated with a benefit.
- `subscriptions` (list of Subscriptions, optional)

### External_Benefit

The reference to a benefit set up in an external system. If Issuer chooses to use benefit_id from R42 then this field is not required.e.g., A benefit from a GNS Issuer, such as the Express Company (EC).

- `id` (string, optional)
- `system` (string, optional)

### Characteristics

An object containing the flags and the metadata associated with a benefit.

- `subscribable` (enum, optional) — A property that is true if the benefit requires a subscription.AutoManuale.g., Auto.
  - Allowed values: `Auto`, `Manual`

### Subscriptions

Contains the benefit subscription information.

- `date` (datetime, optional) — The date, in RFC3339 format, of the subscription into a benefit.e.g., 2021-06-10T19:25:30.000Z.
- `end_date` (datetime, optional) — The date, in RFC3339 format, of when the subscription into the benefit will end.e.g., 2021-06-10T19:25:30.000Z.
- `status` (enum, optional) — The status of the subscription.PENDINGACTIVEFAILEDINACTIVEe.g., PENDING.
  - Allowed values: `PENDING`, `ACTIVE`, `FAILED`, `INACTIVE`
- `reject_reason` (string, optional) — The code for the reject reason if the status is FAILED.e.g., 1001.
- `partner_name` (string, optional) — The name of the Partner.e.g., Hilton.
- `program_code` (enum, optional) — The Partner information for the subscription into a benefit.For Hilton, HILTON_HONORS.For Marriott, MARRIOTT_BONVOY.For Melia, MELIA_REWARDS.For Radisson, RADISSON_REWARDS.For Shangri La, SHANGRI-LA_GOLDEN_CIRCLE.For IHG, IHG_REWARDS_CLUB.e.g., HILTON_HONORS.
  - Allowed values: `HILTON_HONORS`, `MARRIOTT_BONVOY`, `MELIA_REWARDS`, `RADISSON_REWARDS`, `SHANGRI-LA_GOLDEN_CIRCLE`, `IHG_REWARDS_CLUB`
- `program_account_id` (string, optional) — The Partner Account ID refers to the FFN.e.g., The Hilton Honors or the BA Executive Club number of the Customer.This is required to be sent by Network Loyalty GNS for the partners: Hilton, Radisson, Marriott.
- `qualified_program_status` (string, optional) — The program status that the associated benefit qualifies for, which is not necessary for the current status of the Partner's system.e.g., Gold.

## Examples

**Request**

```json
{
  "network_info": {
    "institution_id": "string"
  },
  "instrument_id": "GUID"
}
```

**Response**

```json
[
  {
    "id": "string",
    "external_benefit": {
      "id": "string",
      "system": "string"
    },
    "name": "string",
    "start_date": "2021-06-10T19:25:30.000Z",
    "end_date": "2021-06-10T19:25:30.000Z",
    "instrument_id": "GUID",
    "status": "ACTIVE",
    "characteristics": {
      "subscribable": "Auto"
    },
    "subscriptions": [
      {
        "date": "2021-06-10T19:25:30.000Z",
        "end_date": "2021-06-10T19:25:30.000Z",
        "status": "PENDING",
        "reject_reason": "1001",
        "partner_name": "Hilton",
        "program_code": "HILTON_HONORS",
        "program_account_id": "Hilton Honors Number",
        "qualified_program_status": "Gold"
      }
    ]
  }
]
```

**SDK Code**

```python
import requests

url = "https://api.qa2s.americanexpress.com/loyalty/benefits/search_results"

querystring = {"end_date":"2021-06-10T19:25:30.000Z","start_date":"2021-06-10T19:25:30.000Z"}

payload = {
    "network_info": { "institution_id": "string" },
    "instrument_id": "GUID"
}
headers = {
    "Authorization": "Authorization",
    "correlation_id": "correlation_id",
    "keyname": "keyname",
    "sender": "sender",
    "X-AMEX-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.qa2s.americanexpress.com/loyalty/benefits/search_results?end_date=2021-06-10T19%3A25%3A30.000Z&start_date=2021-06-10T19%3A25%3A30.000Z';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Authorization',
    correlation_id: 'correlation_id',
    keyname: 'keyname',
    sender: 'sender',
    'X-AMEX-API-KEY': '<apiKey>',
    'Content-Type': 'application/json'
  },
  body: '{"network_info":{"institution_id":"string"},"instrument_id":"GUID"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qa2s.americanexpress.com/loyalty/benefits/search_results?end_date=2021-06-10T19%3A25%3A30.000Z&start_date=2021-06-10T19%3A25%3A30.000Z"

	payload := strings.NewReader("{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Authorization")
	req.Header.Add("correlation_id", "correlation_id")
	req.Header.Add("keyname", "keyname")
	req.Header.Add("sender", "sender")
	req.Header.Add("X-AMEX-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.qa2s.americanexpress.com/loyalty/benefits/search_results?end_date=2021-06-10T19%3A25%3A30.000Z&start_date=2021-06-10T19%3A25%3A30.000Z")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Authorization'
request["correlation_id"] = 'correlation_id'
request["keyname"] = 'keyname'
request["sender"] = 'sender'
request["X-AMEX-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.qa2s.americanexpress.com/loyalty/benefits/search_results?end_date=2021-06-10T19%3A25%3A30.000Z&start_date=2021-06-10T19%3A25%3A30.000Z")
  .header("Authorization", "Authorization")
  .header("correlation_id", "correlation_id")
  .header("keyname", "keyname")
  .header("sender", "sender")
  .header("X-AMEX-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.qa2s.americanexpress.com/loyalty/benefits/search_results?end_date=2021-06-10T19%3A25%3A30.000Z&start_date=2021-06-10T19%3A25%3A30.000Z', [
  'body' => '{
  "network_info": {
    "institution_id": "string"
  },
  "instrument_id": "GUID"
}',
  'headers' => [
    'Authorization' => 'Authorization',
    'Content-Type' => 'application/json',
    'X-AMEX-API-KEY' => '<apiKey>',
    'correlation_id' => 'correlation_id',
    'keyname' => 'keyname',
    'sender' => 'sender',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.qa2s.americanexpress.com/loyalty/benefits/search_results?end_date=2021-06-10T19%3A25%3A30.000Z&start_date=2021-06-10T19%3A25%3A30.000Z");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Authorization");
request.AddHeader("correlation_id", "correlation_id");
request.AddHeader("keyname", "keyname");
request.AddHeader("sender", "sender");
request.AddHeader("X-AMEX-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"network_info\": {\n    \"institution_id\": \"string\"\n  },\n  \"instrument_id\": \"GUID\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Authorization",
  "correlation_id": "correlation_id",
  "keyname": "keyname",
  "sender": "sender",
  "X-AMEX-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "network_info": ["institution_id": "string"],
  "instrument_id": "GUID"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.qa2s.americanexpress.com/loyalty/benefits/search_results?end_date=2021-06-10T19%3A25%3A30.000Z&start_date=2021-06-10T19%3A25%3A30.000Z")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```