Contributor operations

Mass payouts API for contractors in 100+ countries

A mass payouts API lets you pay hundreds or thousands of contractors in one run from your own platform. Toku’s API takes a batch of contractor invoices, with a line per task type or bonus, and pays each person in their local currency or in USDC or USDT in 100+ countries, on a schedule or on demand.

Toku also signs the contractor agreements and IP transfers when you need it, which payout-only platforms leave to you. This page covers how the API fits a contributor platform, and what to check for global and bulk payouts.

Toku · Last reviewed

What Toku’s mass payouts API does

Global payouts at volume need more than a transfer endpoint. Toku’s API covers the steps around the money as well, so a payout is tied to a signed agreement, a verified contributor and the work it pays for.

  • Bulk invoice submission: one request carries many contractors’ invoices, each with line items such as accepted tasks and bonuses.
  • Any cadence: monthly, every two weeks, weekly or on demand mid-cycle, from a balance you top up.
  • Local currency or stablecoins: each contractor chooses a local bank account or USDC or USDT to a wallet.
  • Contracts and IP: Toku can sign as contractor or agent of record and collect an IP transfer that is valid in each contractor’s country.
  • Onboarding in your product: identity checks, agreement signing and payout setup through the API or MCP connections.
  • Reconciliation: every payout stays matched to its invoice, contractor and agreement for finance and audits.

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.

Mass payouts API or payout platform?

Payout platforms such as Tipalti, Trolley, Payoneer and PayPal Payouts move money in bulk, and some collect tax forms, while the contracts and IP stay with you. HR platforms such as Deel and Remote add contracts but charge a monthly fee for each contractor. Toku combines bulk payouts with the contract and a country-specific IP transfer, priced on the contributors you pay.

Our comparison of mass payout platforms lists each provider’s published prices and payout options, with sources.

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.

General information for teams planning contributor programs. Classification, tax, payment eligibility, and data obligations depend on the actual arrangement and applicable local requirements.

Questions teams ask

No. Submission and final receipt are different states. Confirm the settlement and reconciliation workflow for your integration.
Toku supports a headless product and API/MCP connections. Confirm the specific onboarding, agreement, verification, and payment interfaces for your implementation.
A mass payout is one payment run that pays many recipients at once, such as contractors, contributors or creators, usually through an API or a file upload. Toku runs mass payouts to contractors in 100+ countries in local currency or USDC and USDT.
Collect each contractor’s invoice or earnings, submit them as one batch through a provider’s API or file upload, fund the run and track each payout. Toku takes bulk invoices through its API and pays each contractor in local currency or stablecoins.
Toku’s API pays contractors in USDC or USDT as a standard option alongside local bank transfers, so each contractor can choose how to be paid.