Invite a customer

Ask a customer to authorize your agents, by a one-to-one customer invitation (adi_*) or a shareable invitation link (ivl_*). Either way, the customer chooses what to allow and which wallet the agent can use, and nothing moves until they accept. For the connection model, read the Customers overview.

Send the invitation

Invite a customer by email or phone with POST /customers/invitations. Natural emails the invitation; for a phone recipient, deliver attributes.url yourself. Each request takes up to 100 recipients and 50 agents. Invitations expire after 30 days unless you set expiresAt (up to 90 days).

In the sandbox, email and phone recipients return customer_invitation_recipient_unsupported_in_sandbox. Use POST /simulations/invite-customer, which creates a test customer and a pending invitation for each agent you name.

from naturalpay import Natural

client = Natural()
invitations = client.customers.create_invitations(
    recipients=[{"type": "email", "value": "ops@bistroroma.com"}],
    agents=[
        {
            "agentId": "agt_019cd1798d637a4da75dce386343931d",
            "permissions": [
                "payments.read",
                "payments.create",
                "external_accounts.create",
                "wallets.balance",
                "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: "ops@bistroroma.com" }],
  agents: [
    {
      agentId: "agt_019cd1798d637a4da75dce386343931d",
      permissions: [
        "payments.read",
        "payments.create",
        "external_accounts.create",
        "wallets.balance",
        "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 create-invitations --json '{
  "recipients": [{ "type": "email", "value": "ops@bistroroma.com" }],
  "agents": [{
    "agentId": "agt_019cd1798d637a4da75dce386343931d",
    "permissions": ["payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update"],
    "limits": { "perTransaction": 100000 }
  }]
}'

Invite ops@bistroroma.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": "ops@bistroroma.com" }],
        "agents": [{
          "agentId": "agt_019cd1798d637a4da75dce386343931d",
          "permissions": ["payments.read", "payments.create", "external_accounts.create", "wallets.balance", "wallets.update", "party.read", "party.update"],
          "limits": { "perTransaction": 100000 }
        }]
      }
    }
  }'

The response carries one invitation (adi_*) per recipient and agent, each with attributes.url, the same URL Natural emails the customer. You can also surface it inside your own product; either path lands on the same acceptance page. Check meta.failedRecipients; a recipient can fail while others succeed.

Send the customer back to your product

Set redirectUrl on the invitation to bring the customer back once they are connected. A customer new to Natural is sent there after they accept and finish setup; a customer who already has an account is sent there right after they accept. Nothing happens if they decline, or while their account is still under review.

{
  "data": {
    "attributes": {
      "recipients": [{ "type": "phone", "value": "+14155550123" }],
      "agents": [
        { "agentId": "agt_019cd1798d637a4da75dce386343931d", "permissions": ["payments.read"] }
      ],
      "redirectUrl": "sms:+14155550199"
    }
  }
}

redirectUrl accepts an https URL (including universal links), an app deep link such as acme://connected, or an sms: link that reopens a Messages or iMessage thread. Natural rejects http, javascript:, data: and similar schemes. The redirect is a convenience for the customer; use the agent_delegation_invitation.accepted webhook to trigger your own follow-up, such as texting the customer their next steps. 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. name is required and at most 32 characters. 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 invitation-links 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 }
        }]
      }
    }
  }'

GET /customers/invitation-links returns each link’s offer and status with a masked token and no URL. GET /customers/invitation-links/{linkId} returns one link the same way. status is ACTIVE or REVOKED; a link past expiresAt stays ACTIVE in the list but no longer connects anyone. If you lose a link’s URL, revoke the link and create a new one. POST /customers/invitation-links/{linkId}/revoke closes 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, when known, sourceId set to the link’s ID. Run one link per channel and count acceptances by sourceId to measure per-channel conversion. Redeeming the same offer again for an already-connected customer and agent is a no-op: Natural returns the existing connection and does not widen its permissions or limits. Disconnecting first does not revive the old acceptance; reconnect with a fresh invitation or offer.

What the customer does

Opens the link

They see who is requesting and which agents 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 on GET /customers. An invitation link keeps working for the next customer; one link can onboard any number of them. Their id is the party ID (pty_*) you pass to act as them. From there the agent moves money for them within the permissions and limit they granted.

A new customer answers the invitation during signup, but the connection is created only once Natural approves their account. agent_delegation_invitation.accepted and delegation.activated arrive at approval, so the invitation stays PENDING while the customer is under review. A customer who skips the invitation during signup, or whose application is rejected, is not connected; a skipped invitation stays PENDING until they accept it from their dashboard or it expires.

Overview

Common use cases

Products

Guides

Send the invitation

Send the customer back to your product

What the customer does

​Send the invitation

​Send the customer back to your product

​Share an invitation link

​What the customer does

Send the invitation

Send the customer back to your product

Share an invitation link

What the customer does