> ## Documentation Index > Fetch the complete documentation index at: https://docs.perflo-api.proofof.tech/llms.txt > Use this file to discover all available pages before exploring further. # Create a confirmation intent > Creates a five-minute, fresh-authenticated confirmation intent bound to one exact irreversible request. ## OpenAPI ````yaml /openapi.json post /v1/confirmation-intents openapi: 3.1.0 info: description: The public API for Perflo financial agents. license: identifier: LicenseRef-Perflo-Proprietary name: Proprietary title: Perflo Financial Agents API version: 1.0.0 servers: - url: https://api.perflo.ai security: [] tags: - description: Existing fiat accounts and provider-stated withdrawal limits. name: accounts - description: Sanitized customer-wide cash activity without provider identifiers. name: activity - description: The current grant, delegated policy, and local confirmation controls. name: authorization - description: Safe beneficiary resources, payout schemas, and virtual-account economics. name: beneficiaries - description: Non-sensitive card lifecycle state and card activity. name: cards - description: Safe display preferences for the current pairwise subject. name: identity - description: >- Normalized verification state without identity evidence or provider details. name: kyc - description: >- Durable financial operation status owned by the current subject and client. name: operations - description: API-owned outbound notifications for durable operation transitions. name: operation-webhooks - description: Indicative service purchase quotes and released purchase state. name: purchases - description: Public asset and fiat-price reference data. name: reference-data - description: Services and capabilities available under the effective grant policy. name: services - description: Spending-account state and durable withdrawal operations. name: spending - description: Gateway health and public API metadata endpoints. name: system - description: Indicative transfer economics that cannot be executed. name: transfer-quotes paths: /v1/confirmation-intents: post: tags: - authorization summary: Create a confirmation intent description: >- Creates a five-minute, fresh-authenticated confirmation intent bound to one exact irreversible request. operationId: createConfirmationIntent parameters: - $ref: '#/components/parameters/PerfloRequestId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfirmationTarget' responses: '201': description: The one-use confirmation intent. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' content: application/json: schema: $ref: '#/components/schemas/ConfirmationIntent' '401': description: The access token or DPoP proof is invalid. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' WWW-Authenticate: $ref: '#/components/headers/PerfloAuthenticate' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: The grant lacks action authority or fresh authentication. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' WWW-Authenticate: $ref: '#/components/headers/PerfloAuthenticate' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '409': description: The provider binding or grant changed. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '422': description: The target request is invalid. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '429': description: The shared request limit was exceeded. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' Retry-After: $ref: '#/components/headers/PerfloRetryAfter' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: The response contract failed. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '503': description: Confirmation state is unavailable. headers: X-Request-Id: $ref: '#/components/headers/PerfloRequestId' DPoP-Nonce: $ref: '#/components/headers/PerfloDpopNonce' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - PerfloDPoPProof: [] PerfloOAuth: - authorization:read components: parameters: PerfloRequestId: description: >- Optional caller request identifier. Unsafe values are replaced with a generated UUID. in: header name: X-Request-Id required: false schema: pattern: ^[A-Za-z0-9._~-]{8,128}$ type: string schemas: ConfirmationTarget: oneOf: - type: object properties: action: type: string const: beneficiaries.create description: Create a beneficiary with sensitive payout-schema answers. request: $ref: '#/components/schemas/BeneficiaryCreate' description: The complete target beneficiary-creation request. required: - action - request additionalProperties: false - type: object properties: action: type: string const: cards.create description: Reserve a new card. request: type: object properties: card_type: description: Optional normalized card type. type: string minLength: 1 maxLength: 128 pattern: ^[a-z0-9]+(?:[._-][a-z0-9]+)*$ nickname: description: Optional card nickname. type: string minLength: 1 maxLength: 128 additionalProperties: false description: The complete target card-reservation request. required: - action - request additionalProperties: false - type: object properties: action: type: string const: cards.freeze description: Freeze an existing card. request: type: object properties: card_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: API-owned opaque card identifier. required: - card_id additionalProperties: false description: The complete target card-freeze request. required: - action - request additionalProperties: false - type: object properties: action: type: string const: spending.withdraw description: Withdraw held spending funds. request: type: object properties: amount: anyOf: - type: object properties: amount: type: string pattern: ^(?:0\.0*[1-9]\d*|[1-9]\d*(?:\.\d+)?)$ description: >- Positive canonical USD amount with at most six decimal places. currency: type: string const: USD description: US dollars. required: - amount - currency additionalProperties: false - type: 'null' description: Amount to withdraw, or null for all held funds. required: - amount additionalProperties: false description: The complete target spending-withdrawal request. required: - action - request additionalProperties: false description: One irreversible action and its complete target request. type: object ConfirmationIntent: type: object properties: action: type: string enum: - beneficiaries.create - cards.create - cards.freeze - spending.withdraw description: The irreversible action bound to this intent. expires_at: 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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: Exact expiry of this five-minute intent. id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Opaque one-use confirmation-intent identifier. required: - action - expires_at - id additionalProperties: false description: A five-minute, one-use API-owned confirmation intent. ProblemDetails: type: object properties: type: type: string format: uri description: Stable URL identifying the problem class. title: type: string minLength: 1 description: Short human-readable problem title. status: type: integer minimum: 400 maximum: 599 description: HTTP status code for this occurrence. detail: type: string minLength: 1 description: Human-readable occurrence detail. instance: type: string pattern: ^\/.* description: Request path identifying this problem occurrence. code: type: string pattern: ^[a-z][a-z0-9_]*$ description: Stable machine-readable Perflo error code. fields: anyOf: - type: array items: $ref: '#/components/schemas/ProblemField' - type: 'null' description: >- Field-level failures, or null when the problem is not field-specific. request_id: type: string pattern: ^[A-Za-z0-9._~-]{8,128}$ description: Request identifier used to correlate API responses with server logs. retryable: type: boolean description: Whether repeating the identical request can safely succeed. submission_uncertain: type: boolean description: >- Whether an upstream write may have landed and must not be resubmitted. required: - type - title - status - detail - instance - code - fields - request_id - retryable - submission_uncertain additionalProperties: false description: >- RFC 9457 problem details with stable Perflo correlation and retry semantics. BeneficiaryCreate: type: object properties: name: type: string minLength: 1 maxLength: 200 description: Beneficiary legal name. nickname: description: Optional owner-private beneficiary nickname. type: string minLength: 1 maxLength: 80 country: type: string pattern: ^[A-Z]{2}$ description: Payout country. currency: type: string pattern: ^[A-Z]{3}$ description: Payout currency. payout_schema_id: type: string minLength: 1 maxLength: 512 description: Selected payout schema. purpose_code: description: Optional provider purpose code. type: string minLength: 1 maxLength: 128 is_external: type: boolean description: Whether this is a third-party payee. details: type: object propertyNames: type: string minLength: 1 maxLength: 256 additionalProperties: $ref: '#/components/schemas/JsonValue' description: Payout-schema answers. required: - name - country - currency - payout_schema_id - is_external - details additionalProperties: false description: A request to create one provider beneficiary. ProblemField: type: object properties: message: type: string minLength: 1 description: Human-readable validation failure. path: type: string minLength: 1 description: Dot-delimited path to the invalid field. required: - message - path additionalProperties: false description: One field-level request validation failure. JsonValue: description: A JSON value. anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' headers: PerfloRequestId: description: Request identifier echoed on every API response. schema: pattern: ^[A-Za-z0-9._~-]{8,128}$ type: string PerfloDpopNonce: description: >- Current protected-resource nonce for the next DPoP proof. Replace any previously stored resource nonce. schema: pattern: ^[A-Za-z0-9_-]{43}$ type: string PerfloAuthenticate: description: >- OAuth DPoP authentication challenge. Inspect the challenge before deciding whether to request a new token or proof. schema: type: string PerfloRetryAfter: description: Whole seconds to wait before sending another request to this endpoint. schema: minimum: 1 type: integer securitySchemes: PerfloDPoPProof: description: >- Per-request RFC 9449 DPoP proof signed with ES256. Protected requests use `Authorization: DPoP your_access_token_here`. Create a new proof for the exact method and normalized target URI, and include the server nonce when challenged. in: header name: DPoP type: apiKey PerfloOAuth: description: >- OAuth 2.0 with RFC 9700 security practices. Discover exact environment endpoints from `/.well-known/openid-configuration` and `/.well-known/oauth-authorization-server`, and discover the resource from `/.well-known/oauth-protected-resource`. Authorization-code clients use PKCE `S256`, the exact environment resource, `nonce` with `openid`, and DPoP binding. Confidential clients also require PAR and `private_key_jwt`. Access and refresh tokens are sender-constrained with DPoP. `purchases:execute` is unavailable and omitted from this scope registry. flows: authorizationCode: authorizationUrl: https://api.perflo.ai/oauth/authorize scopes: accounts:read: >- Read the resource owner’s financial accounts and withdrawal limits. activity:read: Read the resource owner’s sanitized financial activity. authorization:read: Read the current OAuth grant and effective delegated policy. beneficiaries:read: Read beneficiaries and beneficiary reference data. beneficiaries:write: Create beneficiaries through durable operations. cards:manage: Create and manage non-sensitive card lifecycle state. cards:read: Read non-sensitive card state and activity. identity:read: Read the resource owner’s safe display preferences. kyc:read: Read the resource owner’s normalized verification status. operations:read: Read operations owned by the same subject and client. purchases:read: Read quote-bound service purchase state. services:read: Read services available under the effective grant policy. spending:read: Read the resource owner’s spending account. spending:withdraw: Create spending-account withdrawals through durable operations. transfers:quote: Create non-executable transfer estimates. tokenUrl: https://api.perflo.ai/oauth/token clientCredentials: scopes: accounts:read: >- Read the resource owner’s financial accounts and withdrawal limits. activity:read: Read the resource owner’s sanitized financial activity. authorization:read: Read the current OAuth grant and effective delegated policy. beneficiaries:read: Read beneficiaries and beneficiary reference data. beneficiaries:write: Create beneficiaries through durable operations. cards:manage: Create and manage non-sensitive card lifecycle state. cards:read: Read non-sensitive card state and activity. identity:read: Read the resource owner’s safe display preferences. kyc:read: Read the resource owner’s normalized verification status. operations:read: Read operations owned by the same subject and client. purchases:read: Read quote-bound service purchase state. services:read: Read services available under the effective grant policy. spending:read: Read the resource owner’s spending account. spending:withdraw: Create spending-account withdrawals through durable operations. transfers:quote: Create non-executable transfer estimates. tokenUrl: https://api.perflo.ai/oauth/token type: oauth2 x-token-type: DPoP ````