Capabilities and tasks

A capability tells you whether a customer can use a specific outcome, payment method, and direction. Open tasks tell you what must happen before that capability or a related resource can move forward.

Environment variables

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

Discover supported capabilities

Read the customer’s current options with GET /v3/customers/{customerId}/capabilities/supported:

List supported capabilities

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/supported" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Choose a response entry that matches the intended directions, method, and accountType. Continue only when availability is available or beta and eligibility.eligible is true. If institutions are returned, select only an ID from that response. Each institution entry includes a logoUrl and an isDefault flag. Use logoUrl to show the bank’s logo in a bank selection UI, and render your own generic bank icon when it is null. isDefault applies to this customer and capability only, not to the institution globally. GET /v3/institutions returns the same nullable logoUrl. Institution IDs are opaque, so handle new IDs without code changes.

Institution entry

{
  "institutions": [
    {
      "id": "jpmorgan",
      "name": "JPMorgan Chase",
      "bic": "CHASUS33",
      "logoUrl": "https://wallet.swipelux.com/bank-logos/jpmorgan.png",
      "countries": ["US"],
      "isDefault": true
    }
  ]
}

Store the selected data[].id as CAPABILITY_ID. Never copy a capability ID from another customer or environment.

Show why a bank is unavailable

Every entry also includes unavailableInstitutions. It lists the banks that offer this capability variant but do not accept this customer. Each entry has an id, a name, and a non-empty reasons array. Each reason uses the same shape as statusReason, with actor: "provider" and retryable: false. Use unavailableInstitutions to show customers why a bank is missing from your bank selection UI, for example by rendering the bank as disabled with the reason’s message.

Unavailable institution entry

{
  "unavailableInstitutions": [
    {
      "id": "lead_bank",
      "name": "Lead Bank",
      "reasons": [
        {
          "code": "jurisdiction_unsupported",
          "message": "The bank does not accept customers from a country on this customer's profile.",
          "actor": "provider",
          "retryable": false
        }
      ]
    }
  ]
}

Current reason codes:

Code	Meaning
`jurisdiction_unsupported`	The bank does not accept a country on the customer’s profile.
`legal_form_unsupported`	The bank does not accept the customer’s legal form.
`customer_type_unsupported`	The bank does not accept the customer’s type.

Handle unknown codes without code changes, because Swipelux can add new codes. A bank never appears in both institutions and unavailableInstitutions. unavailableInstitutions is always present and is [] on pooled and non-bank entries. A bank that is in neither list is left out for a reason unrelated to this customer. Naming an unavailable bank in a capability request still returns 422 capability_institutions_unsupported.

Pooled vs named account types

Bank capabilities come in two variants, encoded as the accountType field and the capability ID suffix (for example ach_pooled, wire_named):

pooled: shared Swipelux bank account. Each pay-in uses a unique reference to route funds. Pick this for one-time transfers.
named: dedicated bank details for the customer (virtual IBAN, dedicated ACH account). Reusable and shareable with any payer. Required for issued bank accounts.

Default to pooled. Use named only when the customer needs reusable bank details. Check the supported response for which variants are available. To receive SWIFT deposits or issue SWIFT bank details, use swift_named. swift_pooled supports payouts only, so check each option’s directions in the supported-capability response. A named SWIFT account returns reusable receiving details, including the bank’s BIC, a reference when one is required, and the beneficiary address when the bank supplies it. For issued ACH, Wire, and SWIFT accounts, you can pick an exact bank with institution and save the account request before the bank approves the customer. See Issue a bank account.

Request the capability

Request the selected option with POST /v3/customers/{customerId}/capabilities/{capabilityId}:

Request capability

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: capability-request-001" \
  --header "Content-Type: application/json" \
  --data '{}'

Use an explicit institutions array only when you need to select from IDs returned by the supported-capability response. Store data.status as CAPABILITY_STATUS, data.accountProvisioning as ACCOUNT_PROVISIONING_STATUS, data.openTaskIds as OPEN_TASK_IDS, and each data.applications[].id in APPLICATION_IDS.

