فوتّر Customers API
بيانات العملاء وأرقامهم الضريبية والعنوان الوطني.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fawtar-app:fawtar-app-customers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Fawtar Business Customers API
x-capabilities: https://fawtar.app/.well-known/fawtar-capabilities.json
version: 1.0.0
description: 'Arabic-first invoicing, accounting, payroll and point of sale for Saudi businesses. Invoice QR fields do not establish full system compliance or Phase 2 integration. Filtering and sorting follow ransack conventions, and the API-KEY header is accepted alongside Authorization: Bearer, so a client written against Qoyod can be repointed here by changing the base URL and the key. Agent capabilities, sandbox onboarding and prepaid prices: https://fawtar.app/.well-known/fawtar-capabilities.json'
contact:
name: Fawtar
url: https://fawtar.app/docs/api
servers:
- url: https://fawtar.app
security:
- bearerAuth: []
tags:
- name: Customers
description: بيانات العملاء وأرقامهم الضريبية والعنوان الوطني.
paths:
/api/v1/customers:
get:
operationId: listCustomers
tags:
- Customers
summary: List customers
description: بيانات العملاء وأرقامهم الضريبية والعنوان الوطني.
security:
- bearerAuth:
- customers:read
- apiKeyHeader: []
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: q[s]
in: query
description: 'Sort, e.g. "name desc". Sortable: name, created_at, city'
schema:
type: string
- name: q[field_predicate]
in: query
description: 'Ransack-style filter. Filterable fields: name, vat_number, cr_number, email, phone, city, created_at. Predicates: eq, not_eq, cont, start, end, gt, gteq, lt, lteq, in, null.'
schema:
type: string
responses:
'200':
description: A page of results
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
meta:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: خطأ غير متوقع من جانبنا.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: createCustomer
tags:
- Customers
summary: Create a customer
security:
- bearerAuth:
- customers:write
- apiKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
name:
type: string
minLength: 1
maxLength: 200
vat_number:
type: string
maxLength: 30
cr_number:
type: string
maxLength: 30
email:
type: string
maxLength: 254
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
phone:
type: string
maxLength: 30
address:
type: string
maxLength: 500
street:
type: string
maxLength: 120
building:
type: string
maxLength: 40
district:
type: string
maxLength: 120
city:
type: string
maxLength: 120
postal_code:
type: string
maxLength: 20
additional_number:
anyOf:
- type: string
pattern: ^\d{4}$
- type: string
const: ''
country_subentity:
type: string
maxLength: 120
required:
- name
example:
name: Example Company
vat_number: '300000000000003'
cr_number: '1234567890'
street: Main
building: '1234'
district: Business
city: Riyadh
postal_code: '12345'
additional_number: '1234'
country_subentity: Riyadh Region
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
additionalProperties: true
headers:
X-Fawtar-Credits-Remaining:
description: Remaining write credits for agent/sandbox keys; subscription keys are not metered.
schema:
type: integer
minimum: 0
'400':
description: يتطلب إنشاء الإشعار الدائن Idempotency-Key ثابتًا؛ المفتاح المُرسل يجب أن يكون صالحًا في كل عمليات الإنشاء المالية.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Prepaid balance exhausted. Authenticate to POST top_up_url to receive a hosted checkout link.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- error
- code
- balance
- required_credits
- top_up_url
- top_up_method
- pack
properties:
error:
const: payment_required
code:
const: insufficient_credits
balance:
type: integer
minimum: 0
required_credits:
type: integer
minimum: 1
top_up_url:
type: string
format: uri
top_up_method:
const: POST
pack:
type: object
additionalProperties: false
required:
- currency
- price_minor
- credits
- minimum_top_up_minor
properties:
currency:
const: SAR
price_minor:
const: 9900
credits:
const: 1000
minimum_top_up_minor:
const: 9900
example:
error: payment_required
code: insufficient_credits
balance: 0
required_credits: 1
top_up_url: https://fawtar.app/api/v1/credits/top-up
top_up_method: POST
pack:
currency: SAR
price_minor: 9900
credits: 1000
minimum_top_up_minor: 9900
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: استُخدم المفتاح نفسه مع جسم طلب مختلف؛ لا تعِد تنفيذ الحدث بمفتاح جديد.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: فشل التحقق. التفاصيل في details لكل حقل.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: النتيجة غير مؤكدة. أعد الجسم نفسه بالمفتاح نفسه حتى تحصل على المعرّف.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/customers/{id}:
get:
operationId: getCustomer
tags:
- Customers
summary: Fetch one customer
security:
- bearerAuth:
- customers:read
- apiKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: The record
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
operationId: replaceCustomer
tags:
- Customers
summary: Replace one customers
security:
- bearerAuth:
- customers:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Updated
content:
application/json:
schema:
type: object
additionalProperties: true
headers:
X-Fawtar-Credits-Remaining:
description: Remaining write credits for agent/sandbox keys; subscription keys are not metered.
schema:
type: integer
minimum: 0
'400':
description: يتطلب إنشاء الإشعار الدائن Idempotency-Key ثابتًا؛ المفتاح المُرسل يجب أن يكون صالحًا في كل عمليات الإنشاء المالية.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Prepaid balance exhausted. Authenticate to POST top_up_url to receive a hosted checkout link.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- error
- code
- balance
- required_credits
- top_up_url
- top_up_method
- pack
properties:
error:
const: payment_required
code:
const: insufficient_credits
balance:
type: integer
minimum: 0
required_credits:
type: integer
minimum: 1
top_up_url:
type: string
format: uri
top_up_method:
const: POST
pack:
type: object
additionalProperties: false
required:
- currency
- price_minor
- credits
- minimum_top_up_minor
properties:
currency:
const: SAR
price_minor:
const: 9900
credits:
const: 1000
minimum_top_up_minor:
const: 9900
example:
error: payment_required
code: insufficient_credits
balance: 0
required_credits: 1
top_up_url: https://fawtar.app/api/v1/credits/top-up
top_up_method: POST
pack:
currency: SAR
price_minor: 9900
credits: 1000
minimum_top_up_minor: 9900
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: فشل التحقق. التفاصيل في details لكل حقل.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
operationId: updateCustomer
tags:
- Customers
summary: Update one customers
security:
- bearerAuth:
- customers:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Updated
content:
application/json:
schema:
type: object
additionalProperties: true
headers:
X-Fawtar-Credits-Remaining:
description: Remaining write credits for agent/sandbox keys; subscription keys are not metered.
schema:
type: integer
minimum: 0
'400':
description: يتطلب إنشاء الإشعار الدائن Idempotency-Key ثابتًا؛ المفتاح المُرسل يجب أن يكون صالحًا في كل عمليات الإنشاء المالية.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Prepaid balance exhausted. Authenticate to POST top_up_url to receive a hosted checkout link.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- error
- code
- balance
- required_credits
- top_up_url
- top_up_method
- pack
properties:
error:
const: payment_required
code:
const: insufficient_credits
balance:
type: integer
minimum: 0
required_credits:
type: integer
minimum: 1
top_up_url:
type: string
format: uri
top_up_method:
const: POST
pack:
type: object
additionalProperties: false
required:
- currency
- price_minor
- credits
- minimum_top_up_minor
properties:
currency:
const: SAR
price_minor:
const: 9900
credits:
const: 1000
minimum_top_up_minor:
const: 9900
example:
error: payment_required
code: insufficient_credits
balance: 0
required_credits: 1
top_up_url: https://fawtar.app/api/v1/credits/top-up
top_up_method: POST
pack:
currency: SAR
price_minor: 9900
credits: 1000
minimum_top_up_minor: 9900
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: فشل التحقق. التفاصيل في details لكل حقل.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: deleteCustomer
tags:
- Customers
summary: Delete one customers
security:
- bearerAuth:
- customers:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Deleted
headers:
X-Fawtar-Credits-Remaining:
description: Remaining write credits for agent/sandbox keys; subscription keys are not metered.
schema:
type: integer
minimum: 0
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Prepaid balance exhausted. Authenticate to POST top_up_url to receive a hosted checkout link.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- error
- code
- balance
- required_credits
- top_up_url
- top_up_method
- pack
properties:
error:
const: payment_required
code:
const: insufficient_credits
balance:
type: integer
minimum: 0
required_credits:
type: integer
minimum: 1
top_up_url:
type: string
format: uri
top_up_method:
const: POST
pack:
type: object
additionalProperties: false
required:
- currency
- price_minor
- credits
- minimum_top_up_minor
properties:
currency:
const: SAR
price_minor:
const: 9900
credits:
const: 1000
minimum_top_up_minor:
const: 9900
example:
error: payment_required
code: insufficient_credits
balance: 0
required_credits: 1
top_up_url: https://fawtar.app/api/v1/credits/top-up
top_up_method: POST
pack:
currency: SAR
price_minor: 9900
credits: 1000
minimum_top_up_minor: 9900
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: استُخدم المفتاح نفسه مع جسم طلب مختلف؛ لا تعِد تنفيذ الحدث بمفتاح جديد.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
error:
type: string
enum:
- idempotency_key_required
- idempotency_conflict
- document_not_ready
- write_outcome_unknown
- document_render_failed
- invalid_json
- unauthorized
- not_found
- method_not_allowed
- delete_refused
- validation_failed
- rate_limited
- query_failed
message:
type: string
details:
type: object
additionalProperties:
type: array
items:
type: string
required:
- error
securitySchemes:
supabaseSession:
type: http
scheme: bearer
description: Provider-verified Supabase access token, for onboarding claims only.
bearerAuth:
type: http
scheme: bearer
description: 'Authorization: Bearer fwt_live_… or fwt_test_…'
apiKeyHeader:
type: apiKey
in: header
name: API-KEY
description: Qoyod-compatible header carrying the same key.