Invite test customer
curl --request POST \
--url https://api.sandbox.natural.com/simulations/invite-customer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"data": {
"attributes": {
"agentIds": [
"agt_019cd1798d637a4da75dce386343931d"
],
"permissions": [
"wallets.create",
"wallets.withdraw",
"wallets.transfer"
],
"message": "Please review the agent access request.",
"type": "ORG"
}
}
}
'import requests
url = "https://api.sandbox.natural.com/simulations/invite-customer"
payload = { "data": { "attributes": {
"agentIds": ["agt_019cd1798d637a4da75dce386343931d"],
"permissions": ["wallets.create", "wallets.withdraw", "wallets.transfer"],
"message": "Please review the agent access request.",
"type": "ORG"
} } }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
attributes: {
agentIds: ['agt_019cd1798d637a4da75dce386343931d'],
permissions: ['wallets.create', 'wallets.withdraw', 'wallets.transfer'],
message: 'Please review the agent access request.',
type: 'ORG'
}
}
})
};
fetch('https://api.sandbox.natural.com/simulations/invite-customer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.natural.com/simulations/invite-customer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'attributes' => [
'agentIds' => [
'agt_019cd1798d637a4da75dce386343931d'
],
'permissions' => [
'wallets.create',
'wallets.withdraw',
'wallets.transfer'
],
'message' => 'Please review the agent access request.',
'type' => 'ORG'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.natural.com/simulations/invite-customer"
payload := strings.NewReader("{\n \"data\": {\n \"attributes\": {\n \"agentIds\": [\n \"agt_019cd1798d637a4da75dce386343931d\"\n ],\n \"permissions\": [\n \"wallets.create\",\n \"wallets.withdraw\",\n \"wallets.transfer\"\n ],\n \"message\": \"Please review the agent access request.\",\n \"type\": \"ORG\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.natural.com/simulations/invite-customer")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"attributes\": {\n \"agentIds\": [\n \"agt_019cd1798d637a4da75dce386343931d\"\n ],\n \"permissions\": [\n \"wallets.create\",\n \"wallets.withdraw\",\n \"wallets.transfer\"\n ],\n \"message\": \"Please review the agent access request.\",\n \"type\": \"ORG\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.natural.com/simulations/invite-customer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"attributes\": {\n \"agentIds\": [\n \"agt_019cd1798d637a4da75dce386343931d\"\n ],\n \"permissions\": [\n \"wallets.create\",\n \"wallets.withdraw\",\n \"wallets.transfer\"\n ],\n \"message\": \"Please review the agent access request.\",\n \"type\": \"ORG\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "agentDelegationInvitation",
"id": "adi_019cd1798d98577084df77e7ec734db5",
"attributes": {
"developerName": "Acme Payments",
"email": "test+7f21c4@fixtures.sandbox.natural.test",
"phone": null,
"url": "https://www.natural.com/connect/adi_019cd1798d98577084df77e7ec734db5",
"agentName": "Procurement Agent",
"permissions": [
"wallets.create",
"wallets.withdraw",
"wallets.transfer",
"party.read"
],
"limits": null,
"status": "pending",
"effectiveStatus": "pending",
"expiresAt": "2026-02-03T15:30:00.000Z",
"acceptedAt": null,
"declinedAt": null,
"cancelReason": null,
"redirectUrl": null,
"tags": {},
"createdAt": "2026-01-04T15:30:00.000Z",
"updatedAt": "2026-01-04T15:30:00.000Z"
},
"relationships": {
"agent": {
"data": {
"type": "agent",
"id": "agt_019cd1798d637a4da75dce386343931d"
}
},
"customerParty": {
"data": null
}
}
}
],
"meta": {
"customer": {
"partyId": "pty_019cd1798d6a0cf1a6076c62addacb4d",
"handle": "@brightside-labs",
"partyType": "ORG"
}
}
}Simulations
Sandbox: Invite a test customer
Create a test customer and a pending invitation for each agent you name
POST
/
simulations
/
invite-customer
Invite test customer
curl --request POST \
--url https://api.sandbox.natural.com/simulations/invite-customer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"data": {
"attributes": {
"agentIds": [
"agt_019cd1798d637a4da75dce386343931d"
],
"permissions": [
"wallets.create",
"wallets.withdraw",
"wallets.transfer"
],
"message": "Please review the agent access request.",
"type": "ORG"
}
}
}
'import requests
url = "https://api.sandbox.natural.com/simulations/invite-customer"
payload = { "data": { "attributes": {
"agentIds": ["agt_019cd1798d637a4da75dce386343931d"],
"permissions": ["wallets.create", "wallets.withdraw", "wallets.transfer"],
"message": "Please review the agent access request.",
"type": "ORG"
} } }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
attributes: {
agentIds: ['agt_019cd1798d637a4da75dce386343931d'],
permissions: ['wallets.create', 'wallets.withdraw', 'wallets.transfer'],
message: 'Please review the agent access request.',
type: 'ORG'
}
}
})
};
fetch('https://api.sandbox.natural.com/simulations/invite-customer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.natural.com/simulations/invite-customer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'attributes' => [
'agentIds' => [
'agt_019cd1798d637a4da75dce386343931d'
],
'permissions' => [
'wallets.create',
'wallets.withdraw',
'wallets.transfer'
],
'message' => 'Please review the agent access request.',
'type' => 'ORG'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.natural.com/simulations/invite-customer"
payload := strings.NewReader("{\n \"data\": {\n \"attributes\": {\n \"agentIds\": [\n \"agt_019cd1798d637a4da75dce386343931d\"\n ],\n \"permissions\": [\n \"wallets.create\",\n \"wallets.withdraw\",\n \"wallets.transfer\"\n ],\n \"message\": \"Please review the agent access request.\",\n \"type\": \"ORG\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.natural.com/simulations/invite-customer")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"attributes\": {\n \"agentIds\": [\n \"agt_019cd1798d637a4da75dce386343931d\"\n ],\n \"permissions\": [\n \"wallets.create\",\n \"wallets.withdraw\",\n \"wallets.transfer\"\n ],\n \"message\": \"Please review the agent access request.\",\n \"type\": \"ORG\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.natural.com/simulations/invite-customer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"attributes\": {\n \"agentIds\": [\n \"agt_019cd1798d637a4da75dce386343931d\"\n ],\n \"permissions\": [\n \"wallets.create\",\n \"wallets.withdraw\",\n \"wallets.transfer\"\n ],\n \"message\": \"Please review the agent access request.\",\n \"type\": \"ORG\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "agentDelegationInvitation",
"id": "adi_019cd1798d98577084df77e7ec734db5",
"attributes": {
"developerName": "Acme Payments",
"email": "test+7f21c4@fixtures.sandbox.natural.test",
"phone": null,
"url": "https://www.natural.com/connect/adi_019cd1798d98577084df77e7ec734db5",
"agentName": "Procurement Agent",
"permissions": [
"wallets.create",
"wallets.withdraw",
"wallets.transfer",
"party.read"
],
"limits": null,
"status": "pending",
"effectiveStatus": "pending",
"expiresAt": "2026-02-03T15:30:00.000Z",
"acceptedAt": null,
"declinedAt": null,
"cancelReason": null,
"redirectUrl": null,
"tags": {},
"createdAt": "2026-01-04T15:30:00.000Z",
"updatedAt": "2026-01-04T15:30:00.000Z"
},
"relationships": {
"agent": {
"data": {
"type": "agent",
"id": "agt_019cd1798d637a4da75dce386343931d"
}
},
"customerParty": {
"data": null
}
}
}
],
"meta": {
"customer": {
"partyId": "pty_019cd1798d6a0cf1a6076c62addacb4d",
"handle": "@brightside-labs",
"partyType": "ORG"
}
}
}Creates a synthetic Connect customer, visible only to your organization, and one
PENDING invitation for every agent you name. You provide agents only; no customer email, phone, or identity details.
Use the returned customer Party ID and invitation IDs to accept or decline each invitation. The customer grants no agent access and holds no funds until an invitation is accepted. See Simulate Connect.Authorizations
Headers
Was this page helpful?