Shared applications per bank

For named bank capabilities, each customer has one application case per bank. Pooled and platform capabilities use cases without a bank. Swipelux shares a case across every compatible capability you request:

One approval can cover several capabilities. For example, an approved case at one bank can make both an ACH and a wire capability ready.
A later request that matches an existing case reuses it. Swipelux opens no second application and adds no duplicate tasks.
Cases at different banks are independent. A rejection at one bank does not affect a case at another bank.

The request response tells you which case Swipelux used:

201 means the request opened a new application case.
200 means the request resolved to an application case the customer already had, for example a repeated request for a bank capability the customer already holds, or a request for a canceled capability. A repeated request for card or stablecoin_transfers still returns 409 capability_already_exists.
selectedApplicationId is a top-level field next to data with the ID of the case the request selected or opened. Swipelux omits it when the request did not select a case. An idempotent replay returns the same value.

Abbreviated response:

Response (abbreviated)

{
  "data": {
    "id": "ach_named",
    "status": "pending",
    "openTaskIds": ["tsk_000000000000000002"],
    "applications": [{ "id": "apl_000000000000000005", "status": "in_review" }]
  },
  "selectedApplicationId": "apl_000000000000000005"
}

For named capabilities, send the same institutions list again to select the same case, or send one institution ID to target that bank. A bank that terminally rejected the customer is skipped. When you name only that bank, or every eligible bank has rejected the customer, the request returns 409 capability_terminally_rejected. To try another bank after a rejection, request the capability again with that bank’s institution ID. A capability’s status reflects all of the customer’s related cases. For a named capability, one ready case whose approval covers it is enough to make it ready, whatever other banks report. A pooled capability also waits for its method check, reported in probes on the customer applications list.

List the customer’s applications

List every application case for the customer with GET /v3/customers/{customerId}/applications. Results are paginated with nextCursor and hasMore, and accept updatedAfter:

List applications

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/applications" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Each entry includes the application fields returned in a capability’s applications[], plus:

scope: named for a case at one bank, provider_pooled or platform for cases without a bank, or null for an unclassified historical case. institution is absent for provider_pooled and platform cases.
requestedScope[]: the capability keys requested against the case, each with its first requestedAt. Entries are never removed.
coverage[]: the capability keys the case’s approval covers, each with grantedAt and source. Coverage records scope, not authorization. Read the capability for its current status.
probes[]: method checks for the pooled capability keys the case covers, each with capabilityKey, status, and reason. Named keys never require a probe.
generation, predecessorApplicationId, and supersededByApplicationId: succession links. When supersededByApplicationId is set, the case was replaced. Follow that ID to the current case. A capability’s applications[] lists only current cases, so a replaced case appears only in this list.

Abbreviated response:

Response (abbreviated)

