API Reference

A human-readable summary of all Float Service API endpoints. For the full interactive OpenAPI specification with request/response schemas, see API Specification.

Overview

All endpoints are served by the prod-float-service-api Lambda behind API Gateway at https://float-service.api.floatme.io/v1.

Authorization is enforced at the API Gateway level:

  • IAM — internal FloatMe services authenticate with AWS IAM credentials.

  • JWT — mobile app requests are authenticated with a user JWT via the global FloatMe API gateway.

All paths are prefixed with /{user_id} scoped to the user being operated on.

Float Management

Method Path Description

POST

/{user_id}/floats

Create a float. Runs fraud, underwriting, and subscription checks before submitting disbursement. See Disbursement for the full validation sequence.

GET

/{user_id}/floats

Return all floats for a user, ordered by due date descending. Accepts optional include_payback_date query parameter.

GET

/{user_id}/floats/active

Return floats in active statuses only: RETRY, DEFAULTED, SCHEDULING, ACHSENT, UNCOLLECTABLE.

GET

/{user_id}/floats/{float_id}

Return a single float by ID.

PATCH

/{user_id}/floats/{float_id}

Update a float’s ach_debit_status and ach_debit_date. Writes a SUPPORT entry to the collection history log.

GET

/{user_id}/floats/{float_id}/collection-history

Return all collection attempt log entries for a float from the collection-history DynamoDB table.

POST /{user_id}/floats — Request Body

Field Type Required Description

loan_amount

number

Yes

Requested advance amount.

loan_type

string enum

Yes

PINLESS, NORMAL, or RTP.

app_version

string

Yes

Client app build version. Validated against the configured minimum.

custom_payback_date

string

No

ISO 8601 date. Must fall within the allowed custom payback window; see GrowthBook flag floats.custom_payback_days_window.

Bypass Management

Method Path Description

GET

/{user_id}/floats/bypass

Return the active requirements bypass record for a user. Returns 404 if none exists.

POST

/{user_id}/floats/bypass

Create or replace the bypass record for a user. Required body fields: user_id, expiration_date (YYYY-MM-DD), reason.

DELETE

/{user_id}/floats/bypass

Remove the bypass record for a user.

See Bypass & Payback for full bypass semantics and effect on float creation.

Payback

Method Path Description

POST

/{user_id}/floats/{float_id}/payback

Submit a manual payback for an active float. Required body field: payback_option (string — "ACH" or pinless). Float must be at least 24 hours old and not already COMPLETED or ACHSENT.

POST

/{user_id}/floats/payback/reactivate

Pay off all past-due active floats for a user during account reactivation. Always uses pinless debit. Returns amounts collected, remaining, and masked card number.

See Bypass & Payback for flow details and Float Lifecycle for the reactivation payback multi-float sequence.

Administration

Method Path Description

POST

/{user_id}/floats/ban

Default all RETRY and SCHEDULING floats for a banned user. No request body. Writes a collection log entry for each affected float.

PUT

/qa/floats/create

(Test environments only) Batch-create float records with associated collection history and payment records. Restricted to the test-qa-api caller identity.

Error Responses

All error responses use a common shape:

{
  "message": "human-readable description",
  "status_code": 400,
  "error_code": "INVALID_REQUEST_BODY"
}

Generic Error Codes

Used by all endpoints except POST /{user_id}/floats.

error_code HTTP Status Meaning

ENTITY_NOT_FOUND

404

The requested resource does not exist.

INVALID_REQUEST_BODY

400

The request body failed schema validation.

INVALID_CALLER

403

The caller is not authorized to perform this operation.

UNEXPECTED_ERROR

500

An unexpected internal error occurred.

Float Creation Error Codes

POST /{user_id}/floats returns a CreateFloatErrorCode instead of the generic codes above.

error_code HTTP Status Meaning

USER_NOT_ACTIVE

403

User is not in ACTIVE status.

PENDING_CANCELLATION

403

User’s membership is in PENDING_CANCELLATION or CANCELLED state.

EMAIL_NOT_VERIFIED

403

Email verification is enforced and the user’s email is not verified.

ACCOUNT_PAST_DUE

403

User’s subscription is in PAST_DUE or STALE status.

NO_MAIN_ACCOUNT

403

No linked main bank account found via the Transactions Service.

FLOAT_NOT_ALLOWED

403

Underwriting indicates the user is not eligible for a float.

OPEN_FLOAT

400

User already has an outstanding float.

RECENT_FLOAT

400

User took a float within the last 24 hours.

OPEN_INSTALLMENT_LOAN

400

User has an open or defaulted installment loan via the LOC Service.

INVALID_FLOAT_AMOUNT

400

Requested amount exceeds the configured maximum.

INVALID_APP_VERSION

400

App build version is below the configured minimum.

FRAUD_CHECK_FAILED

400

The Payments Service fraud check rejected the request.

NOT_APPROVED

403

Underwriting did not approve the requested amount and no bypass is active.

INVALID_PAYBACK_DATE

400

The provided custom_payback_date is outside the allowed window.

FAILED_TO_SEND_FUNDS

500

The Payments Service returned an error when submitting the disbursement.

INVALID_REQUEST

400

General request validation failure.

UNKNOWN_ERROR

500

An unexpected error occurred during float creation.

Related Pages