Create an agent

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Payroll Automation Agent",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "policy": {
    "permissions": [],
    "spendingLimits": {
      "currency": "USD",
      "perTransactionLimit": 50000,
      "dailyLimit": 500000,
      "dailyTransactionLimit": 10,
      "monthlyLimit": 5000000
    },
    "accountRestrictions": {
      "allowedAccountIds": [
        "Account:019542f5-b3e7-1d02-0000-000000000001"
      ],
      "accountRules": [
        {
          "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
          "perTransactionLimit": 10000
        }
      ]
    },
    "approvalThresholds": {
      "currency": "USD",
      "amount": 100000
    }
  },
  "actingFor": "member_8f2c1a",
  "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Payroll Automation Agent',
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    policy: {
      permissions: [],
      spendingLimits: {
        currency: 'USD',
        perTransactionLimit: 50000,
        dailyLimit: 500000,
        dailyTransactionLimit: 10,
        monthlyLimit: 5000000
      },
      accountRestrictions: {
        allowedAccountIds: ['Account:019542f5-b3e7-1d02-0000-000000000001'],
        accountRules: [
          {
            accountId: 'Account:019542f5-b3e7-1d02-0000-000000000001',
            perTransactionLimit: 10000
          }
        ]
      },
      approvalThresholds: {currency: 'USD', amount: 100000}
    },
    actingFor: 'member_8f2c1a',
    spendingPoolId: 'SpendingPool:019542f5-b3e7-1d02-0000-000000000007'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"name\": \"Payroll Automation Agent\",\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"policy\": {\n    \"permissions\": [],\n    \"spendingLimits\": {\n      \"currency\": \"USD\",\n      \"perTransactionLimit\": 50000,\n      \"dailyLimit\": 500000,\n      \"dailyTransactionLimit\": 10,\n      \"monthlyLimit\": 5000000\n    },\n    \"accountRestrictions\": {\n      \"allowedAccountIds\": [\n        \"Account:019542f5-b3e7-1d02-0000-000000000001\"\n      ],\n      \"accountRules\": [\n        {\n          \"accountId\": \"Account:019542f5-b3e7-1d02-0000-000000000001\",\n          \"perTransactionLimit\": 10000\n        }\n      ]\n    },\n    \"approvalThresholds\": {\n      \"currency\": \"USD\",\n      \"amount\": 100000\n    }\n  },\n  \"actingFor\": \"member_8f2c1a\",\n  \"spendingPoolId\": \"SpendingPool:019542f5-b3e7-1d02-0000-000000000007\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "agent": {
    "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "name": "Payroll Automation Agent",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "isPaused": false,
    "isConnected": true,
    "policy": {
      "permissions": [
        "VIEW_TRANSACTIONS"
      ],
      "defaultExecutionMode": "AUTO",
      "spendingLimits": {
        "currency": "USD",
        "perTransactionLimit": 50000,
        "dailyLimit": 500000,
        "dailyTransactionLimit": 10,
        "monthlyLimit": 5000000
      },
      "accountRestrictions": {
        "allowedAccountIds": [
          "Account:019542f5-b3e7-1d02-0000-000000000001"
        ],
        "accountRules": [
          {
            "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
            "executionMode": "AUTO",
            "perTransactionLimit": 10000
          }
        ]
      },
      "approvalThresholds": {
        "currency": "USD",
        "amount": 100000
      }
    },
    "usage": {
      "dailyTransactionCount": 3,
      "dailySpend": 150000,
      "monthlySpend": 750000,
      "dailyResetDate": "2025-07-22",
      "monthlyResetMonth": "2025-08"
    },
    "createdAt": "2025-07-21T17:32:28Z",
    "updatedAt": "2025-07-21T17:32:28Z",
    "actingFor": "member_8f2c1a",
    "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
  },
  "deviceCode": {
    "code": "jqzJR3AgI9OAwb_enypARw",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "expiresAt": "2025-07-22T17:32:28Z",
    "redeemed": false
  }
}

