Create customer invitations

curl -X POST https://api.natural.co/agents/agentId/customers \
     -H "Idempotency-Key: Idempotency-Key" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "data": {
    "attributes": {
      "recipients": [
        {
          "type": "email",
          "value": "ops@example.com"
        },
        {
          "type": "phone",
          "value": "+14155550123"
        },
        {
          "type": "party_id",
          "value": "pty_4a8c9823f39c42a5b817556766551112"
        }
      ],
      "permissions": [
        "payments.create",
        "payments.read"
      ],
      "limits": {
        "perTransaction": 100000
      },
      "expiresAt": "2026-01-18T12:00:00.000Z"
    }
  }
}'

{
  "data": [
    {
      "type": "customerInvitation",
      "id": "adi_550e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "email",
          "value": "ops@example.com"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": null
        }
      }
    },
    {
      "type": "customerInvitation",
      "id": "adi_650e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "phone",
          "value": "+14155550123"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": null
        }
      }
    },
    {
      "type": "customerInvitation",
      "id": "adi_750e8400e29b41d4a716446655440000",
      "attributes": {
        "recipient": {
          "type": "party_id",
          "value": "pty_4a8c9823f39c42a5b817556766551112"
        },
        "status": "PENDING",
        "permissions": [
          "payments.create",
          "payments.read"
        ],
        "limits": {
          "perTransaction": 100000
        },
        "expiresAt": "2026-01-18T12:00:00.000Z",
        "createdAt": "2026-01-11T12:00:00.000Z",
        "updatedAt": "2026-01-11T12:00:00.000Z"
      },
      "relationships": {
        "agent": {
          "data": {
            "type": "agent",
            "id": "agt_3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
            "attributes": {
              "name": "Carrier Payment Agent",
              "description": "Autonomous agent that pays delivery carriers",
              "status": "ACTIVE"
            }
          }
        },
        "customerParty": {
          "data": {
            "type": "party",
            "id": "pty_4a8c9823f39c42a5b817556766551112"
          }
        }
      }
    }
  ],
  "meta": {
    "emailFailures": []
  }
}

Add or invite customer relationships for this agent.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

agentIdstringRequiredformat: "^agt_[0-9a-f]{32}$"

Request

This endpoint expects an object.

dataobjectRequired

Resource object

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed per window

X-RateLimit-Remaininginteger

Requests remaining in current window

X-RateLimit-Resetinteger

Unix timestamp when rate limit resets

Response

Successful Response

datalist of objects

Created customer invitation resources

metaobject

Batch invitation metadata

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

428

Precondition Error

429

Too Many Requests Error

500

Internal Server Error

501

Not Implemented Error

502

Bad Gateway Error

503

Service Unavailable Error