{
  "data": [
    {
      "id": "apl_000000000000000005",
      "status": "ready",
      "scope": "named",
      "institution": { "id": "jpmorgan", "name": "JPMorgan Chase", "bic": "CHASUS33" },
      "requestedScope": [
        { "capabilityKey": "ach_named", "requestedAt": "2026-09-20T10:00:00.000Z" }
      ],
      "coverage": [
        { "capabilityKey": "ach_named", "grantedAt": "2026-09-22T12:00:00.000Z", "source": "approval" },
        { "capabilityKey": "wire_named", "grantedAt": "2026-09-22T12:00:00.000Z", "source": "approval" }
      ],
      "probes": [],
      "generation": 1,
      "predecessorApplicationId": null,
      "supersededByApplicationId": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Complete current tasks

List tasks with GET /v3/customers/{customerId}/tasks, select IDs from OPEN_TASK_IDS, then read each current task with GET /v3/customers/{customerId}/tasks/{taskId}:

List open tasks

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Use the latest data.revision and data.requirements. Refetch the task immediately before submitting if either may have changed.

Reused profile evidence

For application intake tasks that accept direct API submission, Swipelux reuses information the customer already provided. When such a task is created or reconciled, Swipelux checks the customer profile and the customer’s own uploaded documents. Eligible requirements already backed by a usable profile value or document move to in_review instead of staying actionable. Profile updates and new document uploads trigger the same check for existing tasks. Only missing or incompatible values stay actionable. Reuse does not approve the evidence. Swipelux still reviews it. Explicit correction requests and previously answered requirements stay actionable. Owner and related-party documents are not reused, and requirements collected only through a hosted session keep their normal flow.

Render requirements

Build forms from the metadata each requirement returns rather than from requirement keys. A requirement can include an optional short title, and every request includes a prompt to show beneath the heading. Requirements with request.type: "profile" identify the profile field with profilePointer and add input metadata:

allowedValues: the permitted values for a scalar field, or for each item of an array field. Submit these values, not translated display labels.
valueSchema: a self-contained JSON Schema Draft 7 document that describes the input shape, nested properties, required fields, and structural constraints. Enums on objects appear on the relevant property, for example valueSchema.items.properties.type.enum for tax identifiers. Swipelux still applies cross-field and review validation after submission, so a value that passes the schema can still be rejected.
valueType: "country", or itemValueType: "country" for arrays: the field takes uppercase ISO 3166-1 alpha-2 codes. Nested country properties in valueSchema use format: "iso-3166-1-alpha-2". Use a standard country list for localized labels.

Requirement

{
  "id": "req_000000000000000010",
  "key": "account_purposes",
  "title": "Account purpose",
  "status": "action_required",
  "request": {
    "type": "profile",
    "prompt": "Select every purpose that applies.",
    "required": true,
    "profilePointer": "/financialProfile/accountPurposes",
    "valueType": "array",
    "itemValueType": "string",
    "allowedValues": ["business_expenses", "ecommerce", "payroll"],
    "valueSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "array",
      "items": { "enum": ["business_expenses", "ecommerce", "payroll"] }
    }
  }
}

This example shortens the value catalog; the API returns every permitted value. Some profile requirements have no published schema and omit valueSchema and allowedValues. Render those from prompt and valueType. Every open task includes a dueAt timestamp. When Swipelux authors a task without an explicit due date, dueAt defaults to exactly 31 days after the task’s createdAt. Treat dueAt as informational: you cannot set it through the API, and it does not trigger an automatic lifecycle transition. Only the separate deadline field, when present, causes an automatic transition.

Hosted actions

In the task-detail response, each entry in verificationSessions and tosSessions includes an action object. Task-list responses do not include these action links. Store each session id, then read action.kind before dispatching the customer; do not infer link availability from session status.

action.kind: "available" includes action.url and action.expiresAt (currently always null). Store action.url, send the customer to it, then read the task again. The session-level url and expiresAt fields contain the same values.
action.kind: "unavailable" means no link should be presented. The session-level url and expiresAt fields are absent. A session’s status alone does not determine which action kind you receive.

Verification session

{
  "data": {
    "verificationSessions": [
      {
        "id": "vfy_000000000000000003",
        "key": "identity_verification",
        "type": "identity_verification",
        "status": "action_required",
        "coveredRequirementIds": ["req_000000000000000011", "req_000000000000000012"],
        "action": {
          "kind": "available",
          "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
          "expiresAt": null
        },
        "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
        "expiresAt": null
      }
    ],
    "tosSessions": [
      {
        "id": "vfy_000000000000000004",
        "key": "terms_of_service",
        "type": "terms_of_service",
        "status": "completed",
        "action": { "kind": "unavailable" }
      }
    ]
  }
}

These are task-scoped actions, not a separate customer-verification lifecycle. Every verificationSessions[] entry in task reads and customer task detail includes coveredRequirementIds. It lists the IDs of the task’s live requirements that the session can fill. Use it to see which requirements a hosted session or an imported verification can settle. Fill every other requirement through API answers. For new individual intake tasks, the hosted identity session covers only the ID document, selfie, and proof of address. Proof-of-funds requirements, such as proof_of_funds, source_of_funds_document, named_source_of_funds_document, and sole_proprietor_document, are not part of the hosted session. Upload and submit those documents directly. Swipelux reviews them, and the task stays open until they are accepted. A hosted answer to a profile requirement for a structured value, such as an address or tax identifiers, must pass the same schema and constraint checks as a direct answer. When it does not, the requirement stays open. A requirement that Swipelux returns to action_required for this reason carries reviewFeedback.code: hosted_profile_direct_submission_required. Collect that value from the customer and submit it as an API answer.

Import an existing identity verification

If you already verify individuals in your own account with Swipelux’s identity verification provider, you can import that verification into the identity session of the customer’s intake task instead of sending the customer through the hosted flow. This option is for API integrations with individual customers only. Businesses and related parties are not supported. Before you import, set up sharing with your identity verification provider:

Ask Swipelux for its partner token, then add Swipelux as a sharing partner in your identity verification provider account.
For live verifications, generate a share token for Swipelux with recipient client ID (forClientId) swipelux.com_21030.
Send the token to Swipelux before it expires. Share tokens are opaque, single-use, at most 1,024 UTF-8 bytes, and expire after 20 minutes by default. Treat each token as a credential.

The task must be an individual intake task and offer the hosted verification session as a submission method. The session must have type: "identity_verification" and status: "action_required". The customer must not already have a verification in progress or completed with Swipelux, and an import must not already be running. Opening the hosted link starts verification, but reading the task does not. Then call POST /v3/customers/{customerId}/tasks/{taskId}/verification-sessions/{verificationSessionId}/share-token. The request needs the same accounts:write, customers:read, and customers:write permissions as task submissions, plus an Idempotency-Key:

Request body

{
  "shareToken": "<share token>"
}

Response

{
  "verificationSessionId": "vfy_000000000000000003",
  "status": "in_review"
}

Your provider copies the matching steps into Swipelux’s account, and the checks run again against the level the task requires. Swipelux never stores or logs the share token.

status: "in_review" means the checks are pending. When the checks finish, Swipelux settles the covered requirements the same way as for a hosted session.
status: "action_required" means steps are missing. The customer can finish them through the session’s existing hosted link, or you can submit the covered requirements directly.

The import fills only the requirements listed in coveredRequirementIds: the ID document, selfie, and, where the task requires it, proof of address. Submit profile answers, proof of funds, and other requirements as API answers. To replay a request, send it again with the same Idempotency-Key.

Status	Code	What to do
`409`	`verification_already_started`	This customer already has a verification in progress or completed with Swipelux, or an import is already running, for example because the customer opened a hosted link. Do not retry. Continue through the existing session.
`409`	`verification_session_not_allowed`	The task or session is not eligible for import. Do not retry. Read the task and use the methods it offers.
`422`	`share_token_rejected`	The identity verification provider refused the token, for example because it expired, was already used, or was issued for another recipient. Generate a new token for Swipelux and retry with a new `Idempotency-Key`.
`503`	`kyc_provider_unavailable`	With `retryable: true`, Swipelux had not sent the token yet. Retry after a delay. With `retryable: false`, the import may have happened but could not be confirmed. Do not resend the token. Continue through the session’s hosted link.

Upload documents

When a requirement requests a document, upload it with POST /v3/customers/{customerId}/documents:

Upload document

export DOCUMENT_PATH='/absolute/path/to/requested-document.pdf'

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/documents" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-document-001" \
  --form "file=@${DOCUMENT_PATH}"

Store the returned data.id as DOCUMENT_ID before submitting the answer that references it. To retrieve a stored file later, call GET /v3/customers/{customerId}/documents/{documentId}/download. Swipelux returns a url that downloads the file as an attachment and expires after one hour. Archived documents return 404.

API answers

Submit one complete answer set for the current revision with POST /v3/customers/{customerId}/tasks/{taskId}/submissions:

Submit task answers

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}/submissions" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: task-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "taskRevision": 3,
  "answers": [
    {
      "requirementId": "req_from_current_task",
      "answer": {
        "type": "text",
        "value": "Current answer"
      }
    }
  ]
}
JSON

