List or search Plans

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://bump.sh/zim/doc/esim-api/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "eSIM API MCP server": {
    "url": "https://bump.sh/zim/doc/esim-api/mcp"
  }
}

Close
GET /plans

Single entry point for the plan catalogue. The response shape depends on the query:

  • Paginated list — when no search filter is given (only destination, page, limit or nothing): returns PaginatedPlans. Plans are sorted by Destination / Region name, then data allowance (unlimited last), then duration.
  • Search — when destination is given without page / limit, or when any of region, scope, category, planType, bestSeller, currency, discountCode, groupByRegion is given: returns a non-paginated array of Plan, or of PlanRegionGroup when groupByRegion=true. A search requires destination or region.

UK domestic plans are not returned here; use POST /plans/search/domestic.

Query parameters

  • destination string

    ISO Alpha-3 code of the Destination

  • region string

    Region abbreviation. Takes precedence over destination and scope.

  • scope string
    • LOCAL - single Destination * REGIONAL - a Region (several Destinations) * GLOBAL - worldwide coverage

    Values are LOCAL, REGIONAL, or GLOBAL.

  • category string

    Values are REGULAR, UNLIMITED, or MIXED.

  • planType string
    • DATA - Data-only Plans * VOICE_AND_DATA - Plans including voice (and SMS) in addition to data

    Values are DATA or VOICE_AND_DATA.

  • bestSeller boolean

    If true, returns only the two best-selling Plans

  • currency string

    Only keep prices in this currency

    Values are usd, eur, gbp, chf, or jpy.

  • discountCode string

    Discount code applied to the returned prices (see Price.discountedFrom)

  • groupByRegion boolean

    Group the results by Region (PlanRegionGroup[])

  • page integer

    Minimum value is 1. Default value is 1.

  • limit integer

    Minimum value is 1, maximum value is 1000. Default value is 10.

