YaqeenDocs
Back to Yaqeen

How-to guide

Load your data

Send owners, stores, payouts and orders with the live feed, or map your own export columns and check with a dry run first.

This guide shows how to load your data into Yaqeen. There are two ways: the feed, which takes rows in Yaqeen's own column names, and a saved mapping, which takes rows in yours. You need an admin session. A key with the ingest scope can use the feed, but only a session can save and run mappings.

Before you start#

Hash every identifier before you send it: national ID, phone, email, bank account and card. Send the 64-character hash, never the raw value. Use the same method every time, so that one bank account always gives one hash. Yaqeen links stores by comparing hashes. The feed does not check the format of a hash, so the check is yours.

Load with the feed#

Send POST /api/v1/ingest/feed/ with a table name and up to 5,000 rows:

bash
curl -X POST https://API/api/v1/ingest/feed/ \
  -H "Authorization: Bearer yq_live_..." -H "Content-Type: application/json" \
  -d '{"table":"payouts","rows":[{"payout_id":"p1","store_id":"s1","iban_hash":"<64 characters>","bank_code":"10","amount":"900.00","fee":"5.00","deposit_date":"2026-11-16"}]}'

The answer is 201 and the counts: {"created": 1, "updated": 0}. A row is created, or updated if its id is already loaded.

Load the tables in this order, because a row must point at a record that is already loaded:

  1. owners, then stores, then customers.
  2. orders, then the tables that belong to an order: refunds, payment_attempts, installments, deliveries, order_items, coupons, order_vat.
  3. payouts, then payout_reviews.
  4. account_events (after customers) and kyb_events (after stores).

For payouts alone, you need owners, stores and payouts.

Which tables to send#

Send these tables for full coverage. The core is owners, stores, customers, orders, refunds, payouts, payment_attempts, account_events and kyb_events. Add installments, deliveries and payout_reviews when you have them.

A table you do not send is not an error. Yaqeen reads a missing table as "no evidence", so a payout can look less risky than it is. Send what you have. The more tables you send, the more Yaqeen can check.

A few tables, such as store bank account changes and order chats, cannot be sent by feed yet. Ask your Yaqeen contact how to load them. A row without a required field is refused, and the answer names the missing fields. The endpoints are in the API reference.

The whole batch is one transaction. If one row fails, nothing loads, and the answer names the row, such as row 0: store s1 is not loaded. Fix the row and send the batch again.

These rules protect payouts that are under review:

  • A payout cannot change store.
  • A payout cannot change while a hold on it is open (409 payout_has_open_hold).
  • The feed never sets a payout's status. Yaqeen sets it when a hold is decided.

Load your own columns with a mapping#

If your export uses other column names, save a mapping once. It says which of your columns fills each Yaqeen field. Send POST /api/v1/ingest/mappings/ (admin only):

json
{ "name": "payouts-export", "table": "payouts",
  "mapping": { "payout_id": "Payout Ref", "store_id": "Shop", "iban_hash": "Bank Hash",
               "bank_code": "=10", "amount": "Net", "fee": "Fee", "deposit_date": "Date" } }

A value that starts with = is fixed text. Here every row gets the bank code 10. The mapping must cover every required field of the table. If it does not, the answer is 400 incomplete_mapping and names the missing fields.

Then send rows in your columns to POST /api/v1/ingest/connect/. The default is a dry run. It runs the whole load, rolls it back and tells you what would happen:

json
{ "mapping": "payouts-export", "rows": [ { "Payout Ref": "p1", "Shop": "s1", "Bank Hash": "<64 characters>", "Net": "900.00", "Fee": "5.00", "Date": "2026-11-16" } ] }
json
{"dry_run":true,"would_create":1,"would_update":0,"problems":[]}

If a row would fail, problems has its code and message, and the counts are 0. When the dry run is clean, add "dry_run": false to load for real. The answer is 201 and {"dry_run":false,"created":1,"updated":0}.

New stores#

For a store that is new to you, use intake instead. Submit an application, mark the papers received, and approve it. Approval creates the owner and the store. See Holds and appeals.

What you see now#

GET /api/v1/payouts/ lists the payouts you loaded, and GET /api/v1/stores/ lists the stores. In Set up your organization, the step data is now done.

If it does not work#

  • 400 bad_row: a row is missing a required field or has a bad value. The message names the row and the field.
  • 400 unknown_store (also unknown_owner, unknown_order): load the record it points at first.
  • 413 too_many_rows: send at most 5,000 rows in one batch.
  • 403: you are not an admin, or your key has no ingest scope.

For more, see Troubleshooting.

Next steps#

Up Down to moveEnter to openEsc to close