Take every requirement ID and answer type from the latest task. If the API reports that the task changed, refetch it and rebuild the submission from the new revision.

Beneficial-owner prerequisite for businesses

Requesting a business capability that needs beneficial-owner evidence succeeds even when the customer has no qualifying owner yet. The capability is created as restricted with statusReason.code: tasks_due, and the business intake task requests the missing ownership facts, including the ownership structure. The same task carries a resource_reference requirement whose request includes qualification: "beneficial_owner":

Beneficial owner requirement

{
  "type": "resource_reference",
  "prompt": "Add or select a qualifying beneficial owner.",
  "required": true,
  "resourceType": "related_party",
  "qualification": "beneficial_owner"
}

A related party qualifies when it is an active person party of the same customer with a supplied ownership percentage of at least 25, or with ownership.declared: true and no percentage. The requirement is derived from the current related-party roster, so you usually do not answer it directly:

Creating or updating a qualifying related party meets the requirement in the same reevaluation and opens that owner’s own profile and document work. See Add business related parties.
You can also reference a qualifying party explicitly with a resource_reference answer that carries its relatedPartyId.
The requirement stays listed in the current task after it is met. When no other obligation remains open, the task becomes satisfied.
Archiving the last qualifying party, or removing the facts that qualified it, reopens the requirement, even after the task was satisfied.