{
  "agent": {
    "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "name": "Payroll Automation Agent",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "isPaused": false,
    "isConnected": true,
    "policy": {
      "permissions": [
        "VIEW_TRANSACTIONS"
      ],
      "defaultExecutionMode": "AUTO",
      "spendingLimits": {
        "currency": "USD",
        "perTransactionLimit": 50000,
        "dailyLimit": 500000,
        "dailyTransactionLimit": 10,
        "monthlyLimit": 5000000
      },
      "accountRestrictions": {
        "allowedAccountIds": [
          "Account:019542f5-b3e7-1d02-0000-000000000001"
        ],
        "accountRules": [
          {
            "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
            "executionMode": "AUTO",
            "perTransactionLimit": 10000
          }
        ]
      },
      "approvalThresholds": {
        "currency": "USD",
        "amount": 100000
      }
    },
    "usage": {
      "dailyTransactionCount": 3,
      "dailySpend": 150000,
      "monthlySpend": 750000,
      "dailyResetDate": "2025-07-22",
      "monthlyResetMonth": "2025-08"
    },
    "createdAt": "2025-07-21T17:32:28Z",
    "updatedAt": "2025-07-21T17:32:28Z",
    "actingFor": "member_8f2c1a",
    "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
  },
  "deviceCode": {
    "code": "jqzJR3AgI9OAwb_enypARw",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "expiresAt": "2025-07-22T17:32:28Z",
    "redeemed": false
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Agent Management

Create an agent

Create a new agent with a specified policy. Returns the created agent and a device code that must be redeemed by the agent software to complete installation.

Agents of a BUSINESS customer are available only where the platform enables them, and require actingFor to name the person the agent acts for. Until the business’s KYB status is APPROVED, its agents’ sends and deposits are held to the same limits as an unverified individual’s, counted across the whole business.

Send an Idempotency-Key header to make retries safe: a request carrying a key already used returns the agent the first request created, with a 200 instead of a 201 and a new device code that replaces any unredeemed one. The request is compared with the agent as it is now, so reusing a key with a different customer, name, policy, actingFor or spendingPoolId, after the agent’s policy or pool was changed, for an agent that was deleted, or for one already connected is rejected with 409. Without a key a retry cannot be recognised, so each request creates its own agent.

POST

agents

Create an agent

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Payroll Automation Agent",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "policy": {
    "permissions": [],
    "spendingLimits": {
      "currency": "USD",
      "perTransactionLimit": 50000,
      "dailyLimit": 500000,
      "dailyTransactionLimit": 10,
      "monthlyLimit": 5000000
    },
    "accountRestrictions": {
      "allowedAccountIds": [
        "Account:019542f5-b3e7-1d02-0000-000000000001"
      ],
      "accountRules": [
        {
          "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
          "perTransactionLimit": 10000
        }
      ]
    },
    "approvalThresholds": {
      "currency": "USD",
      "amount": 100000
    }
  },
  "actingFor": "member_8f2c1a",
  "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Payroll Automation Agent',
    customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
    policy: {
      permissions: [],
      spendingLimits: {
        currency: 'USD',
        perTransactionLimit: 50000,
        dailyLimit: 500000,
        dailyTransactionLimit: 10,
        monthlyLimit: 5000000
      },
      accountRestrictions: {
        allowedAccountIds: ['Account:019542f5-b3e7-1d02-0000-000000000001'],
        accountRules: [
          {
            accountId: 'Account:019542f5-b3e7-1d02-0000-000000000001',
            perTransactionLimit: 10000
          }
        ]
      },
      approvalThresholds: {currency: 'USD', amount: 100000}
    },
    actingFor: 'member_8f2c1a',
    spendingPoolId: 'SpendingPool:019542f5-b3e7-1d02-0000-000000000007'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"name\": \"Payroll Automation Agent\",\n  \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\",\n  \"policy\": {\n    \"permissions\": [],\n    \"spendingLimits\": {\n      \"currency\": \"USD\",\n      \"perTransactionLimit\": 50000,\n      \"dailyLimit\": 500000,\n      \"dailyTransactionLimit\": 10,\n      \"monthlyLimit\": 5000000\n    },\n    \"accountRestrictions\": {\n      \"allowedAccountIds\": [\n        \"Account:019542f5-b3e7-1d02-0000-000000000001\"\n      ],\n      \"accountRules\": [\n        {\n          \"accountId\": \"Account:019542f5-b3e7-1d02-0000-000000000001\",\n          \"perTransactionLimit\": 10000\n        }\n      ]\n    },\n    \"approvalThresholds\": {\n      \"currency\": \"USD\",\n      \"amount\": 100000\n    }\n  },\n  \"actingFor\": \"member_8f2c1a\",\n  \"spendingPoolId\": \"SpendingPool:019542f5-b3e7-1d02-0000-000000000007\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "agent": {
    "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "name": "Payroll Automation Agent",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "isPaused": false,
    "isConnected": true,
    "policy": {
      "permissions": [
        "VIEW_TRANSACTIONS"
      ],
      "defaultExecutionMode": "AUTO",
      "spendingLimits": {
        "currency": "USD",
        "perTransactionLimit": 50000,
        "dailyLimit": 500000,
        "dailyTransactionLimit": 10,
        "monthlyLimit": 5000000
      },
      "accountRestrictions": {
        "allowedAccountIds": [
          "Account:019542f5-b3e7-1d02-0000-000000000001"
        ],
        "accountRules": [
          {
            "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
            "executionMode": "AUTO",
            "perTransactionLimit": 10000
          }
        ]
      },
      "approvalThresholds": {
        "currency": "USD",
        "amount": 100000
      }
    },
    "usage": {
      "dailyTransactionCount": 3,
      "dailySpend": 150000,
      "monthlySpend": 750000,
      "dailyResetDate": "2025-07-22",
      "monthlyResetMonth": "2025-08"
    },
    "createdAt": "2025-07-21T17:32:28Z",
    "updatedAt": "2025-07-21T17:32:28Z",
    "actingFor": "member_8f2c1a",
    "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
  },
  "deviceCode": {
    "code": "jqzJR3AgI9OAwb_enypARw",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "expiresAt": "2025-07-22T17:32:28Z",
    "redeemed": false
  }
}

