> ## Documentation Index > Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt > Use this file to discover all available pages before exploring further. # Get an UMA invitation by code > Retrieve details about an UMA invitation by its invitation code. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/grid/openapi.documented.yml get /invitations/{invitationCode} openapi: 3.1.0 info: title: Grid API description: > API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. version: '2025-10-13' contact: name: Lightspark Support email: support@lightspark.com license: name: Proprietary url: https://lightspark.com/terms servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server security: - BasicAuth: [] - AgentAuth: [] tags: - name: Platform Configuration description: >- Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard. - name: Customers description: >- Customer management endpoints for creating and updating customer information - name: KYC/KYB Verifications description: >- Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers. - name: Documents description: >- Endpoints for uploading and managing verification documents for customers and beneficial owners. Supports KYC and KYB document requirements. - name: Internal Accounts description: >- Internal account management endpoints for creating and managing internal accounts - name: External Accounts description: >- External account management endpoints for creating and managing external bank accounts - name: Same-Currency Transfers description: >- Endpoints for transferring funds between internal and external accounts with the same currency - name: Cross-Currency Transfers description: Endpoints for creating and confirming quotes for cross-currency transfers - name: Transactions description: Endpoints for retrieving transaction information - name: Webhooks description: Webhook endpoints and configuration for receiving notifications - name: Invitations description: Endpoints for creating, claiming and managing UMA invitations - name: Sandbox description: Endpoints to trigger test cases in sandbox - name: API Tokens description: Endpoints to programmatically manage API tokens - name: Exchange Rates description: >- Endpoints for retrieving cached foreign exchange rates. Rates are cached for approximately 5 minutes and include platform-specific fees. - name: Discoveries description: >- Endpoints for discovering available payment rails, banks, and providers for a given country and currency corridor. - name: Embedded Wallet Auth description: >- Endpoints for registering and verifying end-user authentication credentials (email OTP, OAuth, passkey) used to sign Embedded Wallet actions. - name: Agent Management description: >- Endpoints for creating and managing agents (experimental), called by the partner's backend using platform credentials. Covers the full agent lifecycle: creation, policy configuration, pausing, deletion, the device code installation flow, and approving or rejecting transactions initiated by agents. - name: Agent Operations description: >- Endpoints called by the agent itself using its own credentials (obtained via device code redemption). Scoped to the agent's associated customer — all requests automatically operate on behalf of that customer and are subject to the agent's policy. When an action requires approval, the resulting transaction enters a pending state and must be approved by the platform via `POST /transactions/{transactionId}/approve`. - name: Cards description: >- Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage card funding sources, and list card transactions. paths: /invitations/{invitationCode}: get: tags: - Invitations summary: Get an UMA invitation by code description: | Retrieve details about an UMA invitation by its invitation code. operationId: getInvitation parameters: - name: invitationCode in: path description: The code of the invitation to get required: true schema: type: string responses: '200': description: Invitation retrieved successfully content: application/json: schema: $ref: '#/components/schemas/UmaInvitation' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '404': description: Invitation not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' security: - BasicAuth: [] x-codeSamples: - lang: JavaScript source: >- import LightsparkGrid from '@lightsparkdev/grid'; const client = new LightsparkGrid({ username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted }); const umaInvitation = await client.invitations.retrieve('invitationCode'); console.log(umaInvitation.code); - lang: Python source: |- import os from grid import LightsparkGrid client = LightsparkGrid( username=os.environ.get("GRID_CLIENT_ID"), # This is the default and can be omitted password=os.environ.get("GRID_CLIENT_SECRET"), # This is the default and can be omitted ) uma_invitation = client.invitations.retrieve( "invitationCode", ) print(uma_invitation.code) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stainless-sdks/grid-go\"\n\t\"github.com/stainless-sdks/grid-go/option\"\n)\n\nfunc main() {\n\tclient := grid.NewClient(\n\t\toption.WithUsername(\"My Username\"),\n\t\toption.WithPassword(\"My Password\"),\n\t)\n\tumaInvitation, err := client.Invitations.Get(context.TODO(), \"invitationCode\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", umaInvitation.Code)\n}\n" - lang: Kotlin source: >- package com.lightspark.grid.example import com.lightspark.grid.client.LightsparkGridClient import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient import com.lightspark.grid.models.invitations.InvitationRetrieveParams import com.lightspark.grid.models.invitations.UmaInvitation fun main() { val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv() val umaInvitation: UmaInvitation = client.invitations().retrieve("invitationCode") } - lang: Ruby source: >- require "grid" lightspark_grid = Grid::Client.new(username: "My Username", password: "My Password") uma_invitation = lightspark_grid.invitations.retrieve("invitationCode") puts(uma_invitation) - lang: PHP source: |- invitations->retrieve('invitationCode'); var_dump($umaInvitation); } catch (APIException $e) { echo $e->getMessage(); } - lang: C# source: |- using System; using Grid; using Grid.Models.Invitations; LightsparkGridClient client = new(); InvitationRetrieveParams parameters = new() { InvitationCode = "invitationCode" }; var umaInvitation = await client.Invitations.Retrieve(parameters); Console.WriteLine(umaInvitation); - lang: CLI source: |- grid invitations retrieve \ --username 'My Username' \ --password 'My Password' \ --invitation-code invitationCode components: schemas: UmaInvitation: type: object required: - code - createdAt - inviterUma - status - url properties: code: type: string description: The unique code of the invitation example: 019542f5 createdAt: type: string format: date-time description: When the invitation was created example: '2025-09-01T14:30:00Z' claimedAt: type: string format: date-time description: When the invitation was claimed if it has been claimed example: '2025-09-01T14:30:00Z' url: type: string description: The URL where this invitation can be claimed. example: https://uma.me/i/019542f5 expiresAt: type: string format: date-time description: When the invitation expires (if at all) example: '2025-09-01T14:30:00Z' inviterUma: type: string description: The UMA address of the inviter example: $inviter@uma.domain inviteeUma: type: string description: The UMA address of the invitee example: $invitee@uma.domain status: type: string enum: - PENDING - CLAIMED - EXPIRED - CANCELLED description: The status of the invitation example: PENDING firstName: type: string description: >- The inviter's first name. Will be displayed when the recipient clicks the invite link example: Jane amountToSend: $ref: '#/components/schemas/CurrencyAmount' description: >- The amount to send to the invitee when the invitation is claimed. This is optional and if not provided, the invitee will not receive any amount. Note that the actual sending of the amount must be done by the inviter platform once the INVITATION_CLAIMED webhook is received. If the inviter platform either does not send the payment or the payment fails, the invitee will not receive this amount. This field is primarily used for display purposes on the claiming side of the invitation. This field is useful for "send-by-link" style customer flows where an inviter can send a payment simply by sharing a link without knowing the receiver's UMA address. Note that these sends can only be sender-locked, meaning that the sender will not know ahead of time how much the receiver will receive in the receiving currency. Error401: type: object required: - message - status - code properties: status: type: integer enum: - 401 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | | REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) | enum: - UNAUTHORIZED - INVALID_SIGNATURE - WALLET_SIGNATURE_MISSING - WALLET_SIGNATURE_MALFORMED - WALLET_SIGNATURE_BODY_MISMATCH - WALLET_SIGNATURE_INVALID - REQUEST_ID_MISSING message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error404: type: object required: - message - status - code properties: status: type: integer enum: - 404 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | TRANSACTION_NOT_FOUND | Transaction not found | | INVITATION_NOT_FOUND | Invitation not found | | USER_NOT_FOUND | Customer not found | | QUOTE_NOT_FOUND | Quote not found | | LOOKUP_REQUEST_NOT_FOUND | Lookup request not found | | TOKEN_NOT_FOUND | Token not found | | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found | | REFERENCE_NOT_FOUND | Reference not found | | UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP | enum: - TRANSACTION_NOT_FOUND - INVITATION_NOT_FOUND - USER_NOT_FOUND - QUOTE_NOT_FOUND - LOOKUP_REQUEST_NOT_FOUND - TOKEN_NOT_FOUND - BULK_UPLOAD_JOB_NOT_FOUND - REFERENCE_NOT_FOUND - UMA_NOT_FOUND message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error500: type: object required: - message - status - code properties: status: type: integer enum: - 500 description: HTTP status code code: type: string description: | | Error Code | Description | |------------|-------------| | GRID_SWITCH_ERROR | Grid switch error | | INTERNAL_ERROR | Internal server or UMA error | enum: - GRID_SWITCH_ERROR - INTERNAL_ERROR message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true CurrencyAmount: type: object required: - amount - currency properties: amount: type: integer format: int64 description: >- Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) example: 12550 currency: $ref: '#/components/schemas/Currency' Currency: type: object properties: code: type: string description: >- Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) example: USD name: type: string description: Full name of the currency example: United States Dollar symbol: type: string description: Symbol of the currency example: $ decimals: type: integer description: Number of decimal places for the currency minimum: 0 example: 2 securitySchemes: BasicAuth: type: http scheme: basic description: >- API token authentication using format `:` AgentAuth: type: http scheme: bearer description: >- Bearer token authentication for agent-scoped endpoints. The token is the `accessToken` returned when redeeming a device code via `POST /agents/device-codes/{code}/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy. ````