Continue when the capability is ready

Read the capability again with GET /v3/customers/{customerId}/capabilities/{capabilityId}:

Refetch capability

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Replace the stored status, account-provisioning status, and task IDs with the latest response. Capability status reports whether the entitlement is approved. For a capability that issues an account, accountProvisioning separately reports whether that account is not_started, in_progress, issued, or failed; a capability that does not issue an account returns not_applicable. While the capability is pending, two of the statusReason.code values it can report show whether a review is underway. preparing_submission means Swipelux is still preparing an application for submission and no review is underway, even if another bank’s application is rejected or needs attention. review_in_progress means a review is underway, for example while an application is in_review or a hosted verification is open. Both use resolution: wait. A change between these codes keeps the status pending, so it sends no capability.status_changed event. Read the capability to see the current code. A capability can also be restricted with statusReason.code: offer_unavailable and resolution: contact_support. Swipelux returns this code when an approved application covers the capability but no current offer permits it. The application is already approved, so waiting does not change the capability. Contact Swipelux support instead of polling. This code replaces related_application_action_required and resolution: wait in this case. Open customer tasks still take precedence, so complete any current tasks first.

Capability restricted by offer availability

{
  "status": "restricted",
  "statusReason": {
    "code": "offer_unavailable",
    "resolution": "contact_support",
    "message": "The approved Application covers this capability, but no current offer permits it. Contact support."
  }
}

Continue only when the current capability status permits the account, quote, or transfer you intend to create. When the flow needs an issued account, also wait for accountProvisioning to become issued. Next, choose the matching journey in Common flows.

Get started

Onboard customers

Build money flows

Launch

Capabilities and tasks

Discover supported capabilities

Show why a bank is unavailable

Pooled vs named account types

Request the capability

Shared applications per bank

List the customer’s applications

Complete current tasks

Reused profile evidence

Render requirements

Hosted actions

Import an existing identity verification

Upload documents

API answers

Beneficial-owner prerequisite for businesses

Continue when the capability is ready

​Discover supported capabilities

​Show why a bank is unavailable

​Pooled vs named account types

​Request the capability

​Shared applications per bank

​List the customer’s applications

​Complete current tasks

​Reused profile evidence

​Render requirements

​Hosted actions

​Import an existing identity verification

​Upload documents

​API answers

​Beneficial-owner prerequisite for businesses

​Continue when the capability is ready

Discover supported capabilities

Show why a bank is unavailable

Pooled vs named account types

Request the capability

Shared applications per bank

List the customer’s applications

Complete current tasks

Reused profile evidence

Render requirements

Hosted actions

Import an existing identity verification

Upload documents

API answers

Beneficial-owner prerequisite for businesses

Continue when the capability is ready