Skip to main content
The Natural API is REST-based and follows a simplified JSON:API structure. We use JSON:API to specify how our servers should respond to requests, and use a modified structure described below in order to specify how requests should be made to our servers.

​
Requests

To create or update a resource, wrap your fields in data.attributes. No type, id, or relationships needed — the type is inferred from the endpoint and the ID is assigned by the server.

​
Creating a resource

Send a POST request with a data object containing attributes: 
// POST /api/payments
{
  "data": {
    "attributes": {
      "amount": 500000,
      "currency": "USD",
      "counterparty": "pty_019cd1798d627ad9bc302511c4f2c115",
      "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3",
      "description": "Payment for Q4 2025 development work"
    }
  }
}

​
Updating a resource

To update a resource, send a PUT request with only the fields you want to change inside attributes. Omitted fields remain unchanged.
The Natural API uses PUT for partial updates — only the fields you include are modified.
// PUT /api/agents/{agentId}
{
  "data": {
    "attributes": {
      "name": "Carrier Payment Agent v3.0",
      "status": "ACTIVE"
    }
  }
}

​
Responses

Responses follow the JSON:API specification. Resources may be singular or be comprised of lists, and each resource in a response has:
  • type — A string identifying the kind of resource (e.g., "agent", "payment", "transaction")
  • id — A unique prefixed identifier (e.g., agt_019cd179..., pay_019cd179...)
  • attributes — The resource’s data fields
  • relationships (optional) — Links to related resources

​
Single resource

Responses for a single resource wrap the resource in a data object: 
{
  "data": {
    "type": "agent",
    "id": "agt_019cd1798d637a4da75dce386343931d",
    "attributes": {
      "name": "Carrier Payment Agent v2.1",
      "description": "Autonomous agent that pays delivery carriers",
      "status": "ACTIVE",
      "createdAt": "2026-01-04T15:30:00Z",
      "createdBy": "usr_019cd1798d657de5b5fed4198cb9fac0",
      "updatedAt": "2026-01-04T15:30:00Z",
      "updatedBy": "usr_019cd1798d657de5b5fed4198cb9fac0"
    },
    "relationships": {
      "party": {
        "data": {
          "type": "party",
          "id": "pty_019cd1798d617f65a79cb965dda9eac3"
        }
      }
    }
  }
}

​
List of resources

List endpoints return an array of resources in data, with pagination metadata in meta: 
{
  "data": [
    {
      "type": "transaction",
      "id": "txn_019cd1798d6672a7b828eee780291b72",
      "attributes": {
        "amount": 100000,
        "currency": "USD",
        "status": "COMPLETED",
        "transactionType": "payment",
        "category": "sent",
        "direction": "OUTBOUND",
        "createdAt": "2026-01-04T15:30:00Z"
      },
      "relationships": {
        "sourceParty": {
          "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
        },
        "destinationParty": {
          "data": { "type": "party", "id": "pty_019cd1798d627ad9bc302511c4f2c115" }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "hasMore": false,
      "nextCursor": null
    }
  }
}
Use the nextCursor value from meta.pagination to fetch subsequent pages.

​
Relationships

Relationships connect resources to each other without nesting the full related resource. Each relationship contains a data object with the related resource’s type and id. Relationships appear only in responses. In requests, reference related resources by including their ID directly in attributes (e.g., customerPartyId).

​
To-one relationships

A to-one relationship links to a single related resource: 
"customerParty": {
  "data": {
    "type": "party",
    "id": "pty_019cd1798d617f65a79cb965dda9eac3"
  }
}
A null value in data indicates the relationship is absent: 
"counterparty": {
  "data": null
}

​
Common relationships

RelationshipDescriptionFound on
partyOwning partyAgents, Wallet Balances
customerPartyParty making the paymentPayments, Transactions
counterpartyParty receiving the paymentPayments
sourcePartyOriginating partyTransactions
destinationPartyReceiving partyTransactions
sourceWalletOriginating walletTransactions
destinationWalletReceiving walletTransactions

​
Using relationship IDs

Use the type and id from a relationship to fetch the related resource. For example, if a payment response includes: 
"relationships": {
  "customerParty": {
    "data": { "type": "party", "id": "pty_019cd1798d617f65a79cb965dda9eac3" }
  }
}
You can look up the party using its ID in a subsequent request.

​
Glossary

  • Resource — An entity in the Natural API, such as a payment, agent, or transaction.
  • Attribute — A piece of information about a resource (e.g., status, amount, createdAt).
  • Relationship — A link from one resource to another, represented by type and id.