---
title: "Retrieve merchant addresses"
method: GET
path: "/addresses"
tags: ["Addresses"]
---

# Retrieve merchant addresses

`GET /addresses`

Returns the addresses assigned to the merchant.

Can be filtered by address category and status. 

By default, if no value is passed for the address category index, it returns all the address categories that are active for the merchant. The list can be filtered by address category and/or address status.

## Query parameters

- `categoryIndex` string
- `addressStatus` 'FUTURE' | 'ACTIVE' | 'ALL'

## Headers

- `Content-Type` 'application/json' | 'application/json;charset=UTF-8', required
- `FSV-Interaction-Id` string, required
- `Environment` string, required
- `Institution-Number` string, required
- `Internal-Merchant-Id` string, required

## Response `200`

OK

- InlineResponse2007 — An API response. The API response will be either a `SUCCESS` or an `ERROR`. A partial success or warning scenario will be treated as a Success with embedded messages in the meta data. A full success may not have messages. The API response will contain at least one of the following top level members."
  - `meta` MetaType — Supplementary information about the data.
    - `paging` PagingMetaType — Map containing pagination related information about data.
      - `count` integer — Total number of records present in system which can be retrieved.
      - `totalPages` integer — Total number of pages with maximum limit taken into account.
      - `currentOffset` integer — Current offset used in request.
      - `currentNumberOfRetrievedRecords` integer — Current number of retrieved records.
      - `maxLimit` integer — Maximum limit of records that can be retrieved.
      - `hasMoreRecords` boolean — Indicates if there are more records available.
      - `pageNumber` integer — Current page number.
    - `sorting` SortingMetaType — Map containing sorting related information about data.
      - `sort` string — Indicates the elements the current data is sorted with and the direction of sorting.
    - `messages` ErrorType[] — Messages related to request processing or response data - any additional information or warnings to be returned in the case of a successful API call.
      - `id` string — Generated message identifier for particular request, helping to locate server logs.
      - `code` string, required — Machine readable, unique code of the message related to particular case within operation execution. For complete list of codes please refer to API portal, messages page.
      - `title` string, required — Short description of the error. Not for displaying purposes.
      - `detail` string — Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
      - `source` SourceType — Object containing references to the source of the message.
        - `pointer` string — Indicates the element in the request document which caused the error.
        - `parameter` string — Indicates which query parameter caused the error.
        - `header` string — Indicates which header caused the error.
  - `data` object[] — "Contains the primary data to be returned as the API response. Use this object only when respnse type is an array. It will not be returned in case of error."
    - `status` 'FUTURE' | 'ACTIVE' | 'ALL' — Future - returns addresses not yet effective ( having effective date later than current posting date ). Active - returns currently active addresses ( having effective date smaller than current posting date ). All - returns both future and active addresses
    - `merchantAddress` MerchantAddress[]
      - `category` OPYAddressCategoryObj — The category of the address to be added. It can be a mandatory or optional category, defined per Institution.
        - `categoryIndex` string — Numeric Code.
        - `categoryDescription` string — Contains description associated to a code in English.
      - `contactName` string — The contact name at the address location. Any extended ASCII characters contains 2 bytes. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `groupSpecific` boolean — Only applicable if a merchant is in a hierarchy. Indicates if the address is to be used for all merchants within the group.
      - `line1` string — Merchant address line 1 for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `line2` string — Merchant address line 2 for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `line3` string — Merchant address line 3 for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `line4` string — Merchant address line 4 for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `line5` string — Merchant address line 5 for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `postCode` string — Merchant address post code or zip code for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `city` string — Merchant city for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `state` string — Merchant state for the specified address category. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.
      - `countryCode` string — ISO-3166 alpha country code representing the country the address category is located in, the values are restricted based on institutions configuration. For a list of valid codes use Acquirer Profile API get reference-data endpoint with query parameter classification equal countryCode.
      - `telephone` string — Telephone at the specified address category
      - `fax` string — Fax at the specified address category
      - `email` string — Email address (with extended length capacity) for the specified address category
      - `deliveryMethodIndex` OPYAddressDeliveryMethodObj — Delivery method code of correspondence to this address; however, it is dependent on the delivery solutions in place for the given institution.
        - `deliveryMethodIndex` string — Numeric Code.
        - `deliveryMethodDescription` string — Contains description associated to a code in English.
      - `effectiveDate` string — Effective date of the address. When selecting address information on the Omnipay platform, the system will automatically choose the most recently effective address. To maintain accurate audit records, merchant addresses cannot be deleted after they become effective. Therefore, effective dates in the format of YYYYMMDD are used for all addresses. When adding address in merchant maintenance, the effective date must be on or after the current institution posting date. If no effective date is provided, the default will be the current institution posting date.
      - `lastUpdatedBy` string — Contact name of the person or system description that last updated the record.
      - `lastUpdated` string — Date when the record was last updated. Format YYYYMMDD.
  - `errors` ErrorType[] — "Contains one or more error messages and is mutually exclusive with the data item. This will not be returned in success scenarios."
    - `id` string — Generated message identifier for particular request, helping to locate server logs.
    - `code` string, required — Machine readable, unique code of the message related to particular case within operation execution. For complete list of codes please refer to API portal, messages page.
    - `title` string, required — Short description of the error. Not for displaying purposes.
    - `detail` string — Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
    - `source` SourceType — Object containing references to the source of the message.
      - `pointer` string — Indicates the element in the request document which caused the error.
      - `parameter` string — Indicates which query parameter caused the error.
      - `header` string — Indicates which header caused the error.
  - `links` LinksType — Contains the links to retrieve the resources exposed as part of this API.
    - `self` string — The link to the primary resource being retrieved in the request.
    - `first` string — This is to provide the link to retrieve the first record/page. This SHOULD be used in case server provides pagination of the resource.
    - `last` string — This is to provide the link to retrieve the last record/page. This SHOULD be used in case server provides pagination of the resource.
    - `prev` string — This is to provide the link to retrieve the previous record/page. This SHOULD be used in case server provides pagination of the resource.
    - `next` string — This is to provide the link to retrieve the last record. This SHOULD be used in case server provides pagination of the resource

## Other responses

- `400` — Invalid request
- `401` — Authorization error
- `403` — Forbidden error i.e. Consumer token credentials are valid but lack of permissions to do this action.
- `404` — Record does not exist
- `500` — Internal Server Error

---

[API](https://skmtc.net/fiserv/apis/acquirer-profile-in-design.md) · [All operations](https://skmtc.net/fiserv/apis/acquirer-profile-in-design/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fiserv/acquirer-profile-in-design/versions/dd7ef6ce81a1/schema)