Create an UMA invitation

Create an UMA invitation from a given platform customer.

POST /invitations

Create an UMA invitation

cURL

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": "$[e-mail]",
  "firstName": "Alice",
  "amountToSend": 12550,
  "expiresAt": "2025-09-01T14:30:00Z"
}
'

201

{
  "code": "019542f5",
  "createdAt": "2025-09-01T14:30:00Z",
  "url": "https://uma.me/i/019542f5",
  "inviterUma": "$[e-mail]",
  "status": "PENDING",
  "claimedAt": "2025-09-01T14:30:00Z",
  "expiresAt": "2025-09-01T14:30:00Z",
  "inviteeUma": "$[e-mail]",
  "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:

"$[e-mail]"

firstName · string

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

Example:

"Alice"

amountToSend · integer<int64>

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

201

application/json

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:

"$[e-mail]"

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:

"$[e-mail]"

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.

Show child attributes