Responses

  • 200 application/json

    Plans fetched successfully

    One of:
    Hide attributes Show attributes object
    • id string
    • name string
    • scope string
      • LOCAL - single Destination * REGIONAL - a Region (several Destinations) * GLOBAL - worldwide coverage

      Values are LOCAL, REGIONAL, or GLOBAL.

    • category string

      Values are REGULAR, UNLIMITED, or MIXED.

    • type string
      • DATA - Data-only Plans * VOICE_AND_DATA - Plans including voice (and SMS) in addition to data

      Values are DATA or VOICE_AND_DATA.

    • isRecurring boolean

      true for recurring plans such as UK domestic plans

    • recurringInterval string | null

      Billing interval of recurring plans (MONTHLY for UK domestic plans), null for one-off plans

      Values are DAILY, WEEKLY, MONTHLY, YEARLY, or null.

    • destination object
      Hide destination attributes Show destination attributes object
      • name string
      • isoAlpha3 string
      • regions array[object]
        Hide regions attributes Show regions attributes object
        • name string
        • abbreviation string
      • scopes object

        Returned by GET /destinations/{iso3} only

        Hide scopes attributes Show scopes attributes object
        • local boolean
        • regional boolean
        • global boolean
    • region object
      Hide region attributes Show region attributes object
      • name string
      • abbreviation string
    • dataUnit string

      Possible values:

      • MB - MegaByte representation
      • GB - GigaByte representation

      Values are MB or GB.

    • dataValue number

      Details:

      • If dataValue >= 0 then the plan is capped to that amount of consumable data
      • If dataValue == -1 then the plan is unlimited and does not have a cap on consumable data
    • callUnit string

      Details:

      • MINUTES - Minutes representation
      • HOURS - Hours representation

      Values are MINUTES or HOURS.

    • callValue number

      Details:

      • If callValue >= 0 then the plan is capped to that amount of consumable call time
      • If callValue == -1 then the plan is unlimited and does not have a cap on call time
    • smsUnit string
    • smsValue number

      Details:

      • If smsValue >= 0 then the plan is capped to that amount of consumable SMS sent
      • If smsValue == -1 then the plan is unlimited and does not have a cap on SMS sent
    • durationUnit string
    • durationValue number
    • features array[object]
      Hide features attributes Show features attributes object
      • name string

        Possible values:

        • HOTSPOT - The plan does support the hotspot function
        • TOP_UP - The plan does support top up operations
        • 3G - The plan and its associated network supports speeds up to 3G
        • 4G - The plan and its associated network supports speeds up to 4G
        • 5G - The plan and its associated network supports speeds up to 5G

        Values are HOTSPOT, TOP_UP, 3G, 4G, or 5G.

      • category string

        Values are UTILITY, BILLING, or NETWORK.

    • prices array[object]
      Hide prices attributes Show prices attributes object
      • currencyISO string
      • value number

        The unit amount in minor units (e.g. cents, if supported), represented as a signed integer

      • minorUnitsExponent number

        Indicates the number of decimals in the price for currencies supporting this format or 0 for zero-decimal currencies such as JPY. Examples:

        • A USD price value of 490 with a minorUnitsExponent of 2 would be $4.90
        • A JPY price value of 775 with a minorUnitsExponent of 0 would be ¥775
      • discountedFrom number

        Present when a valid discountCode was applied — the price before discount, in minor units

    • createdAt string(date-time)
    Hide attributes Show attributes object
    • region string
    • supportedCountries array[object]
      Hide supportedCountries attributes Show supportedCountries attributes object
      • name string
      • isoAlpha3 string
      • regions array[object]
        Hide regions attributes Show regions attributes object
        • name string
        • abbreviation string
      • scopes object

        Returned by GET /destinations/{iso3} only

        Hide scopes attributes Show scopes attributes object
        • local boolean
        • regional boolean
        • global boolean
    • plans array[object]
      Hide plans attributes Show plans attributes object
      • id string
      • name string
      • scope string
        • LOCAL - single Destination * REGIONAL - a Region (several Destinations) * GLOBAL - worldwide coverage

        Values are LOCAL, REGIONAL, or GLOBAL.

      • category string

        Values are REGULAR, UNLIMITED, or MIXED.

      • type string
        • DATA - Data-only Plans * VOICE_AND_DATA - Plans including voice (and SMS) in addition to data

        Values are DATA or VOICE_AND_DATA.

      • isRecurring boolean

        true for recurring plans such as UK domestic plans

      • recurringInterval string | null

        Billing interval of recurring plans (MONTHLY for UK domestic plans), null for one-off plans

        Values are DAILY, WEEKLY, MONTHLY, YEARLY, or null.

      • destination object
        Hide destination attributes Show destination attributes object
        • name string
        • isoAlpha3 string
        • regions array[object]
          Hide regions attributes Show regions attributes object
          • name string
          • abbreviation string
        • scopes object

          Returned by GET /destinations/{iso3} only

          Hide scopes attributes Show scopes attributes object
          • local boolean
          • regional boolean
          • global boolean
      • region object
        Hide region attributes Show region attributes object
        • name string
        • abbreviation string
      • dataUnit string

        Possible values:

        • MB - MegaByte representation
        • GB - GigaByte representation

        Values are MB or GB.

      • dataValue number

        Details:

        • If dataValue >= 0 then the plan is capped to that amount of consumable data
        • If dataValue == -1 then the plan is unlimited and does not have a cap on consumable data
      • callUnit string

        Details:

        • MINUTES - Minutes representation
        • HOURS - Hours representation

        Values are MINUTES or HOURS.

      • callValue number

        Details:

        • If callValue >= 0 then the plan is capped to that amount of consumable call time
        • If callValue == -1 then the plan is unlimited and does not have a cap on call time
      • smsUnit string
      • smsValue number

        Details:

        • If smsValue >= 0 then the plan is capped to that amount of consumable SMS sent
        • If smsValue == -1 then the plan is unlimited and does not have a cap on SMS sent
      • durationUnit string
      • durationValue number
      • features array[object]
        Hide features attributes Show features attributes object
        • name string

          Possible values:

          • HOTSPOT - The plan does support the hotspot function
          • TOP_UP - The plan does support top up operations
          • 3G - The plan and its associated network supports speeds up to 3G
          • 4G - The plan and its associated network supports speeds up to 4G
          • 5G - The plan and its associated network supports speeds up to 5G

          Values are HOTSPOT, TOP_UP, 3G, 4G, or 5G.

        • category string

          Values are UTILITY, BILLING, or NETWORK.

      • prices array[object]
        Hide prices attributes Show prices attributes object
        • currencyISO string
        • value number

          The unit amount in minor units (e.g. cents, if supported), represented as a signed integer

        • minorUnitsExponent number

          Indicates the number of decimals in the price for currencies supporting this format or 0 for zero-decimal currencies such as JPY. Examples:

          • A USD price value of 490 with a minorUnitsExponent of 2 would be $4.90
          • A JPY price value of 775 with a minorUnitsExponent of 0 would be ¥775
        • discountedFrom number

          Present when a valid discountCode was applied — the price before discount, in minor units

      • createdAt string(date-time)
  • 400 application/json

    Invalid request or refused by a business rule

    Hide response attributes Show response attributes object
