Invite a customer

There are two ways to ask a customer to approve your agents: a customer invitation, sent to one person by email or phone, or an invitation link, an open-ended shareable invitation that can connect many customers. Either way, the customer chooses what to allow and which wallet the agent can use, and nothing moves until they accept.

Send the invitation

Invite your customer over email with POST /customers/invitations. Natural handles the customer communication.

In Sandbox, use POST /simulations/invite-customer when you want Natural to create a hidden synthetic customer and you only want to choose agents.

from naturalpay import Natural

client = Natural()
invitations = client.customers.create_invitations(
    recipients=[{"type": "email", "value": "customer@example.com"}],
    agents=[
        {
            "agentId": "agt_019cd1798d637a4da75dce386343931d",
            "permissions": [
                "payments.read",
                "payments.create",
                "external_accounts.create",
                "wallets.read",
                "wallets.update",
                "party.read",
                "party.update",
            ],
            "limits": {"perTransaction": 100_000},
        }
    ],
)

for invitation in invitations.data:
    print(invitation.id, invitation.attributes.url)

import Natural from "@naturalpay/sdk";

const client = new Natural();
const invitations = await client.customers.createInvitations({
  recipients: [{ type: "email", value: "customer@example.com" }],
  agents: [
    {
      agentId: "agt_019cd1798d637a4da75dce386343931d",
      permissions: [
        "payments.read",
        "payments.create",
        "external_accounts.create",
        "wallets.read",
        "wallets.update",
        "party.read",
        "party.update",
      ],
      limits: { perTransaction: 100_000 },
    },
  ],
});

for (const invitation of invitations.data) {
  console.log(invitation.id, invitation.attributes.url);
}

natural customers createInvitations --json '{
  "recipients": [{ "type": "email", "value": "customer@example.com" }],
  "agents": [{
    "agentId": "agt_019cd1798d637a4da75dce386343931d",
    "permissions": ["payments.read", "payments.create", "external_accounts.create", "wallets.read", "wallets.update", "party.read", "party.update"],
    "limits": { "perTransaction": 100000 }
  }]
}'

Invite customer@example.com to connect my Procurement Agent.
Let it run money end to end for them, limited to $1,000 per transaction.

curl -X POST https://api.natural.com/customers/invitations \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "recipients": [{ "type": "email", "value": "customer@example.com" }],
        "agents": [{
          "agentId": "agt_019cd1798d637a4da75dce386343931d",
          "permissions": ["payments.read", "payments.create", "external_accounts.create", "wallets.read", "wallets.update", "party.read", "party.update"],
          "limits": { "perTransaction": 100000 }
        }]
      }
    }
  }'

Each invitation in the response carries attributes.url, the same /connect link Natural emails the recipient. Surface it in your own product or send it through your own channel when you own the customer communication; either path lands on the same acceptance page. An invitation link is the same offer with no recipient: create it once, share the URL anywhere, and any customer who opens it can accept. Create one with POST /customers/invitation-links, naming the agents it offers and what each one asks for. The create response is the only place the API returns the shareable url, so store it then. expiresAt is optional; a link without one stays open until you revoke it.

from naturalpay import Natural

client = Natural()
link = client.invitation_links.create(
    name="Q3 carrier onboarding",
    proposed_agents=[
        {
            "agentId": "agt_019cd1798d637a4da75dce386343931d",
            "permissions": ["payments.read", "payments.create"],
            "limits": {"perTransaction": 100_000},
        }
    ],
)

print(link.data.attributes.url)

import Natural from "@naturalpay/sdk";

const client = new Natural();
const link = await client.invitationLinks.create({
  name: "Q3 carrier onboarding",
  proposedAgents: [
    {
      agentId: "agt_019cd1798d637a4da75dce386343931d",
      permissions: ["payments.read", "payments.create"],
      limits: { perTransaction: 100_000 },
    },
  ],
});

console.log(link.data.attributes.url);

natural invitationLinks create --json '{
  "name": "Q3 carrier onboarding",
  "proposedAgents": [{
    "agentId": "agt_019cd1798d637a4da75dce386343931d",
    "permissions": ["payments.read", "payments.create"],
    "limits": { "perTransaction": 100000 }
  }]
}'

Create an invitation link named "Q3 carrier onboarding" offering my Procurement Agent
with payments access, limited to $1,000 per transaction.

curl -X POST https://api.natural.com/customers/invitation-links \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "name": "Q3 carrier onboarding",
        "proposedAgents": [{
          "agentId": "agt_019cd1798d637a4da75dce386343931d",
          "permissions": ["payments.read", "payments.create"],
          "limits": { "perTransaction": 100000 }
        }]
      }
    }
  }'

List and get return each link’s offer and status with a masked token and no URL. If you lose a link’s URL, revoke the link and create a new one. Revoke a link to close the offer. It stops accepting new customers immediately; customers it already connected are untouched, because a link only ever offers, it never grants. Every connection made through a link records its source: the delegation.activated webhook carries sourceType: "link" and sourceId set to the link’s ID. Run one link per channel and count acceptances by sourceId to measure per-channel conversion.

What the customer does

Opens the link

They see who is requesting and which agents will act. A revoked or expired invitation link shows only that it is no longer available.

Onboards if new

A customer new to Natural creates an account and verifies as part of accepting. Natural handles the compliance.

Picks a wallet and accepts

They choose which wallet the agent may use.

The invitation flips to ACCEPTED and the customer shows up in your customers. An invitation link keeps working for the next customer; one link can onboard any number of them. Their id is the party ID you pass to act as them. From there the agent moves money for them within the permissions and limit they granted.

Overview

Common use cases

Products

Guides

Send the invitation

What the customer does

​Send the invitation

​Share an invitation link

​What the customer does

Send the invitation

Share an invitation link

What the customer does