> ## Documentation Index > Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # Create card > Required API-key scope: `cards:write`. A newly created card normally has a `spentAmount` of `0.00`. ## OpenAPI ````yaml /openapi/2026-07-13.json post /2026-07-13/cards openapi: 3.1.0 info: title: Reap Direct API description: > # Introduction The Reap Direct API gives you programmatic access to Reap Direct: issue and manage cards, control spend and resolve team members from your own systems. ## Quickstart 1. Ask a team administrator to create an API key from the Reap dashboard. 2. Make your first request: ```bash curl https://api.global.direct.reap.global/2026-07-13/cards \ -H "x-api-key: " ``` ## Authentication Every request is authenticated with an API key sent in the `x-api-key` header. Keys are issued per business and carry scopes that limit which endpoints they can call: requests without a valid key receive `401`; requests with a valid key but insufficient scope receive `403`. ## Response schemas A response property marked `required` is always present in that response. This is separate from nullability: a required property may still contain `null` when its schema is nullable. ## Versioning The API is versioned with dates in the URL: `/2026-07-13/cards`. Pin one version in your integration and every endpoint keeps its behavior on that date while it is supported. - New dates are published only when breaking changes ship; additive changes (new optional fields, new endpoints) appear on all supported dates. - Each date remains supported for at least 12 months after its successor is published; deprecation and sunset dates are announced before retirement. - Supported versions: 2026-07-13. Requests to an unknown version return `404` with an error listing the supported versions. ## Errors All errors share a single JSON envelope: ```json { "statusCode": 400, "type": "INVALID_REQUEST_ERROR", "code": "SPEND_CAP_TOO_LOW", "message": "Spend cap cannot be lower than the amount already spent on this card.", "param": "spendCap", "requestId": "01H..." } ``` - `statusCode` — HTTP status, duplicated in the body. - `type` — coarse category, **always present**. Branch on this for retry/re-auth decisions. - `code` — stable, machine-readable identifier. Present only for programmatically-actionable errors. - `message` — human-readable explanation, safe to surface to users. - `param` — offending field for validation errors (optional). - `details` — structured extra context such as validation issues (optional). - `requestId` — correlation id; include it when contacting support (optional). The specific error codes each endpoint can return are documented on that endpoint's responses below. ### Error types | Type | Description | | --- | --- | | `INVALID_REQUEST_ERROR` | The request was rejected due to invalid input, a missing resource, or a business-rule violation (HTTP 400/404/409/422). | | `AUTHENTICATION_ERROR` | Authentication is missing or invalid (HTTP 401). | | `PERMISSION_ERROR` | The caller is authenticated but not permitted to perform the action (HTTP 403). | | `RATE_LIMIT_ERROR` | Too many requests; retry after a delay (HTTP 429). | | `API_ERROR` | An unexpected error occurred on our side (HTTP 5xx). | | `UPSTREAM_ERROR` | An upstream service returned an error (HTTP 502/503). | version: '2026-07-13' contact: {} servers: - url: https://api.global.direct.reap.global security: [] tags: [] paths: /2026-07-13/cards: post: tags: - Cards summary: Create card description: >- Required API-key scope: `cards:write`. A newly created card normally has a `spentAmount` of `0.00`. operationId: createCard parameters: - name: Idempotency-Key in: header description: Replaying the same key returns the original result. required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCard' responses: '201': description: >- Card created. When the card is not yet readable, the body degrades to `{ id, status: "pending" }` — poll the `Location` header. headers: Location: description: Version-matched URL of the created card. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Card' - $ref: '#/components/schemas/CardCreatedPending' examples: created: summary: Card created value: id: card_01JZ2Q4T4J7QF2G6Z3X9A1B5CD type: virtual status: active title: Travel card last4: '4242' expiresAt: '2028-08-31' isRevolving: false planType: topUp category: travel cardholder: userId: user_01JZ2Q1J4Y8P7M6N5K3H2G1F0E name: Ada Lovelace email: ada@example.com spendCap: amount: '5000.00' currency: USD spentAmount: amount: '0.00' currency: USD spendControl: limits: transaction: amount: '1000.00' currency: USD monthly: amount: '5000.00' currency: USD spent: monthly: amount: '0.00' currency: USD atm: dailyWithdrawal: amount: '500.00' currency: USD dailyFrequency: 3 restriction: time: start: '09:00' end: '18:00' category: allow: true ids: - travel createdAt: '2026-07-13T08:00:00.000Z' updatedAt: '2026-07-13T08:00:00.000Z' pendingSync: summary: Card created and pending synchronization value: id: card_01JZ2Q4T4J7QF2G6Z3X9A1B5CD status: pending '202': description: Card creation requires approval. content: application/json: schema: $ref: '#/components/schemas/CardApprovalPending' examples: pendingApproval: summary: Card creation awaiting approval value: approvalRequestId: approval_01JZ2Q8A6B4C3D2E1F0G9H8J7K status: pendingApproval '400': description: '`BAD_REQUEST`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: BAD_REQUEST: summary: BAD_REQUEST value: statusCode: 400 type: INVALID_REQUEST_ERROR message: Bad request. '401': description: '`UNAUTHORIZED`, `AUTH_CREDENTIAL_MISSING`, `API_KEY_INVALID`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: UNAUTHORIZED: summary: UNAUTHORIZED value: statusCode: 401 type: AUTHENTICATION_ERROR message: Authentication required. AUTH_CREDENTIAL_MISSING: summary: AUTH_CREDENTIAL_MISSING value: statusCode: 401 type: AUTHENTICATION_ERROR code: AUTH_CREDENTIAL_MISSING message: Authentication is required. API_KEY_INVALID: summary: API_KEY_INVALID value: statusCode: 401 type: AUTHENTICATION_ERROR code: API_KEY_INVALID message: API key is invalid. '403': description: >- `FORBIDDEN`, `API_KEY_IP_NOT_ALLOWED`, `AUTH_INSUFFICIENT_PERMISSIONS`, `AUTH_METHOD_NOT_ALLOWED` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: FORBIDDEN: summary: FORBIDDEN value: statusCode: 403 type: PERMISSION_ERROR message: You do not have permission to perform this action. API_KEY_IP_NOT_ALLOWED: summary: API_KEY_IP_NOT_ALLOWED value: statusCode: 403 type: PERMISSION_ERROR code: API_KEY_IP_NOT_ALLOWED message: Request IP is not allowed for this API key. AUTH_INSUFFICIENT_PERMISSIONS: summary: AUTH_INSUFFICIENT_PERMISSIONS value: statusCode: 403 type: PERMISSION_ERROR code: AUTH_INSUFFICIENT_PERMISSIONS message: Insufficient permissions. AUTH_METHOD_NOT_ALLOWED: summary: AUTH_METHOD_NOT_ALLOWED value: statusCode: 403 type: PERMISSION_ERROR code: AUTH_METHOD_NOT_ALLOWED message: >- This endpoint does not accept the credential type provided. '409': description: '`IDEMPOTENCY_KEY_IN_FLIGHT`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: IDEMPOTENCY_KEY_IN_FLIGHT: summary: IDEMPOTENCY_KEY_IN_FLIGHT value: statusCode: 409 type: INVALID_REQUEST_ERROR code: IDEMPOTENCY_KEY_IN_FLIGHT message: >- A request with this Idempotency-Key is still being processed. Retry shortly. '422': description: >- `CARD_CREATION_REQUIRES_DEPOSIT`, `CARDHOLDER_NOT_FOUND`, `IDEMPOTENCY_KEY_REUSED`, `CURRENCY_MISMATCH` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: CARD_CREATION_REQUIRES_DEPOSIT: summary: CARD_CREATION_REQUIRES_DEPOSIT value: statusCode: 422 type: INVALID_REQUEST_ERROR code: CARD_CREATION_REQUIRES_DEPOSIT message: Deposit funds before creating a card. CARDHOLDER_NOT_FOUND: summary: CARDHOLDER_NOT_FOUND value: statusCode: 422 type: INVALID_REQUEST_ERROR code: CARDHOLDER_NOT_FOUND message: No team member matches the provided cardholder id. IDEMPOTENCY_KEY_REUSED: summary: IDEMPOTENCY_KEY_REUSED value: statusCode: 422 type: INVALID_REQUEST_ERROR code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request body. CURRENCY_MISMATCH: summary: CURRENCY_MISMATCH value: statusCode: 422 type: INVALID_REQUEST_ERROR code: CURRENCY_MISMATCH message: The provided currency does not match the card currency. '429': description: '`CARD_LIMIT_EXCEEDED`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: API_KEY_RATE_LIMITED: summary: API_KEY_RATE_LIMITED value: statusCode: 429 type: RATE_LIMIT_ERROR code: API_KEY_RATE_LIMITED message: API key rate limit exceeded. CARD_LIMIT_EXCEEDED: summary: CARD_LIMIT_EXCEEDED value: statusCode: 429 type: RATE_LIMIT_ERROR code: CARD_LIMIT_EXCEEDED message: >- Your account has reached the maximum number of cards. Contact support to request more. '500': description: '`INTERNAL_ERROR`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: statusCode: 500 type: API_ERROR message: An unexpected error occurred. '503': description: '`CARD_CREATION_UNAVAILABLE`, `IDEMPOTENCY_UNAVAILABLE`' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: CARD_CREATION_UNAVAILABLE: summary: CARD_CREATION_UNAVAILABLE value: statusCode: 503 type: API_ERROR code: CARD_CREATION_UNAVAILABLE message: >- Card creation temporarily unavailable. Please retry shortly. IDEMPOTENCY_UNAVAILABLE: summary: IDEMPOTENCY_UNAVAILABLE value: statusCode: 503 type: API_ERROR code: IDEMPOTENCY_UNAVAILABLE message: >- The idempotent request outcome could not be safely determined. security: - apiKey: [] components: schemas: CreateCard: type: object properties: type: type: string const: virtual description: Type of card to create. title: type: string maxLength: 255 pattern: \S description: Nickname for the card. cardholderId: type: string description: >- User ID of the team member who will hold the card. Use a userId returned by the team-members endpoint. planType: type: string enum: - subscription - topUp description: >- Funding plan. Defaults to subscription; topUp uses fixed reserved credit supplied in spendCap. category: anyOf: - type: string - type: 'null' description: ID of the card category to assign. isRevolving: type: boolean description: >- Whether the card draws funds from the revolving budget. Must be false or omitted when planType is topUp. expiresAt: anyOf: - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: 'null' description: >- Requested card expiration date in YYYY-MM-DD format. Time is unsupported. spendCap: type: object properties: amount: type: string pattern: ^(?!0+(\.0{1,2})?$)\d{1,15}(\.\d{1,2})?$ description: >- Positive decimal amount in major currency units, with up to two fractional digits. currency: type: string enum: - USD - HKD description: ISO 4217 alpha issuing currency code. required: - amount - currency description: >- Fixed credit reserved for a top-up card. Required when planType is topUp. spendControl: type: object properties: transaction: type: object properties: amount: type: string pattern: ^(?!0+(\.0{1,2})?$)\d{1,15}(\.\d{1,2})?$ description: >- Positive decimal amount in major currency units, with up to two fractional digits. currency: type: string enum: - USD - HKD description: ISO 4217 alpha issuing currency code. required: - amount - currency description: Maximum amount allowed for a single transaction. daily: type: object properties: amount: type: string pattern: ^(?!0+(\.0{1,2})?$)\d{1,15}(\.\d{1,2})?$ description: >- Positive decimal amount in major currency units, with up to two fractional digits. currency: type: string enum: - USD - HKD description: ISO 4217 alpha issuing currency code. required: - amount - currency description: Maximum amount the card can spend per day. weekly: type: object properties: amount: type: string pattern: ^(?!0+(\.0{1,2})?$)\d{1,15}(\.\d{1,2})?$ description: >- Positive decimal amount in major currency units, with up to two fractional digits. currency: type: string enum: - USD - HKD description: ISO 4217 alpha issuing currency code. required: - amount - currency description: Maximum amount the card can spend per week. monthly: type: object properties: amount: type: string pattern: ^(?!0+(\.0{1,2})?$)\d{1,15}(\.\d{1,2})?$ description: >- Positive decimal amount in major currency units, with up to two fractional digits. currency: type: string enum: - USD - HKD description: ISO 4217 alpha issuing currency code. required: - amount - currency description: Maximum amount the card can spend per month. yearly: type: object properties: amount: type: string pattern: ^(?!0+(\.0{1,2})?$)\d{1,15}(\.\d{1,2})?$ description: >- Positive decimal amount in major currency units, with up to two fractional digits. currency: type: string enum: - USD - HKD description: ISO 4217 alpha issuing currency code. required: - amount - currency description: Maximum amount the card can spend per year. allTime: type: object properties: amount: type: string pattern: ^(?!0+(\.0{1,2})?$)\d{1,15}(\.\d{1,2})?$ description: >- Positive decimal amount in major currency units, with up to two fractional digits. currency: type: string enum: - USD - HKD description: ISO 4217 alpha issuing currency code. required: - amount - currency description: Maximum amount the card can spend over its lifetime. description: Spending limits to apply to the card. restriction: type: object properties: time: anyOf: - type: object properties: start: anyOf: - type: string - type: 'null' description: >- Start of the allowed daily card-usage window in UTC, in HH:mm format. end: anyOf: - type: string - type: 'null' description: >- End of the allowed daily card-usage window in UTC, in HH:mm format. required: - start - end - type: 'null' description: Daily UTC window during which the card can be used. category: anyOf: - type: object properties: allow: type: boolean description: >- When true, only the listed categories are allowed; when false, the listed categories are blocked. ids: type: array items: type: string description: Card category IDs to allow or block. required: - allow - ids - type: 'null' description: Rules that allow or block transaction categories. description: Time and transaction-category restrictions to apply. message: anyOf: - type: string maxLength: 255 - type: 'null' description: Optional message stored with the card request. required: - type - title - cardholderId Card: type: object properties: id: type: string description: Unique card ID. type: type: string enum: - virtual - physical description: Card form factor. status: type: string enum: - pending - active - frozen - inactive - expiring - expired - terminated description: >- Derived card lifecycle status. Pending physical cards await activation; expiring physical cards are within 90 days of expiry. title: anyOf: - type: string - type: 'null' description: Card nickname. last4: anyOf: - type: string - type: 'null' description: Last four digits of the card number. expiresAt: anyOf: - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: 'null' description: Card expiration date in YYYY-MM-DD format. Time is unsupported. isRevolving: type: boolean description: Whether the card draws funds from the revolving budget. planType: anyOf: - type: string enum: - physical - subscription - topUp - type: 'null' description: >- Funding plan: physical identifies physical-card plans, subscription cards can share the revolving budget, and top-up cards use fixed reserved credit. category: anyOf: - type: string - type: 'null' description: ID of the card category assigned to the card. cardholder: type: object properties: userId: anyOf: - type: string - type: 'null' description: User ID of the team member assigned to the card. name: anyOf: - type: string - type: 'null' description: Full name of the team member assigned to the card. email: anyOf: - type: string - type: 'null' description: Email address of the team member assigned to the card. required: - userId - name - email description: Team member assigned to the card. spendCap: anyOf: - type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency - type: 'null' description: >- Fixed credit reserved for the card; used as the funding amount for top-up cards. spentAmount: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Total amount spent on the card. spendControl: type: object properties: limits: type: object properties: transaction: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount allowed for a single transaction. daily: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per day. weekly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per week. monthly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per month. yearly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend per year. allTime: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum amount the card can spend over its lifetime. description: Configured card-spending limits. spent: type: object properties: daily: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current day. weekly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current week. monthly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current month. yearly: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent during the current year. allTime: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Amount spent over the lifetime of the card. description: Spend accumulated against each configured period. atm: type: object properties: dailyWithdrawal: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum ATM withdrawal amount allowed per day. monthlyWithdrawal: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum ATM withdrawal amount allowed per month. yearlyWithdrawal: type: object properties: amount: type: string description: >- Decimal amount in major currency units, formatted with two fractional digits. currency: type: string description: ISO 4217 alpha currency code. required: - amount - currency description: Maximum ATM withdrawal amount allowed per year. dailyFrequency: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of ATM withdrawals allowed per day. monthlyFrequency: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of ATM withdrawals allowed per month. yearlyFrequency: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of ATM withdrawals allowed per year. description: ATM withdrawal amount and frequency limits. description: Card-spending and ATM controls with current period usage. restriction: type: object properties: time: anyOf: - type: object properties: start: anyOf: - type: string - type: 'null' description: >- Start of the allowed daily card-usage window in UTC, in HH:mm format. end: anyOf: - type: string - type: 'null' description: >- End of the allowed daily card-usage window in UTC, in HH:mm format. required: - start - end - type: 'null' description: Daily UTC window during which the card can be used. category: anyOf: - type: object properties: allow: type: boolean description: >- When true, only the listed categories are allowed; when false, the listed categories are blocked. ids: type: array items: type: string description: Card category IDs to allow or block. required: - allow - ids - type: 'null' description: Rules that allow or block transaction categories. description: Time and transaction-category restrictions applied to the card. createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Date and time the card was created, in ISO 8601 format. updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Date and time the card was last updated, in ISO 8601 format. required: - id - type - status - title - last4 - expiresAt - isRevolving - planType - category - cardholder - spendCap - spentAmount - spendControl - restriction - createdAt - updatedAt CardCreatedPending: type: object properties: id: type: string description: ID of the card created upstream. status: type: string const: pending description: Indicates that the created card is not yet available to retrieve. required: - id - status CardApprovalPending: type: object properties: approvalRequestId: type: string description: ID of the approval request created for this card. status: type: string const: pendingApproval description: Indicates that card creation is awaiting approval. required: - approvalRequestId - status ErrorResponse: type: object properties: statusCode: type: integer minimum: 100 maximum: 599 description: HTTP status code. type: type: string enum: - INVALID_REQUEST_ERROR - AUTHENTICATION_ERROR - PERMISSION_ERROR - RATE_LIMIT_ERROR - API_ERROR - UPSTREAM_ERROR description: Coarse error category; always present. code: description: Stable machine code; present for actionable errors. type: string message: type: string description: Human-readable explanation. param: description: Offending field for validation errors. type: string details: description: Structured extra context (e.g. validation issues). requestId: description: Correlation id for support. type: string required: - statusCode - type - message securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Enter your API key ````