Mass payouts API for contributor teams

Separate the work ledger from the payment ledger

Keep task acceptance and earnings calculation in your platform. Pass approved invoice records into the payment workflow and store the identifiers needed to reconcile them later. Do not let an API success response overwrite your own evidence of which tasks were approved.

The contributor’s agreement, verification status, and payout setup need to be complete under the agreed process. Define which system is authoritative for each check and what the contributor sees if a step is incomplete.

Submit a documented invoice batch

The endpoint, authorization headers, and request fields below match the public Toku documentation. The identities, dates, and amounts are illustrative. Confirm the invoice identifiers and operational prerequisites with Toku before using production credentials.

The published response indicates submission success. It does not establish bank receipt or final settlement. Never expose API credentials in a browser or contributor-facing application.

// Server-side example using the documented invoice submission endpoint.
// Submitting invoices is not confirmation that recipients have been paid.
const response = await fetch(
  "https://app.toku.com/api/tokuApi/v1/submitBulkInvoicePayments",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TOKU_API_TOKEN}`,
      "x-role-type": "CLIENT_ORG_ADMIN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      submissionTimestamp: new Date().toISOString(),
      invoices: [{
        invoiceID: "example-invoice-001",
        contractorEmail: "contributor@example.com",
        contractorName: "Example Contributor",
        invoiceNumber: "EXAMPLE-001",
        invoiceDate: "2026-10-13",
        dueDate: "2026-10-20",
        totalAmount: 45,
        currencyCode: "USD",
        lineItems: [{
          description: "30 accepted annotation tasks",
          quantity: 30,
          rate: 1.5,
          amount: 45,
          type: "EARNING",
        }],
      }],
    }),
  },
);
if (!response.ok) {
  // Reconcile uncertain outcomes before resubmitting a payment operation.
  throw new Error(`Invoice submission returned ${response.status}`);
}
const result = await response.json();
if (result.success !== true) throw new Error("Submission not confirmed");

Design for incomplete and uncertain outcomes

Before launch, document what happens after a timeout, a rejected record, or a returned payment. Do not automatically retry a money-moving request unless you have established that the first submission did not execute or the provider has documented safe retry semantics.

The public bulk-invoice schema does not establish an idempotency-key contract or a per-invoice settlement response. Confirm duplicate protection, batch limits, partial failures, and the status-reconciliation interface during integration.

• Persist the intended batch and stable invoice references before submitting
• Distinguish validation failure from an unknown outcome
• Restrict the integration credential to the agreed role and organization
• Avoid writing tokens, full identity documents, or unnecessary personal data to logs
• Agree a manual exception process before the first production run

Funding and frequency are part of the design

A task event does not have to produce an immediate bank transfer. Aggregate approved earnings on the agreed schedule, keep bonuses explicit, and ensure the funded balance and approval process cover the planned run.

Test a realistic low-value payment and a failed or corrected payment as well as the happy path. Confirm the contributor’s final net amount rather than looking only at the amount submitted.

Plan the integration with Toku

Bring your countries, active contributor volume, task and bonus structure, and desired payout cadence. Discuss how the API and MCP connections fit your product and which operations are supported for your account.

Compare the amount the contributor can use

Record the sending fee, conversion, any recipient charge, and the final usable amount. Compare the same payment size and timing. A low headline transfer fee does not establish the lowest total cost.