GET /plans
curl \
 --request GET 'https://zim.api.zimconnections.com/plans' \
 --header "X-App-Identifier: $API_KEY"
Response examples (200)
{
  "data": [
    {
      "id": "plan_guaGulGcrqgTYboPvetgu",
      "name": "France - 10GB - 14 days",
      "scope": "LOCAL",
      "category": "REGULAR",
      "type": "DATA",
      "isRecurring": false,
      "recurringInterval": "DAILY",
      "destination": {
        "name": "United Kingdom",
        "isoAlpha3": "GBR",
        "regions": [
          {
            "name": "Europe",
            "abbreviation": "EU"
          }
        ],
        "scopes": {
          "local": true,
          "regional": true,
          "global": true
        }
      },
      "region": {
        "name": "Europe",
        "abbreviation": "EU"
      },
      "dataUnit": "GB",
      "dataValue": 10,
      "callUnit": "MINUTES",
      "callValue": 100,
      "smsUnit": "SMS",
      "smsValue": 100,
      "durationUnit": "DAYS",
      "durationValue": 14,
      "features": [
        {
          "name": "HOTSPOT",
          "category": "UTILITY"
        }
      ],
      "prices": [
        {
          "currencyISO": "usd",
          "value": 490,
          "minorUnitsExponent": 2,
          "discountedFrom": 590
        }
      ],
      "createdAt": "2026-05-04T09:42:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "totalItems": 42,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}
[
  {
    "id": "plan_guaGulGcrqgTYboPvetgu",
    "name": "France - 10GB - 14 days",
    "scope": "LOCAL",
    "category": "REGULAR",
    "type": "DATA",
    "isRecurring": false,
    "recurringInterval": "DAILY",
    "destination": {
      "name": "United Kingdom",
      "isoAlpha3": "GBR",
      "regions": [
        {
          "name": "Europe",
          "abbreviation": "EU"
        }
      ],
      "scopes": {
        "local": true,
        "regional": true,
        "global": true
      }
    },
    "region": {
      "name": "Europe",
      "abbreviation": "EU"
    },
    "dataUnit": "GB",
    "dataValue": 10,
    "callUnit": "MINUTES",
    "callValue": 100,
    "smsUnit": "SMS",
    "smsValue": 100,
    "durationUnit": "DAYS",
    "durationValue": 14,
    "features": [
      {
        "name": "HOTSPOT",
        "category": "UTILITY"
      }
    ],
    "prices": [
      {
        "currencyISO": "usd",
        "value": 490,
        "minorUnitsExponent": 2,
        "discountedFrom": 590
      }
    ],
    "createdAt": "2026-05-04T09:42:00Z"
  }
]
[
  {
    "region": "Europe",
    "supportedCountries": [
      {
        "name": "United Kingdom",
        "isoAlpha3": "GBR",
        "regions": [
          {
            "name": "Europe",
            "abbreviation": "EU"
          }
        ],
        "scopes": {
          "local": true,
          "regional": true,
          "global": true
        }
      }
    ],
    "plans": [
      {
        "id": "plan_guaGulGcrqgTYboPvetgu",
        "name": "France - 10GB - 14 days",
        "scope": "LOCAL",
        "category": "REGULAR",
        "type": "DATA",
        "isRecurring": false,
        "recurringInterval": "DAILY",
        "destination": {
          "name": "United Kingdom",
          "isoAlpha3": "GBR",
          "regions": [
            {
              "name": "Europe",
              "abbreviation": "EU"
            }
          ],
          "scopes": {
            "local": true,
            "regional": true,
            "global": true
          }
        },
        "region": {
          "name": "Europe",
          "abbreviation": "EU"
        },
        "dataUnit": "GB",
        "dataValue": 10,
        "callUnit": "MINUTES",
        "callValue": 100,
        "smsUnit": "SMS",
        "smsValue": 100,
        "durationUnit": "DAYS",
        "durationValue": 14,
        "features": [
          {
            "name": "HOTSPOT",
            "category": "UTILITY"
          }
        ],
        "prices": [
          {
            "currencyISO": "usd",
            "value": 490,
            "minorUnitsExponent": 2,
            "discountedFrom": 590
          }
        ],
        "createdAt": "2026-05-04T09:42:00Z"
      }
    ]
  }
]
Response examples (400)
{
  "statusCode": 400,
  "message": [
    "property foo should not exist"
  ],
  "error": "Bad Request"
}