Skip to main content
POST
/
invitations
Create an UMA invitation from a given platform customer.
curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/invitations \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inviterUma": "$inviter@uma.domain",
  "firstName": "Alice",
  "amountToSend": 12550,
  "expiresAt": "2025-09-01T14:30:00Z"
}'
{
  "code": "019542f5",
  "createdAt": "2025-09-01T14:30:00Z",
  "claimedAt": "2025-09-01T14:30:00Z",
  "url": "https://uma.me/i/019542f5",
  "expiresAt": "2025-09-01T14:30:00Z",
  "inviterUma": "$inviter@uma.domain",
  "inviteeUma": "$invitee@uma.domain",
  "status": "PENDING",
  "firstName": "Jane",
  "amountToSend": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  }
}

Authorizations

​
Authorization
string
header
required

API token authentication using format <api token id>:<api client secret>

Body

application/json
​
inviterUma
string
required

The UMA address of the customer creating the invitation

Example:

"$inviter@uma.domain"

​
firstName
string

First name of the invitee to show as part of the invite

Example:

"Alice"

​
amountToSend
integer

An amount to send (in the smallest unit of the customer's currency) 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.

Example:

12550

​
expiresAt
string<date-time>

When the invitation expires (if at all)

Example:

"2025-09-01T14:30:00Z"

Response

Invitation created successfully

​
code
string
required

The unique code of the invitation

Example:

"019542f5"

​
createdAt
string<date-time>
required

When the invitation was created

Example:

"2025-09-01T14:30:00Z"

​
url
string
required

The URL where this invitation can be claimed.

Example:

"https://uma.me/i/019542f5"

​
inviterUma
string
required

The UMA address of the inviter

Example:

"$inviter@uma.domain"

​
status
enum<string>
required

The status of the invitation

Available options:
PENDING,
CLAIMED,
EXPIRED,
CANCELLED
Example:

"PENDING"

​
claimedAt
string<date-time>

When the invitation was claimed if it has been claimed

Example:

"2025-09-01T14:30:00Z"

​
expiresAt
string<date-time>

When the invitation expires (if at all)

Example:

"2025-09-01T14:30:00Z"

​
inviteeUma
string

The UMA address of the invitee

Example:

"$invitee@uma.domain"

​
firstName
string

The inviter's first name. Will be displayed when the recipient clicks the invite link

Example:

"Jane"

​
amountToSend
object

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.

⌘I