Allocora
Docs / Payee API Endpoints

API Reference

Payee API endpoints

Use payee endpoints to automate recipient records, contact details, hold status, payout thresholds, fallback percentages, and Contract Economics V1 fields.

Start Free Try Sample Data

Details

What to know

Payee object

A payee represents a recipient that can receive allocations from payout rules.

  • Use external_id to connect Allocora payees to your source system.
  • Use type values individual, company, affiliate, or agency.
  • Use status values active, inactive, or pending.
  • Use hold fields when a recipient should be reviewed before payout.
  • Use contract economics fields for opening balances, recoupable advances, recoupable expenses, reserves, and clawback balances that should be applied after gross allocation math.

Endpoint Examples

Requests and responses

Each example shows the request shape and a shortened successful response. Replace placeholder IDs with values from your workspace.

GET /api/v1/payees

List payees

Returns payees available to the API key workspace.

  • Requires read:payees.

Request example

curl -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  https://www.allocora.com/api/v1/payees

Response example

{
  "data": [
    {
      "id": "<PAYEE_ID>",
      "external_id": "partner_001",
      "name": "Northwind Partner",
      "type": "affiliate",
      "status": "active",
      "minimum_payout_threshold": "100.000",
      "recoupable_advance": "250.000",
      "reserve_percent": "5.50"
    }
  ]
}
GET /api/v1/payees/{id}

Retrieve a payee

Returns one payee by ID.

  • Requires read:payees.

Request example

curl -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  https://www.allocora.com/api/v1/payees/<PAYEE_ID>

Response example

{
  "data": {
    "id": "<PAYEE_ID>",
    "external_id": "partner_001",
    "name": "Northwind Partner",
    "type": "affiliate",
    "status": "active",
    "contact_email": "[email protected]",
    "minimum_payout_threshold": "100.000",
    "opening_balance": "0.000",
    "recoupable_advance": "250.000",
    "recoupable_expenses": "40.000",
    "reserve_percent": "5.50",
    "clawback_balance": "0.000",
    "economics_notes": "Advance recoups before reserves."
  }
}
POST /api/v1/payees

Create a payee

Creates one payee.

  • Requires write:payees.
  • external_id is optional but recommended for future upserts.

Request example

curl -X POST https://www.allocora.com/api/v1/payees \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "partner_001",
    "name": "Northwind Partner",
    "type": "affiliate",
    "status": "active",
    "contact_email": "[email protected]",
    "recoupable_advance": "250.000",
    "reserve_percent": "5.50",
    "economics_notes": "Advance recoups before reserves."
  }'

Response example

{
  "data": {
    "id": "<PAYEE_ID>",
    "external_id": "partner_001",
    "name": "Northwind Partner",
    "type": "affiliate",
    "status": "active",
    "recoupable_advance": "250.000",
    "reserve_percent": "5.50"
  }
}
POST /api/v1/payees/upsert

Upsert a payee

Creates or updates one payee by external_id.

  • Requires write:payees.
  • operation must be create_only, update_only, or create_or_update.

Request example

curl -X POST https://www.allocora.com/api/v1/payees/upsert \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "partner_001",
    "operation": "create_or_update",
    "name": "Northwind Partner",
    "type": "affiliate",
    "status": "active",
    "recoupable_expenses": "40.000",
    "clawback_balance": "10.000"
  }'

Response example

{
  "data": {
    "id": "<PAYEE_ID>",
    "external_id": "partner_001",
    "name": "Northwind Partner",
    "type": "affiliate",
    "status": "active",
    "recoupable_expenses": "40.000",
    "clawback_balance": "10.000"
  }
}
POST /api/v1/payees/batch

Create payees in batch

Creates up to 100 payees in one request.

  • Requires write:payees.
  • Each record uses the same fields as create payee.

Request example

curl -X POST https://www.allocora.com/api/v1/payees/batch \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "external_id": "partner_001",
        "name": "Northwind Partner",
        "type": "affiliate"
      }
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 201,
      "response": {
        "data": {"id": "<PAYEE_ID>", "external_id": "partner_001"}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}
POST /api/v1/payees/batch/upsert

Upsert payees in batch

Creates or updates up to 100 payees by external_id.

  • Requires write:payees.
  • Each record must include external_id and operation.

Request example

curl -X POST https://www.allocora.com/api/v1/payees/batch/upsert \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "external_id": "partner_001",
        "operation": "create_or_update",
        "name": "Northwind Partner",
        "type": "affiliate"
      }
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 200,
      "response": {
        "data": {"id": "<PAYEE_ID>", "external_id": "partner_001"}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}
PUT /api/v1/payees/{id}

Update a payee

Updates one payee by ID.

  • Requires write:payees.
  • Send only the fields you want to change.

Request example

curl -X PUT https://www.allocora.com/api/v1/payees/<PAYEE_ID> \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive",
    "hold_status": "on_hold",
    "hold_reason": "Missing tax form",
    "minimum_payout_threshold": "100.000",
    "opening_balance": "25.000"
  }'

Response example

{
  "data": {
    "id": "<PAYEE_ID>",
    "external_id": "partner_001",
    "name": "Northwind Partner",
    "status": "inactive",
    "hold_status": "on_hold",
    "hold_reason": "Missing tax form",
    "minimum_payout_threshold": "100.000",
    "opening_balance": "25.000"
  }
}
PUT /api/v1/payees/batch

Update payees in batch

Updates up to 100 payees by ID.

  • Requires write:payees.
  • Each record must include id.

Request example

curl -X PUT https://www.allocora.com/api/v1/payees/batch \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"id": "<PAYEE_ID>", "status": "inactive"}
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 200,
      "response": {
        "data": {"id": "<PAYEE_ID>", "status": "inactive"}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}

Reference Tables

Fields and checks

Common payee fields

These fields appear in payee create, update, and response examples.

Field Type Notes
id string Allocora payee ID returned by the API.
external_id string or null Your stable payee identifier.
name string Display name for the payee.
type string individual, company, affiliate, or agency.
status string active, inactive, or pending.
contact_email string or null Optional payee contact email.
default_fallback_percent decimal or null Optional fallback percentage for rule workflows.
minimum_payout_threshold decimal or null Optional minimum payout amount.
opening_balance decimal or null Optional opening balance to recoup before net payable.
recoupable_advance decimal or null Optional advance balance to recoup.
recoupable_expenses decimal or null Optional expense balance to recoup.
reserve_percent decimal or null Optional reserve holdback percent from 0 to 100.
clawback_balance decimal or null Optional existing clawback/refund balance to apply.
economics_notes string or null Internal note explaining the configured economics terms.

Feedback

Was this page helpful?

Send a note if a step is unclear, missing, or out of date.

Email Support

Apply this in a workspace

Start free, use sample data, then replace examples with your own revenue rows when the workflow is clear.

Start Free Browse Docs