{
  "agent": {
    "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "name": "Payroll Automation Agent",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "isPaused": false,
    "isConnected": true,
    "policy": {
      "permissions": [
        "VIEW_TRANSACTIONS"
      ],
      "defaultExecutionMode": "AUTO",
      "spendingLimits": {
        "currency": "USD",
        "perTransactionLimit": 50000,
        "dailyLimit": 500000,
        "dailyTransactionLimit": 10,
        "monthlyLimit": 5000000
      },
      "accountRestrictions": {
        "allowedAccountIds": [
          "Account:019542f5-b3e7-1d02-0000-000000000001"
        ],
        "accountRules": [
          {
            "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
            "executionMode": "AUTO",
            "perTransactionLimit": 10000
          }
        ]
      },
      "approvalThresholds": {
        "currency": "USD",
        "amount": 100000
      }
    },
    "usage": {
      "dailyTransactionCount": 3,
      "dailySpend": 150000,
      "monthlySpend": 750000,
      "dailyResetDate": "2025-07-22",
      "monthlyResetMonth": "2025-08"
    },
    "createdAt": "2025-07-21T17:32:28Z",
    "updatedAt": "2025-07-21T17:32:28Z",
    "actingFor": "member_8f2c1a",
    "spendingPoolId": "SpendingPool:019542f5-b3e7-1d02-0000-000000000007"
  },
  "deviceCode": {
    "code": "jqzJR3AgI9OAwb_enypARw",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
    "expiresAt": "2025-07-22T17:32:28Z",
    "redeemed": false
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Headers

Idempotency-Key

string

A unique identifier for the request. A retry with the same key returns the agent the first request created rather than creating a second one.

Maximum string length: 255

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

name

string

required

Human-readable name to identify the agent.

Example:

"Payroll Automation Agent"

customerId

string

required

The ID of the customer this agent will operate on behalf of.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

policy

object

required

Policy governing what an agent can do, how it executes actions, and its spending boundaries.

Show child attributes

actingFor

string

The platform's own reference for the person this agent acts for, such as a member id within a business. Grid stores it as given, never interprets it, and copies it onto every card the agent is issued, for audit and screening. Required when the customer is a BUSINESS, where agents are available only where the platform enables them for business customers; optional for an INDIVIDUAL. It cannot be changed after the agent is created.

Required string length: 1 - 255

Example:

"member_8f2c1a"

spendingPoolId

string

A spending pool of the same customer to put the agent in, where the platform enables spending pools. The agent's policy must be in the pool's currency.

Example:

"SpendingPool:019542f5-b3e7-1d02-0000-000000000007"

Response

The Idempotency-Key was already used for this request: the agent the first request created, with a new device code

Response returned when an agent is created, including the agent and a device code for installation.

agent

object

required

A programmatic agent with scoped permissions and a spending policy, used to automate payment workflows.

Show child attributes

deviceCode

object

required

Show child attributes

Using the API

API documentation

Create an agent

Authorizations

Headers

Body

Response