Browse the docs

List cardholders

GET /v2/api-gateway/cardholders

Lists the cardholders of one organization: organization_id if given, otherwise your top-level organization (child organizations are not included). Filter by email.

Request

Authentication: your API key in the x-api-key header.

Query parameters

Field	Type	Description
`page`	integer	Page number, starting at `1`. Default `1`.
`current_page`	integer	Page number, starting at `1` — the canonical spelling, accepted on every paginated endpoint and matching `pagination.current_page` in the response. `page` means the same thing and keeps working; if both are sent, `current_page` wins.
`per_page`	integer	Cardholders per page. Minimum `1`. Default `10`. A value above `100` is not rejected: it is silently reduced to `100`, and `pagination.per_page` in the response reports the size actually applied — read it back rather than assuming the value you sent.
`email`	string, email	Only the cardholder(s) whose email matches this value exactly.
`organization_id`	string, uuid	UUID of one of your organizations whose cardholders to list. Default: your top-level organization (child organizations are not included). 404 if it is not one of yours.

Example request

cURL

curl --request GET \
     --url 'https://api.themooncard.com/v2/api-gateway/cardholders' \
     --header 'x-api-key: YOUR_API_KEY'

Responses

200 Success

Field	Type	Description
`cardholders` required	array of object
`cardholders[].id` required	string	Cardholder id (Moon-assigned).
`cardholders[].external_id` required	string, nullable	Your identifier for this cardholder (the `end_customer_id` you supplied), or null.
`cardholders[].organization_id` required	string	Owning organization.
`cardholders[].email` required	string, nullable
`cardholders[].delegated_kyc_completed_at` required	string, nullable	When delegated KYC was marked complete, or null.
`cardholders[].banned_at` required	string, nullable	When the cardholder was banned, or null.
`cardholders[].auth_enabled_at` required	string, nullable	When cardholder authentication was enabled, or null.
`cardholders[].last_login_at` required	string, nullable	When the cardholder last logged in, or null.
`cardholders[].metadata` required	object	The key-value data you stored on this cardholder, returned exactly as you sent it. An empty object when you never set any — it is never null.
`cardholders[].created_at` required	string, nullable
`cardholders[].updated_at` required	string, nullable
`pagination` required	object
`pagination.total` required	integer	Total number of items across all pages.
`pagination.last_page` required	integer	Number of the last page (0 when there are no items).
`pagination.prev_page` required	integer, nullable	Previous page number, or null on the first page.
`pagination.next_page` required	integer, nullable	Next page number, or null on the last page.
`pagination.per_page` required	integer	Page size that was applied.
`pagination.current_page` required	integer	1-based current page.
`pagination.from` required	integer	1-based index of the first item on this page (0 when empty).
`pagination.to` required	integer	1-based index of the last item on this page (0 when empty).

JSON

{
  "cardholders": [
    {
      "id": "3f5b1c2e-8d4a-4b6f-9e2a-1c7d8e9f0a1b",
      "external_id": "customer_123",
      "organization_id": "5c1e2d3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "email": "jane@example.com",
      "delegated_kyc_completed_at": "2026-08-02T14:20:05.000Z",
      "banned_at": null,
      "auth_enabled_at": "2026-08-02T14:21:00.000Z",
      "last_login_at": "2026-08-15T09:03:44.000Z",
      "metadata": {
        "crm_id": "CRM-4821"
      },
      "created_at": "2026-08-01T09:12:44.000Z",
      "updated_at": "2026-08-15T09:03:44.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "last_page": 1,
    "prev_page": null,
    "next_page": null,
    "per_page": 10,
    "current_page": 1,
    "from": 1,
    "to": 1
  }
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).

The body is the standard error object: see Errors.

401 Error

Missing or invalid credentials, e.g. { "message": "Invalid API Key", "code": "UNAUTHORIZED" }.

The body is the standard error object: see Errors.

404 Error

Organization not found or not owned by you.

The body is the standard error object: see Errors.

500 Error

Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_SERVER_ERROR" }.

The body is the standard error object: see Errors.

Last updated June 5, 2026