Authenticate and make your first request

Every Wafeq request uses an organization-scoped API key. Start by retrieving the organization, then list the accounts available to your integration.

1. Create and protect an API key

Create the key from the Wafeq application for the organization you want to connect.

Send it in the Authorization header:

Authorization: Api-Key <API_KEY>

Treat the key like a password:

Store it in a server-side secret manager.
Do not put it in frontend, mobile, analytics, or log payloads.
Use separate keys for separate environments or organizations.
Rotate it if it is exposed.

2. Verify the connected organization

Call Retrieve organization:

curl "https://api.wafeq.com/v1/organization/" \
  --header "Authorization: Api-Key <API_KEY>" \
  --header "Accept: application/json"

A successful 200 response confirms that the key is valid and identifies the organization behind it. Persist the organization identity next to the connection in your system so records are never sent to the wrong tenant.

3. Retrieve accounting IDs

Accounting documents reference other Wafeq records by ID. A useful first request is List accounts:

curl "https://api.wafeq.com/v1/accounts/?page_size=100" \
  --header "Authorization: Api-Key <API_KEY>" \
  --header "Accept: application/json"

To find accounts that can receive or pay money, add is_payment_enabled=true:

curl "https://api.wafeq.com/v1/accounts/?is_payment_enabled=true&page_size=100" \
  --header "Authorization: Api-Key <API_KEY>"

You will commonly need IDs from:

Pagination

List endpoints return count, next, previous, and results. Continue requesting the URL in next until it is null. Do not assume that the first page contains every record.

Use page_size to control page size and page only when you need direct page navigation.

Common responses

Status	Meaning	What to do
200 or 201	Request succeeded	Store the returned Wafeq ID
400	Request could not be validated	Read the field-level error and correct the payload
401	Key is missing or invalid	Check the header and rotate the key if necessary
403	The key cannot perform this operation	Check organization access and feature availability
404	The object does not exist in this organization	Verify the ID and tenant mapping
429	Too many requests	Back off and retry according to the response
5xx	Temporary server failure	Retry safely with backoff and idempotency

Before creating data

For POST requests that expose the header, send a unique X-Wafeq-Idempotency-Key. Reuse the same value only when retrying the same logical operation.

Next, choose an end-to-end workflow: